@elizaos/plugin-local-inference 2.0.3-beta.2 → 2.0.3-beta.4

package/src/services/voice/ffi-bindings.ts

@@ -23,8 +23,37 @@
  * the UI.
  */
 
+import path from "node:path";
+
 import { VoiceLifecycleError } from "./lifecycle";
 
+/**
+ * Make a directory discoverable by the Win32 DLL loader for this process by
+ * prepending it to PATH (step 6 of the standard DLL search order).
+ *
+ * The fused lib's sibling backends (`ggml*.dll`, `llama*.dll`, `mtmd.dll`) are
+ * staged NEXT TO `elizainference.dll`, but when a DLL is opened by absolute
+ * path the Win32 loader does NOT search that DLL's own directory for its
+ * dependencies — it searches the host EXE's dir, the system dirs, and PATH. So
+ * `dlopen` fails with "error code 126" (a dependent DLL could not be found)
+ * even though the siblings are right there. Linux/macOS don't need this:
+ * `stage-desktop-fused-lib.mjs` bakes a relative rpath (`$ORIGIN` /
+ * `@loader_path`) at link time so the loader resolves siblings from the lib's
+ * own dir. Idempotent; a no-op off win32 and when `dir` is already on PATH.
+ */
+function ensureWin32DllSearchDir(dir: string): void {
+	if (process.platform !== "win32" || !dir) return;
+	const current = process.env.PATH ?? "";
+	const resolved = path.resolve(dir);
+	const already = current
+		.split(path.delimiter)
+		.some((seg) => seg && path.resolve(seg) === resolved);
+	if (already) return;
+	process.env.PATH = current
+		? `${resolved}${path.delimiter}${current}`
+		: resolved;
+}
+
 /**
  * ABI version the JS binding was authored against. Must match the value
  * `eliza_inference_abi_version()` returns at runtime — a mismatch is a
@@ -77,7 +106,7 @@ import { VoiceLifecycleError } from "./lifecycle";
  *     degraded capability: its voice/ASR/VAD/LLM/text surface is unchanged and
  *     Kokoro just probes unsupported on it.
  */
-export const ELIZA_INFERENCE_ABI_VERSION = 12 as const;
+export const ELIZA_INFERENCE_ABI_VERSION = 13 as const;
 
 /** One transcribed word with playback-synced timing (ms from utterance start). */
 export interface AsrWordTiming {
@@ -189,7 +218,7 @@ export type LlmStreamHandle = bigint;
 /**
  * Per-session config handed to `llmStreamOpen`. Mirrors
  * `eliza_llm_stream_config_t` in
- * `native/llama.cpp/tools/omnivoice/include/eliza-inference-ffi.h` (ABI v8).
+ * `native/llama.cpp/tools/omnivoice/include/eliza-inference-ffi.h` (ABI v9).
  */
 export interface LlmStreamConfig {
 	maxTokens: number;
@@ -213,7 +242,7 @@ export interface LlmStreamConfig {
 	 * path. `null`/empty disables grammar constraint.
 	 */
 	gbnfGrammar?: string | null;
-	/** Qwen3-style thinking-tag suppression passthrough (v1 no-op). */
+	/** Thinking-tag suppression passthrough (v1 no-op). */
 	disableThinking?: boolean;
 	/**
 	 * Per-load GPU offload (ABI v8). Number of model layers to place on GPU.
@@ -229,6 +258,8 @@ export interface LlmStreamConfig {
 	cacheTypeK?: string | null;
 	/** KV-cache V quant type name (ABI v8); see `cacheTypeK`. */
 	cacheTypeV?: string | null;
+	/** Runtime context window in tokens (ABI v9). `undefined`/0 uses native fallback. */
+	contextSize?: number;
 }
 
 /**
@@ -645,6 +676,29 @@ export interface ElizaInferenceFfi {
 		maxTextBytes?: number;
 	}): string;
 
+	/* ---- Streaming mmproj vision describe (ABI v13) -------------- */
+
+	/**
+	 * True when this build wires token-by-token vision describe
+	 * (`eliza_inference_describe_image_stream_open`). A <=v12 / vision-off
+	 * library returns false, so the IMAGE_DESCRIPTION handler falls back to the
+	 * buffered {@link describeImage}.
+	 */
+	visionStreamSupported?(): boolean;
+	/**
+	 * Open a streaming vision-describe session: prime an `LlmStreamHandle`'s KV
+	 * with `imageBytes` (raw PNG/JPEG/WebP) + `prompt` through the mmproj at
+	 * `mmprojPath`, then PULL tokens with the existing {@link llmStreamNext} loop
+	 * and release via {@link llmStreamClose} — the same machinery as chat text.
+	 * Throws `VoiceLifecycleError` when the build lacks vision streaming.
+	 */
+	describeImageStreamOpen?(args: {
+		ctx: ElizaInferenceContextHandle;
+		imageBytes: Uint8Array;
+		mmprojPath: string;
+		prompt?: string;
+	}): LlmStreamHandle;
+
 	/* ---- Tokenizer (ABI v9) -------------------------------------- */
 
 	/**
@@ -688,7 +742,7 @@ export interface ElizaInferenceFfi {
 	/**
 	 * Single causal forward pass over `tokens` (a tokenized partial transcript)
 	 * returning the next-token softmax probability of `targetTokenId` (the
-	 * end-of-turn marker, e.g. `<|im_end|>`), plus the argmax next token and its
+	 * end-of-turn marker, e.g. `<end_of_turn>`), plus the argmax next token and its
 	 * probability. Runs on a dedicated scoring context over the loaded text
 	 * model; KV is cleared per call so scores are independent.
 	 */
@@ -1006,6 +1060,21 @@ interface BunFfiSymbols {
 		maxTextBytes: bigint | number,
 		outErr: unknown,
 	) => number;
+	// Streaming mmproj vision describe (ABI v13). Optional — absent on <=v12
+	// builds (the probe then reports unsupported and IMAGE_DESCRIPTION falls back
+	// to the buffered `eliza_inference_describe_image`). `_stream_open` returns an
+	// EliLlmStream* (as a pointer/bigint) primed with the image+prompt KV; the
+	// caller drives the existing `eliza_inference_llm_stream_next` loop and frees
+	// via `eliza_inference_llm_stream_close`.
+	eliza_inference_vision_stream_supported?: () => number;
+	eliza_inference_describe_image_stream_open?: (
+		ctx: bigint,
+		imageBytes: unknown,
+		nBytes: bigint | number,
+		mmprojPath: unknown,
+		prompt: unknown,
+		outErr: unknown,
+	) => bigint;
 	// Tokenizer (ABI v9). Optional — absent on v8 builds.
 	eliza_inference_tokenize_supported?: () => number;
 	eliza_inference_tokenize?: (
@@ -1089,8 +1158,8 @@ interface BunFfiModule {
 		byteOffset?: number,
 		byteLength?: number,
 	): ArrayBuffer;
-	JSCallback: new (
-		fn: (...args: never[]) => unknown,
+	JSCallback: new <F extends (...args: never[]) => unknown>(
+		fn: F,
 		def: { args: number[]; returns: number },
 	) => BunFfiJSCallback;
 }
@@ -1134,6 +1203,11 @@ function bindWithBunFfi(dylibPath: string): ElizaInferenceFfi {
 	}
 	const T = ffi.FFIType;
 
+	// Windows-only: make the fused lib's co-located backends (ggml*/llama*/mtmd
+	// .dll) resolvable before dlopen, which otherwise fails with error 126. See
+	// ensureWin32DllSearchDir for the full rationale.
+	ensureWin32DllSearchDir(path.dirname(dylibPath));
+
 	// All `char *` arguments are typed as T.ptr — Bun's `T.cstring` is a
 	// RETURN-only type for "library hands back a NUL-terminated string".
 	// For inputs we encode UTF-8 to a NUL-terminated Buffer on the JS
@@ -1383,6 +1457,21 @@ function bindWithBunFfi(dylibPath: string): ElizaInferenceFfi {
 			returns: T.i32,
 		},
 	};
+	// Streaming mmproj vision describe (ABI v13): open returns an EliLlmStream*
+	// primed with the image+prompt KV; the caller drives the existing
+	// `eliza_inference_llm_stream_next` loop. Layered on top of the v12 surface;
+	// the cascade peels it when a <=v12 library is loaded (the
+	// `visionStreamSupported()` probe then reports false and IMAGE_DESCRIPTION
+	// falls back to the buffered `eliza_inference_describe_image`).
+	let visionStreamSymbolsAvailable = true;
+	const visionStreamDefs = {
+		eliza_inference_vision_stream_supported: { args: [], returns: T.i32 },
+		eliza_inference_describe_image_stream_open: {
+			// ctx, image_bytes, n_bytes, mmproj_path, prompt, out_error -> EliLlmStream*
+			args: [T.ptr, T.ptr, T.usize, T.ptr, T.ptr, T.ptr],
+			returns: T.ptr,
+		},
+	};
 	const coreDefs = {
 		eliza_inference_abi_version: { args: [], returns: T.cstring },
 		eliza_inference_create: {
@@ -1459,7 +1548,36 @@ function bindWithBunFfi(dylibPath: string): ElizaInferenceFfi {
 	const classifierDefs = { ...speakerDefs, ...diarizDefs };
 	const attempts = [
 		{
-			// Full v12 surface (v11 + the in-process ASR word-timestamp decoder).
+			// Full v13 surface (v12 + token-by-token mmproj vision describe).
+			defs: {
+				...coreDefs,
+				...referenceEncodeDefs,
+				...nativeVadDefs,
+				...wakewordDefs,
+				...classifierDefs,
+				...llmStreamDefs,
+				...llmCapabilityDefs,
+				...textModalitiesDefs,
+				...kokoroDefs,
+				...eotDefs,
+				...timedAsrDefs,
+				...visionStreamDefs,
+			},
+			referenceEncode: true,
+			nativeVad: true,
+			wakeword: true,
+			classifiers: true,
+			llmStream: true,
+			llmCapability: true,
+			textModalities: true,
+			kokoro: true,
+			eot: true,
+			timedAsr: true,
+			visionStream: true,
+		},
+		{
+			// Full v12 surface (v11 + the in-process ASR word-timestamp decoder);
+			// a v12 build lacks the v13 streaming-vision symbols.
 			defs: {
 				...coreDefs,
 				...referenceEncodeDefs,
@@ -1695,6 +1813,8 @@ function bindWithBunFfi(dylibPath: string): ElizaInferenceFfi {
 			eotSymbolsAvailable = (attempt as { eot?: boolean }).eot ?? false;
 			timedAsrSymbolsAvailable =
 				(attempt as { timedAsr?: boolean }).timedAsr ?? false;
+			visionStreamSymbolsAvailable =
+				(attempt as { visionStream?: boolean }).visionStream ?? false;
 			break;
 		} catch (err) {
 			lastOpenError = err;
@@ -1738,6 +1858,7 @@ function bindWithBunFfi(dylibPath: string): ElizaInferenceFfi {
 	// tokenizer), accepted only when those are absent too.
 	const abiOk =
 		reported === String(ELIZA_INFERENCE_ABI_VERSION) ||
+		(reported === "12" && !visionStreamSymbolsAvailable) ||
 		(reported === "11" && !timedAsrSymbolsAvailable) ||
 		(reported === "10" && !eotSymbolsAvailable && !timedAsrSymbolsAvailable) ||
 		(reported === "9" && !kokoroSymbolsAvailable && !eotSymbolsAvailable) ||
@@ -1992,7 +2113,7 @@ function bindWithBunFfi(dylibPath: string): ElizaInferenceFfi {
 			const speakerArg = cstr(speakerPresetId);
 			// (pcm: ptr, n_samples: usize, is_final: i32, user_data: ptr) -> i32
 			const cb = new ffi.JSCallback(
-				((pcmPtr: bigint, nSamples: bigint, isFinal: number) => {
+				(pcmPtr: bigint, nSamples: bigint, isFinal: number) => {
 					const n = Number(nSamples);
 					// Bun delivers the C pointer as a bigint; copy the floats out
 					// before returning — the buffer is the library's, valid only
@@ -2003,7 +2124,7 @@ function bindWithBunFfi(dylibPath: string): ElizaInferenceFfi {
 							: new Float32Array(0);
 					const requestCancel = onChunk({ pcm, isFinal: isFinal !== 0 });
 					return requestCancel === true ? 1 : 0;
-				}) as unknown as (...args: never[]) => unknown,
+				},
 				{
 					args: [T.ptr, T.usize, T.i32, T.ptr],
 					returns: T.i32,
@@ -2139,9 +2260,9 @@ function bindWithBunFfi(dylibPath: string): ElizaInferenceFfi {
 			}
 			// (ev: ptr to EliVerifierEvent, user_data: ptr) -> void
 			const cb = new ffi.JSCallback(
-				((evPtr: bigint) => {
+				(evPtr: bigint) => {
 					cbFn(readVerifierEvent(evPtr, ffi));
-				}) as unknown as (...args: never[]) => unknown,
+				},
 				{ args: [T.ptr, T.ptr], returns: T.void },
 			);
 			const rc = loadedLib.symbols.eliza_inference_set_verifier_callback(
@@ -2567,7 +2688,7 @@ function bindWithBunFfi(dylibPath: string): ElizaInferenceFfi {
 			const err = makeOutErr();
 			// Marshal the config struct into a Buffer. Layout matches
 			// `eliza_llm_stream_config_t` in `eliza-inference-ffi.h`
-			// (8-byte aligned, ABI v8):
+			// (8-byte aligned, ABI v9):
 			//   off  0 : i32  max_tokens
 			//   off  4 : f32  temperature
 			//   off  8 : f32  top_p
@@ -2583,8 +2704,9 @@ function bindWithBunFfi(dylibPath: string): ElizaInferenceFfi {
 			//   off 60 : i32  n_gpu_layers          (ABI v8 — fills old tail pad)
 			//   off 64 : ptr  cache_type_k          (ABI v8)
 			//   off 72 : ptr  cache_type_v          (ABI v8)
-			//   sizeof = 80
-			const buf = Buffer.alloc(80);
+			//   off 80 : i32  context_size          (ABI v9)
+			//   sizeof = 88
+			const buf = Buffer.alloc(88);
 			buf.writeInt32LE(config.maxTokens, 0);
 			buf.writeFloatLE(config.temperature, 4);
 			buf.writeFloatLE(config.topP, 8);
@@ -2621,6 +2743,7 @@ function bindWithBunFfi(dylibPath: string): ElizaInferenceFfi {
 			);
 			buf.writeBigUInt64LE(toPtrBigInt(cacheKArg.ptr), 64);
 			buf.writeBigUInt64LE(toPtrBigInt(cacheVArg.ptr), 72);
+			buf.writeInt32LE(config.contextSize ?? 0, 80);
 			const handle = open(ctx, ffi.ptr(buf), err.ptr);
 			if (isNullPointer(handle)) {
 				const message =
@@ -2858,6 +2981,45 @@ function bindWithBunFfi(dylibPath: string): ElizaInferenceFfi {
 			);
 		},
 
+		/* ---- Streaming mmproj vision describe (ABI v13) ------------ */
+
+		visionStreamSupported(): boolean {
+			const probe = loadedLib.symbols.eliza_inference_vision_stream_supported;
+			return (
+				visionStreamSymbolsAvailable &&
+				typeof probe === "function" &&
+				probe() === 1
+			);
+		},
+
+		describeImageStreamOpen({ ctx, imageBytes, mmprojPath, prompt }) {
+			const open = loadedLib.symbols.eliza_inference_describe_image_stream_open;
+			if (!visionStreamSymbolsAvailable || typeof open !== "function") {
+				throw new VoiceLifecycleError(
+					"kernel-missing",
+					"[ffi-bindings] eliza_inference_describe_image_stream_open is not exported by this build",
+				);
+			}
+			const err = makeOutErr();
+			const mmprojArg = cstr(mmprojPath);
+			const promptArg = cstr(prompt ?? null);
+			const handle = open(
+				ctx,
+				ffi.ptr(imageBytes),
+				BigInt(imageBytes.length),
+				mmprojArg.ptr,
+				promptArg.ptr,
+				err.ptr,
+			);
+			if (isNullPointer(handle)) {
+				const message =
+					takeError(err.buf) ??
+					"[ffi-bindings] eliza_inference_describe_image_stream_open returned NULL with no diagnostic";
+				throw new VoiceLifecycleError("kernel-missing", message);
+			}
+			return handle as LlmStreamHandle;
+		},
+
 		/* ---- Tokenizer (ABI v9) ------------------------------------ */
 
 		tokenizeSupported(): boolean {
@@ -3100,7 +3262,7 @@ function bindWithBunFfi(dylibPath: string): ElizaInferenceFfi {
 		if (typeof value === "bigint") return value;
 		if (typeof value === "number") return BigInt(value);
 		// Bun returns its internal pointer object that coerces to bigint.
-		return BigInt(value as unknown as number);
+		return BigInt(value as number);
 	}
 
 	/**

package/src/services/voice/fused-eot-scorer.ts

@@ -2,9 +2,9 @@
  * Fused FFI end-of-turn scorer (ABI v11).
  *
  * The fused replacement for the retired node-llama-cpp `controlledEvaluate()`
- * path the EOT classifiers depended on. Computes P(`<|im_end|>` next | partial
+ * path the EOT classifiers depended on. Computes P(`<end_of_turn>` next | partial
  * transcript) through the single `libelizainference` handle: tokenize the
- * Qwen-formatted partial transcript, then one causal forward pass
+ * Gemma-formatted partial transcript, then one causal forward pass
  * (`eliza_inference_llm_eot_score`) reads the next-token probability of the
  * end-of-turn marker. No separate model weights, no sampling loop, and no KV
  * growth on the chat session — the dedicated native scoring context clears its
@@ -17,7 +17,7 @@ import type {
 	ElizaInferenceFfi,
 } from "./ffi-bindings";
 
-const IM_END_TOKEN = "<|im_end|>";
+const END_OF_TURN_TOKEN = "<end_of_turn>";
 
 export interface FfiEotScorerOptions {
 	/** The loaded fused inference binding (must expose the v11 EOT symbols). */
@@ -31,7 +31,7 @@ export interface FfiEotScorerOptions {
 }
 
 export interface FfiEotScoreResult {
-	/** Probability of `<|im_end|>` as the next token, ∈ [0, 1]. */
+	/** Probability of `<end_of_turn>` as the next token, ∈ [0, 1]. */
 	probability: number;
 	/** Wall-clock model latency for this scoring call. */
 	latencyMs: number;
@@ -40,7 +40,7 @@ export interface FfiEotScoreResult {
 }
 
 /**
- * Stateful EOT scorer bound to a loaded fused text model. The `<|im_end|>`
+ * Stateful EOT scorer bound to a loaded fused text model. The `<end_of_turn>`
  * token id is resolved once and cached. Safe to keep across many voice turns.
  */
 export class FfiEotScorer {
@@ -48,7 +48,7 @@ export class FfiEotScorer {
 	private readonly getContext: () => ElizaInferenceContextHandle;
 	private readonly maxHistoryTokens: number;
 	readonly modelLabel: string;
-	private imEndTokenId: number | null = null;
+	private endOfTurnTokenId: number | null = null;
 
 	constructor(options: FfiEotScorerOptions) {
 		this.ffi = options.ffi;
@@ -71,25 +71,25 @@ export class FfiEotScorer {
 		);
 	}
 
-	private resolveImEnd(ctx: ElizaInferenceContextHandle): number {
-		if (this.imEndTokenId !== null) return this.imEndTokenId;
+	private resolveEndOfTurn(ctx: ElizaInferenceContextHandle): number {
+		if (this.endOfTurnTokenId !== null) return this.endOfTurnTokenId;
 		const tokenize = this.ffi.tokenize;
 		if (!tokenize) {
 			throw new Error("[voice] FfiEotScorer: fused tokenizer is unavailable.");
 		}
 		const ids = tokenize({
 			ctx,
-			text: IM_END_TOKEN,
+			text: END_OF_TURN_TOKEN,
 			addSpecial: false,
 			parseSpecial: true,
 		});
 		const first = ids[0];
 		if (ids.length !== 1 || first === undefined || !Number.isInteger(first)) {
 			throw new Error(
-				`[voice] FfiEotScorer: tokenizer did not resolve <|im_end|> to a single special token (got ${JSON.stringify([...ids])}). The text bundle must be Qwen-template compatible.`,
+				`[voice] FfiEotScorer: tokenizer did not resolve <end_of_turn> to a single special token (got ${JSON.stringify([...ids])}). The text bundle must be Gemma-template compatible.`,
 			);
 		}
-		this.imEndTokenId = first;
+		this.endOfTurnTokenId = first;
 		return first;
 	}
 
@@ -103,7 +103,7 @@ export class FfiEotScorer {
 				"[voice] FfiEotScorer: fused EOT symbols are unavailable.",
 			);
 		}
-		const imEndId = this.resolveImEnd(ctx);
+		const endOfTurnId = this.resolveEndOfTurn(ctx);
 		const formatted = formatEotPrompt(partialTranscript);
 		const all = tokenize({
 			ctx,
@@ -122,7 +122,11 @@ export class FfiEotScorer {
 				promptTokens: 0,
 			};
 		}
-		const { targetProb } = eotScore({ ctx, tokens, targetTokenId: imEndId });
+		const { targetProb } = eotScore({
+			ctx,
+			tokens,
+			targetTokenId: endOfTurnId,
+		});
 		const probability = Number.isFinite(targetProb)
 			? Math.max(0, Math.min(1, targetProb))
 			: 0.5;

package/src/services/voice/index.ts

@@ -33,6 +33,13 @@ export {
 	type MockCheckpointSnapshot,
 	type MockSnapshotSource,
 } from "./checkpoint-manager";
+export {
+	computeDiarizationErrorRate,
+	type DerOptions,
+	type DerResult,
+	type DiarizationSegment,
+	diarizationWithinBudget,
+} from "./diarization-error-rate";
 export {
 	type BuildDeterministicFn,
 	type BuildMessageDependentFn,
@@ -42,6 +49,20 @@ export {
 	type FullContext,
 	mergeContext,
 } from "./eager-context-builder";
+export {
+	DEFAULT_PLAYBACK_DELAY_MS,
+	type EchoDelayEstimate,
+	type EchoDelayOptions,
+	estimateEchoDelaySamples,
+	PLATFORM_PLAYBACK_DELAY_DEFAULTS,
+	platformPlaybackDelayMs,
+	platformPlaybackDelaySamples,
+} from "./echo-delay";
+export { computeErle } from "./echo-metrics";
+export {
+	EchoReferenceBuffer,
+	type EchoReferenceBufferOptions,
+} from "./echo-reference-buffer";
 export type {
 	LlamaContextLike as Eliza1EotLlamaContext,
 	LlamaContextSequenceLike as Eliza1EotLlamaSequence,
@@ -104,13 +125,13 @@ export {
 	type VoiceTurnSignal,
 } from "./eot-classifier";
 export {
-	applyQwenUserTemplate,
+	applyGemmaUserTemplate,
 	createBundledLiveKitGgmlTurnDetector,
 	DEFAULT_LIVEKIT_TURN_DETECTOR_GGML_DIR,
 	DEFAULT_LIVEKIT_TURN_DETECTOR_GGUF_EN,
 	DEFAULT_LIVEKIT_TURN_DETECTOR_GGUF_INTL,
 	EotGgmlUnavailableError,
-	LIVEKIT_IM_END_TOKEN,
+	LIVEKIT_END_OF_TURN_TOKEN,
 	LiveKitGgmlTurnDetector,
 	type LiveKitGgmlTurnDetectorOptions,
 	turnDetectorGgufForTier,
@@ -153,6 +174,10 @@ export {
 	pipeMicToRingBuffer,
 	resolveDesktopRecorder,
 } from "./mic-source";
+export {
+	NlmsEchoCanceller,
+	type NlmsEchoCancellerOptions,
+} from "./nlms-echo-canceller";
 export {
 	DEFAULT_OPTIMISTIC_EOT_THRESHOLD,
 	OptimisticGenerationPolicy,
@@ -335,9 +360,9 @@ export * from "./types";
 export {
 	createSileroVadDetector,
 	createVadDetector,
+	type ExternalVadAdapter,
 	GgmlSileroVad,
 	NativeSileroVad,
-	type QwenToolkitVadAdapter,
 	type ResolvedVadProvider,
 	RmsEnergyGate,
 	type RmsEnergyGateConfig,
@@ -371,6 +396,11 @@ export {
 	voiceEnsemblePeakMb,
 	voiceEnsembleSteadyStateMb,
 } from "./voice-budget";
+export {
+	type ArbiterPreloader,
+	VoicePreloadPredictor,
+	type VoicePreloadPredictorOptions,
+} from "./voice-preload-predictor";
 export {
 	readVoicePresetFile,
 	VOICE_PRESET_MAGIC,
@@ -395,15 +425,6 @@ export {
 	type VoiceProfileSampleInput,
 	verifyVoiceProfileArtifact,
 } from "./voice-profile-artifact";
-export {
-	DEFAULT_VOICE_SETTINGS,
-	effectiveBackendMode,
-	qualityPresetQuantizationRanking,
-	resolveVoiceSettings,
-	type VoiceBackendMode,
-	type VoiceModelQualityPreset,
-	type VoiceSettings,
-} from "./voice-settings";
 export {
 	type DrafterAbortReason,
 	type DrafterHandle,

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

@@ -1,11 +1,16 @@
 import { describe, expect, it } from "vitest";
+import { scoreFirstResponseLatency } from "../../e2e-harness";
 import type {
 	AudioSink,
 	Phrase,
 	SpeakerPreset,
 	TtsPcmChunk,
 } from "../../types";
-import { KokoroTtsBackend } from "../kokoro-backend";
+import {
+	KOKORO_MOBILE_TTFA_BUDGET_MS,
+	KokoroTtsBackend,
+} from "../kokoro-backend";
+import type { KokoroRuntime, KokoroRuntimeInputs } from "../kokoro-runtime";
 import { KokoroMockRuntime } from "../kokoro-runtime";
 import type { KokoroPhonemizer } from "../types";
 import { KOKORO_DEFAULT_VOICE_ID } from "../voices";
@@ -147,5 +152,111 @@ describe("KokoroTtsBackend", () => {
 	});
 });
 
+// ── TTFA: the first AUDIBLE chunk streams out before the phrase finishes ──
+//
+// These lock the streaming-TTFA contract (issue #8787 acceptance criterion 7)
+// deterministically — no native model, no wall-clock flakiness. The gated
+// real-FFI synth that measures TTFA against a true Kokoro forward lives in
+// `kokoro-engine-bridge.real.test.ts` and skips when artifacts are absent.
+
+/**
+ * A runtime that emits `chunkCount` body chunks and records, for every body
+ * chunk, how many runtime chunks had been produced when the backend re-emitted
+ * its first audible slice. Proves TTFA is bounded by ONE runtime forward
+ * boundary, not the whole phrase.
+ */
+class CountingKokoroRuntime implements KokoroRuntime {
+	readonly id = "mock" as const;
+	readonly sampleRate = 24000;
+	emitted = 0;
+	constructor(
+		private readonly totalSamples: number,
+		private readonly chunkCount: number,
+	) {}
+	async synthesize(args: KokoroRuntimeInputs): Promise<{ cancelled: boolean }> {
+		const perChunk = Math.max(
+			1,
+			Math.ceil(this.totalSamples / this.chunkCount),
+		);
+		for (let off = 0; off < this.totalSamples; off += perChunk) {
+			if (args.cancelSignal.cancelled) return { cancelled: true };
+			const n = Math.min(perChunk, this.totalSamples - off);
+			this.emitted++;
+			const want = args.onChunk({
+				pcm: new Float32Array(n).fill(0.05),
+				sampleRate: this.sampleRate,
+				isFinal: false,
+			});
+			if (want === true) return { cancelled: true };
+		}
+		args.onChunk({
+			pcm: new Float32Array(0),
+			sampleRate: this.sampleRate,
+			isFinal: true,
+		});
+		return { cancelled: false };
+	}
+	dispose(): void {}
+}
+
+describe("KokoroTtsBackend — streaming TTFA", () => {
+	it("emits the first audible chunk from the first runtime forward (sub-phrase TTFA)", async () => {
+		const runtime = new CountingKokoroRuntime(48000, 4); // 2s across 4 forwards
+		const backend = new KokoroTtsBackend({
+			runtime,
+			layout: {
+				root: "/tmp/kokoro",
+				modelFile: "kokoro-82m-v1_0.gguf",
+				voicesDir: "/tmp/kokoro/voices",
+				sampleRate: 24000,
+			},
+			defaultVoiceId: KOKORO_DEFAULT_VOICE_ID,
+			phonemizer: fixedPhonemizer(),
+			streamingChunkSamples: 1200, // 50ms slices
+		});
+
+		let firstAudibleAtRuntimeEmits = -1;
+		let firstAudibleSamples = -1;
+		await backend.synthesizeStream({
+			phrase: makePhrase("a full sentence that decodes in one forward"),
+			preset: makePreset(KOKORO_DEFAULT_VOICE_ID),
+			cancelSignal: { cancelled: false },
+			onChunk: (c) => {
+				if (!c.isFinal && c.pcm.length > 0 && firstAudibleAtRuntimeEmits < 0) {
+					firstAudibleAtRuntimeEmits = runtime.emitted;
+					firstAudibleSamples = c.pcm.length;
+				}
+				return undefined;
+			},
+		});
+
+		// The listener hears audio after the FIRST runtime forward, not all 4.
+		expect(firstAudibleAtRuntimeEmits).toBe(1);
+		// The first audible chunk is a bounded sub-phrase slice, not the phrase.
+		expect(firstAudibleSamples).toBeGreaterThan(0);
+		expect(firstAudibleSamples).toBeLessThanOrEqual(1200);
+	});
+
+	it("a mobile-class TTFA gate passes within budget and fails past it", () => {
+		// Representative warm-handle Kokoro first-phrase TTFB (~97ms TTFB +
+		// phonemize). Well within the mobile budget.
+		const within = scoreFirstResponseLatency({
+			turnStartedAtMs: 1_000,
+			ttsFirstAudioAtMs: 1_000 + 180,
+			maxFirstAudioMs: KOKORO_MOBILE_TTFA_BUDGET_MS,
+		});
+		expect(within.firstAudioMs).toBe(180);
+		expect(within.passed).toBe(true);
+
+		// A regression that blows the budget must fail the gate, never silently pass.
+		const blown = scoreFirstResponseLatency({
+			turnStartedAtMs: 1_000,
+			ttsFirstAudioAtMs: 1_000 + KOKORO_MOBILE_TTFA_BUDGET_MS + 50,
+			maxFirstAudioMs: KOKORO_MOBILE_TTFA_BUDGET_MS,
+		});
+		expect(blown.passed).toBe(false);
+	});
+});
+
 // Local declaration so the test file does not import the audio sink (unused).
 void (null as unknown as AudioSink);