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

package/src/routes/family-member-route.ts

@@ -0,0 +1,353 @@
+/**
+ * Voice first-run route: create a family-member voice profile.
+ *
+ * Route:
+ *   POST /v1/voice/first-run/family-member
+ *     Body (JSON):
+ *       {
+ *         audioBase64: string,   // raw base64-encoded audio (webm/wav/ogg)
+ *         durationMs: number,    // client-measured capture length
+ *         displayName: string,   // e.g. "Alex"
+ *         relationship: string,  // free-form label, e.g. "spouse", "colleague"
+ *         ownerEntityId?: string // optional — stored on the profile for edge creation
+ *       }
+ *     Response:
+ *       {
+ *         profileId: string,    // content-addressed vp_<sha> id
+ *         entityId: string,     // freshly minted UUID for the family-member entity
+ *         displayName: string,
+ *         relationship: string,
+ *         relationshipTag: "family_of"
+ *       }
+ *
+ * Audio pipeline (mirrors voice-first-run-routes.ts):
+ *   1. Decode base64 → Buffer → Float32 PCM (assumes 16 kHz, mono).
+ *   2. Encode via the fused `FusedSpeakerEncoder` → 256-dim centroid.
+ *   3. Store in VoiceProfileStore (non-OWNER entity binding).
+ *
+ * Graceful degradation: when the fused libelizainference (or its speaker ABI)
+ * is unavailable the route returns a 503. The client-side adapter
+ * (`VoiceProfilesClient`) falls back to a client-side pending profile so the UI
+ * flow is not blocked.
+ *
+ * The `family_of` relationship edge is recorded in profile metadata so a
+ * runtime-level consumer (e.g. voice-first-run-complete handler) can create
+ * the real Entity + Relationship rows after the runtime is up. The route
+ * itself does not call IAgentRuntime because HTTP route handlers in this
+ * plugin do not hold a runtime reference.
+ */
+
+import crypto from "node:crypto";
+import type * as http from "node:http";
+import path from "node:path";
+import {
+	logger,
+	readJsonBody,
+	resolveStateDir,
+	sendJson,
+	sendJsonError,
+} from "@elizaos/core";
+import { resolveFusedLibraryPath } from "../services/desktop-fused-ffi-backend-runtime.js";
+import { loadElizaInferenceFfi } from "../services/voice/ffi-bindings.js";
+import { VoiceProfileStore } from "../services/voice/profile-store.js";
+import {
+	type SpeakerEncoder,
+	SpeakerEncoderUnavailableError,
+	WESPEAKER_EMBEDDING_DIM,
+	WESPEAKER_MIN_SAMPLES,
+	WESPEAKER_RESNET34_LM_INT8_MODEL_ID,
+	WESPEAKER_SAMPLE_RATE,
+} from "../services/voice/speaker/encoder.js";
+import { FusedSpeakerEncoder } from "../services/voice/speaker/encoder-fused.js";
+
+// ---------------------------------------------------------------------------
+// Injectable test hooks (mirrors voice-first-run-routes.ts)
+// ---------------------------------------------------------------------------
+
+export type FamilyMemberEncoderFactory = () => Promise<SpeakerEncoder>;
+
+let encoderFactoryOverride: FamilyMemberEncoderFactory | null = null;
+let cachedEncoder: SpeakerEncoder | null = null;
+
+export function setFamilyMemberEncoderFactory(
+	factory: FamilyMemberEncoderFactory | null,
+): void {
+	encoderFactoryOverride = factory;
+	cachedEncoder = null;
+}
+
+let profileStoreOverride: VoiceProfileStore | null = null;
+
+export function setFamilyMemberProfileStore(
+	store: VoiceProfileStore | null,
+): void {
+	profileStoreOverride = store;
+}
+
+// ---------------------------------------------------------------------------
+// Loader helpers
+// ---------------------------------------------------------------------------
+
+async function loadEncoder(): Promise<SpeakerEncoder> {
+	if (cachedEncoder) return cachedEncoder;
+	if (encoderFactoryOverride) {
+		cachedEncoder = await encoderFactoryOverride();
+		return cachedEncoder;
+	}
+	cachedEncoder = await loadFusedSpeakerEncoder();
+	return cachedEncoder;
+}
+
+/**
+ * Load the fused speaker encoder through the `eliza_inference_speaker_*` ABI —
+ * the sole on-device speaker runtime. Probes the speaker ABI up front: a build
+ * that lacks it raises a structured `SpeakerEncoderUnavailableError` (the route
+ * surfaces a 503) rather than degrading silently. No standalone-lib fallback.
+ */
+async function loadFusedSpeakerEncoder(): Promise<SpeakerEncoder> {
+	const bundleRoot = path.join(resolveStateDir(), "voice-profiles");
+	const libPath = resolveFusedLibraryPath(bundleRoot);
+	if (!libPath) {
+		throw new SpeakerEncoderUnavailableError(
+			"library-missing",
+			"[family-member-route] fused libelizainference not found. Set $ELIZA_INFERENCE_LIBRARY (exact path) or $ELIZA_INFERENCE_LIB_DIR, or build it via packages/app-core/scripts/build-llama-cpp-mtp.mjs.",
+		);
+	}
+	const ffi = loadElizaInferenceFfi(libPath);
+	if (!FusedSpeakerEncoder.isSupported(ffi)) {
+		throw new SpeakerEncoderUnavailableError(
+			"native-missing",
+			`[family-member-route] the fused libelizainference at ${libPath} (ABI v${ffi.libraryAbiVersion}) lacks the speaker ABI (eliza_inference_speaker_supported() == 0). Rebuild with the WeSpeaker forward graph linked in.`,
+		);
+	}
+	const ctx = ffi.create(bundleRoot);
+	return FusedSpeakerEncoder.load({ ffi, ctx });
+}
+
+async function getProfileStore(): Promise<VoiceProfileStore> {
+	if (profileStoreOverride) return profileStoreOverride;
+	const store = new VoiceProfileStore({
+		rootDir: path.join(resolveStateDir(), "voice-profiles"),
+	});
+	await store.init();
+	return store;
+}
+
+// ---------------------------------------------------------------------------
+// Request body validation
+// ---------------------------------------------------------------------------
+
+interface FamilyMemberBody {
+	audioBase64: string;
+	durationMs: number;
+	displayName: string;
+	relationship: string;
+	ownerEntityId?: string | null;
+}
+
+function parseFamilyMemberBody(
+	raw: Record<string, unknown>,
+): FamilyMemberBody | string {
+	const audioBase64 =
+		typeof raw.audioBase64 === "string" ? raw.audioBase64.trim() : null;
+	if (!audioBase64) return "audioBase64 is required";
+
+	const durationMs =
+		typeof raw.durationMs === "number" && raw.durationMs > 0
+			? raw.durationMs
+			: null;
+	if (durationMs === null) return "durationMs must be a positive number";
+
+	const displayName =
+		typeof raw.displayName === "string" && raw.displayName.trim().length > 0
+			? raw.displayName.trim()
+			: null;
+	if (!displayName) return "displayName is required";
+
+	const relationship =
+		typeof raw.relationship === "string" && raw.relationship.trim().length > 0
+			? raw.relationship.trim()
+			: "family";
+
+	const ownerEntityId =
+		typeof raw.ownerEntityId === "string" && raw.ownerEntityId.trim()
+			? raw.ownerEntityId.trim()
+			: null;
+
+	return { audioBase64, durationMs, displayName, relationship, ownerEntityId };
+}
+
+// ---------------------------------------------------------------------------
+// PCM decode
+// ---------------------------------------------------------------------------
+
+function decodeBase64ToPcm(audioBase64: string): Float32Array | string {
+	let rawBuf: Buffer;
+	try {
+		rawBuf = Buffer.from(audioBase64, "base64");
+	} catch {
+		return "failed to decode audioBase64";
+	}
+	if (rawBuf.byteLength % 4 !== 0) {
+		return `PCM buffer length ${rawBuf.byteLength} is not a multiple of 4 (expected raw Float32 PCM)`;
+	}
+	const out = new Float32Array(rawBuf.byteLength / 4);
+	const view = new DataView(
+		rawBuf.buffer,
+		rawBuf.byteOffset,
+		rawBuf.byteLength,
+	);
+	for (let i = 0; i < out.length; i += 1) {
+		out[i] = view.getFloat32(i * 4, true);
+	}
+	return out;
+}
+
+// ---------------------------------------------------------------------------
+// Route handler
+// ---------------------------------------------------------------------------
+
+/** Relationship tag written to profile metadata and echoed in response. */
+export const FAMILY_OF_TAG = "family_of" as const;
+
+export interface FamilyMemberResult {
+	profileId: string;
+	entityId: string;
+	displayName: string;
+	relationship: string;
+	relationshipTag: typeof FAMILY_OF_TAG;
+	ownerEntityId: string | null;
+}
+
+/**
+ * Handle `POST /v1/voice/first-run/family-member`.
+ *
+ * Returns `true` when the request was handled (success or error response
+ * written), `false` when the path does not match this handler.
+ */
+export async function handleFamilyMemberRoute(
+	req: http.IncomingMessage,
+	res: http.ServerResponse,
+): Promise<boolean> {
+	const method = (req.method ?? "GET").toUpperCase();
+	const url = new URL(req.url ?? "/", "http://localhost");
+	const pathname = url.pathname;
+
+	if (method !== "POST" || pathname !== "/v1/voice/first-run/family-member") {
+		return false;
+	}
+
+	const raw = await readJsonBody<Record<string, unknown>>(req, res);
+	if (!raw) return true; // readJsonBody already sent a 4xx
+
+	const parsed = parseFamilyMemberBody(raw);
+	if (typeof parsed === "string") {
+		sendJsonError(res, parsed, 400);
+		return true;
+	}
+
+	const { audioBase64, durationMs, displayName, relationship, ownerEntityId } =
+		parsed;
+
+	// Decode audio.
+	const pcmOrError = decodeBase64ToPcm(audioBase64);
+	if (typeof pcmOrError === "string") {
+		sendJsonError(res, pcmOrError, 400);
+		return true;
+	}
+	const pcm = pcmOrError;
+
+	if (pcm.length < WESPEAKER_MIN_SAMPLES) {
+		sendJsonError(
+			res,
+			`capture too short: ${pcm.length} PCM samples (< ${WESPEAKER_MIN_SAMPLES} required for ${WESPEAKER_SAMPLE_RATE} Hz encoder). Minimum ~${Math.ceil((WESPEAKER_MIN_SAMPLES / WESPEAKER_SAMPLE_RATE) * 1000)}ms.`,
+			400,
+		);
+		return true;
+	}
+
+	// Encode via WeSpeaker.
+	let encoder: SpeakerEncoder;
+	try {
+		encoder = await loadEncoder();
+	} catch (err) {
+		if (err instanceof SpeakerEncoderUnavailableError) {
+			sendJsonError(res, err.message, 503);
+			return true;
+		}
+		throw err;
+	}
+
+	let centroid: Float32Array;
+	try {
+		centroid = await encoder.encode(pcm);
+	} catch (err) {
+		if (err instanceof SpeakerEncoderUnavailableError) {
+			sendJsonError(res, err.message, err.code === "invalid-input" ? 400 : 503);
+			return true;
+		}
+		throw err;
+	}
+
+	if (centroid.length !== WESPEAKER_EMBEDDING_DIM) {
+		sendJsonError(
+			res,
+			`centroid dim mismatch: ${centroid.length} != ${WESPEAKER_EMBEDDING_DIM}`,
+			500,
+		);
+		return true;
+	}
+
+	// Generate a stable entity ID for the family member.
+	const entityId = crypto.randomUUID();
+
+	// Store the profile in VoiceProfileStore.
+	const store = await getProfileStore();
+	let profile: Awaited<ReturnType<VoiceProfileStore["createProfile"]>>;
+	try {
+		profile = await store.createProfile({
+			centroid,
+			embeddingModel: WESPEAKER_RESNET34_LM_INT8_MODEL_ID,
+			entityId,
+			confidence: 0.85,
+			durationMs,
+			consent: {
+				attributionAuthorized: true,
+				synthesisAuthorized: false,
+				grantedAt: new Date().toISOString(),
+				grantedBy: ownerEntityId ?? undefined,
+			},
+			metadata: {
+				displayName,
+				relationship,
+				cohort: "family",
+				source: "first-run",
+				relationshipTag: FAMILY_OF_TAG,
+				ownerEntityId: ownerEntityId ?? null,
+			},
+		});
+	} catch (err) {
+		logger.error(
+			{ err, displayName, relationship },
+			"[family-member-route] failed to create voice profile",
+		);
+		sendJsonError(
+			res,
+			err instanceof Error ? err.message : "failed to create voice profile",
+			500,
+		);
+		return true;
+	}
+
+	const result: FamilyMemberResult = {
+		profileId: profile.profileId,
+		entityId,
+		displayName,
+		relationship,
+		relationshipTag: FAMILY_OF_TAG,
+		ownerEntityId: ownerEntityId ?? null,
+	};
+
+	sendJson(res, result);
+	return true;
+}

package/src/routes/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Route-side exports for plugin-local-inference.
+ *
+ * Consumers (app-core/api/server.ts) import from
+ * `@elizaos/plugin-local-inference/routes` to mount the HTTP compat routes
+ * for model catalog, downloads, status, and chat commands.
+ */
+export { handleVoiceProfileRoutes, registerProfileInCatalog, resolveDefaultProfileId, type VoiceProfileCatalog, type VoiceProfileCatalogEntry, type VoiceProfileRouteOptions, } from "../services/voice/voice-profile-routes.js";
+export { FAMILY_OF_TAG, type FamilyMemberEncoderFactory, type FamilyMemberResult, handleFamilyMemberRoute, setFamilyMemberEncoderFactory, setFamilyMemberProfileStore, } from "./family-member-route.js";
+export { handleLiveDiarizationRoute, resetLiveDiarizationSession, } from "./live-diarization-route.js";
+export * from "./local-inference-asr-route.js";
+export * from "./local-inference-compat-routes.js";
+export * from "./local-inference-tts-route.js";
+export { __resetVoiceFirstRunSessions, type EncoderFactory as VoiceFirstRunEncoderFactory, FIRST_RUN_SCRIPT, type FirstRunScriptStep, handleVoiceFirstRunRoutes, setVoiceFirstRunEncoderFactory, setVoiceFirstRunProfileStore, setVoiceFirstRunSettingsWriter, } from "./voice-first-run-routes.js";
+export { handleVoiceModelsRoutes, resolveInstalledVersions as resolveInstalledVoiceModelVersions, setVoiceModelDownloader, setVoiceModelsBundleVersionForTest, setVoiceModelsUpdater, type VoiceModelInstallationView, } from "./voice-models-routes.js";
+export { voiceProfilePluginRoutes } from "./voice-profile-plugin-routes.js";
+export { handleVoiceProfilesManagementRoutes, setVoiceProfilesManagementStore, type VoiceProfileDto, } from "./voice-profiles-management-routes.js";
+export { handleVoiceSpeakerProfileRoutes, type SpeakerProfileSummary, setVoiceSpeakerProfileStore, } from "./voice-speaker-profile-routes.js";
+//# sourceMappingURL=index.d.ts.map

package/src/routes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACN,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,GAC7B,MAAM,2CAA2C,CAAC;AACnD,OAAO,EACN,aAAa,EACb,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EACvB,uBAAuB,EACvB,6BAA6B,EAC7B,2BAA2B,GAC3B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACN,0BAA0B,EAC1B,2BAA2B,GAC3B,MAAM,6BAA6B,CAAC;AACrC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oCAAoC,CAAC;AACnD,cAAc,gCAAgC,CAAC;AAC/C,OAAO,EACN,4BAA4B,EAC5B,KAAK,cAAc,IAAI,2BAA2B,EAClD,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,yBAAyB,EACzB,8BAA8B,EAC9B,4BAA4B,EAC5B,8BAA8B,GAC9B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACN,uBAAuB,EACvB,wBAAwB,IAAI,kCAAkC,EAC9D,uBAAuB,EACvB,kCAAkC,EAClC,qBAAqB,EACrB,KAAK,0BAA0B,GAC/B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EACN,mCAAmC,EACnC,+BAA+B,EAC/B,KAAK,eAAe,GACpB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACN,+BAA+B,EAC/B,KAAK,qBAAqB,EAC1B,2BAA2B,GAC3B,MAAM,mCAAmC,CAAC"}

package/src/routes/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Route-side exports for plugin-local-inference.
+ *
+ * Consumers (app-core/api/server.ts) import from
+ * `@elizaos/plugin-local-inference/routes` to mount the HTTP compat routes
+ * for model catalog, downloads, status, and chat commands.
+ */
+
+export {
+	handleVoiceProfileRoutes,
+	registerProfileInCatalog,
+	resolveDefaultProfileId,
+	type VoiceProfileCatalog,
+	type VoiceProfileCatalogEntry,
+	type VoiceProfileRouteOptions,
+} from "../services/voice/voice-profile-routes.js";
+export {
+	FAMILY_OF_TAG,
+	type FamilyMemberEncoderFactory,
+	type FamilyMemberResult,
+	handleFamilyMemberRoute,
+	setFamilyMemberEncoderFactory,
+	setFamilyMemberProfileStore,
+} from "./family-member-route.js";
+export {
+	handleLiveDiarizationRoute,
+	resetLiveDiarizationSession,
+} from "./live-diarization-route.js";
+export * from "./local-inference-asr-route.js";
+export * from "./local-inference-compat-routes.js";
+export * from "./local-inference-tts-route.js";
+export {
+	__resetVoiceFirstRunSessions,
+	type EncoderFactory as VoiceFirstRunEncoderFactory,
+	FIRST_RUN_SCRIPT,
+	type FirstRunScriptStep,
+	handleVoiceFirstRunRoutes,
+	setVoiceFirstRunEncoderFactory,
+	setVoiceFirstRunProfileStore,
+	setVoiceFirstRunSettingsWriter,
+} from "./voice-first-run-routes.js";
+export {
+	handleVoiceModelsRoutes,
+	resolveInstalledVersions as resolveInstalledVoiceModelVersions,
+	setVoiceModelDownloader,
+	setVoiceModelsBundleVersionForTest,
+	setVoiceModelsUpdater,
+	type VoiceModelInstallationView,
+} from "./voice-models-routes.js";
+export { voiceProfilePluginRoutes } from "./voice-profile-plugin-routes.js";
+export {
+	handleVoiceProfilesManagementRoutes,
+	setVoiceProfilesManagementStore,
+	type VoiceProfileDto,
+} from "./voice-profiles-management-routes.js";
+export {
+	handleVoiceSpeakerProfileRoutes,
+	type SpeakerProfileSummary,
+	setVoiceSpeakerProfileStore,
+} from "./voice-speaker-profile-routes.js";

package/src/routes/live-diarization-route.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `/api/voice/audio-frames` — WebView → agent transport for live on-device
+ * speaker diarization.
+ *
+ * The Android `audioFrame` PCM stream is captured in the Capacitor WebView but
+ * the bun:ffi voice libs run in the agent process. The WebView batches frames
+ * (~49 fps) and POSTs them here; this route feeds them to the single
+ * {@link LiveDiarizationSession}, which runs the real ggml VAD / encoder /
+ * diarizer / attribution pipeline and emits VOICE_TURN_OBSERVED.
+ *
+ * Routes:
+ *   POST /api/voice/audio-frames        body: { frames: AudioFrameEvent[],
+ *                                               flush?: boolean }
+ *                                       → { ok, framesReceived, turnsObserved }
+ *   GET  /api/voice/audio-frames/status → LiveDiarizationStatus (device evidence)
+ *
+ * Auth follows the compat pattern: trusted-loopback OR the compat API token.
+ * The WebView reaches this over 127.0.0.1 (trusted local), matching the rest of
+ * the on-device agent surface.
+ */
+import type http from "node:http";
+import { type CompatRuntimeState } from "./compat-helpers.js";
+/** Reset the module-level session (tests + capture teardown). */
+export declare function resetLiveDiarizationSession(): Promise<void>;
+export declare function handleLiveDiarizationRoute(req: http.IncomingMessage, res: http.ServerResponse, state: CompatRuntimeState): Promise<boolean>;
+//# sourceMappingURL=live-diarization-route.d.ts.map

package/src/routes/live-diarization-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-diarization-route.d.ts","sourceRoot":"","sources":["live-diarization-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAMlC,OAAO,EACN,KAAK,kBAAkB,EAKvB,MAAM,qBAAqB,CAAC;AAY7B,iEAAiE;AACjE,wBAAsB,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC,CAIjE;AAgBD,wBAAsB,0BAA0B,CAC/C,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,cAAc,EACxB,KAAK,EAAE,kBAAkB,GACvB,OAAO,CAAC,OAAO,CAAC,CAmDlB"}

package/src/routes/live-diarization-route.test.ts

@@ -0,0 +1,213 @@
+/**
+ * live-diarization-route unit tests (HTTP-level, no GGUF models).
+ *
+ * Exercises the WebView → agent transport route's request/response contract:
+ *   - loopback (trusted-local) auth pass-through;
+ *   - non-loopback rejection (401);
+ *   - frame-shape validation (rejects malformed frames);
+ *   - the status route surfaces the model/lib resolution (and, on a host with
+ *     no on-device GGUFs, the precise "voice GGUFs missing" blocker — the same
+ *     readiness payload the device read returns).
+ *
+ * The model-heavy path (real ggml VAD/encoder/diarizer) is covered by the
+ * host smoke harness (`packages/app-core/scripts/voice-attribution-smoke.ts`),
+ * which exercises the same AudioFrameConsumer with real models.
+ */
+
+import type http from "node:http";
+import { Readable } from "node:stream";
+import { afterEach, describe, expect, it } from "vitest";
+import type { CompatRuntimeState } from "./compat-helpers.js";
+import {
+	handleLiveDiarizationRoute,
+	resetLiveDiarizationSession,
+} from "./live-diarization-route.js";
+
+class FakeRes {
+	statusCode = 200;
+	headersSent = false;
+	private readonly headers = new Map<string, string>();
+	body = "";
+	ended = false;
+	setHeader(name: string, value: string): void {
+		this.headers.set(name.toLowerCase(), value);
+	}
+	end(chunk?: string): void {
+		if (chunk) this.body += chunk;
+		this.ended = true;
+		this.headersSent = true;
+	}
+	json(): unknown {
+		return JSON.parse(this.body);
+	}
+}
+
+function makeReq(opts: {
+	method: string;
+	url: string;
+	body?: unknown;
+	remoteAddress?: string;
+	host?: string;
+}): http.IncomingMessage {
+	const payload = opts.body !== undefined ? JSON.stringify(opts.body) : "";
+	const stream = Readable.from(payload ? [Buffer.from(payload)] : []);
+	const req = stream as unknown as http.IncomingMessage & {
+		method: string;
+		url: string;
+		headers: Record<string, string>;
+		socket: { remoteAddress: string };
+	};
+	req.method = opts.method;
+	req.url = opts.url;
+	req.headers = { host: opts.host ?? "127.0.0.1:31337" };
+	req.socket = { remoteAddress: opts.remoteAddress ?? "127.0.0.1" } as never;
+	return req;
+}
+
+const runtimeState = (): CompatRuntimeState => ({
+	current: {
+		emitEvent: async () => {},
+	} as never,
+});
+
+/** A well-formed AudioFrameEvent (20 ms silence frame). */
+function silentFrame(frameIndex: number) {
+	const samples = 320;
+	const pcm16 = Buffer.alloc(samples * 2).toString("base64");
+	return {
+		pcm16,
+		sampleRate: 16_000,
+		channels: 1,
+		samples,
+		rms: 0,
+		timestamp: frameIndex * 20,
+		frameIndex,
+	};
+}
+
+afterEach(async () => {
+	await resetLiveDiarizationSession();
+});
+
+describe("handleLiveDiarizationRoute", () => {
+	it("returns false for an unrelated path (passes through)", async () => {
+		const res = new FakeRes();
+		const handled = await handleLiveDiarizationRoute(
+			makeReq({ method: "GET", url: "/api/unrelated" }),
+			res as unknown as http.ServerResponse,
+			runtimeState(),
+		);
+		expect(handled).toBe(false);
+		expect(res.ended).toBe(false);
+	});
+
+	it("rejects a non-loopback caller with 401", async () => {
+		const res = new FakeRes();
+		const handled = await handleLiveDiarizationRoute(
+			makeReq({
+				method: "GET",
+				url: "/api/voice/audio-frames/status",
+				remoteAddress: "10.0.0.5",
+				host: "example.com",
+			}),
+			res as unknown as http.ServerResponse,
+			runtimeState(),
+		);
+		expect(handled).toBe(true);
+		expect(res.statusCode).toBe(401);
+	});
+
+	it("status route surfaces model/lib resolution (blocker on a host without device GGUFs)", async () => {
+		const res = new FakeRes();
+		const handled = await handleLiveDiarizationRoute(
+			makeReq({ method: "GET", url: "/api/voice/audio-frames/status" }),
+			res as unknown as http.ServerResponse,
+			runtimeState(),
+		);
+		expect(handled).toBe(true);
+		expect(res.statusCode).toBe(200);
+		const status = res.json() as {
+			ready: boolean;
+			libs: { fusedInference: string | null };
+			models: { dir: string };
+			framesReceived: number;
+			turnsObserved: number;
+			error?: string;
+		};
+		// On CI/host there is no fused libelizainference, so readiness fails with
+		// a precise blocker rather than a silent default — the device-evidence
+		// read. The session now runs the whole stack (VAD/encoder/diarizer)
+		// through the one fused FFI handle, not separate bun:ffi-musl libs.
+		expect(typeof status.models.dir).toBe("string");
+		expect("fusedInference" in status.libs).toBe(true);
+		expect(status.framesReceived).toBe(0);
+		expect(status.turnsObserved).toBe(0);
+		if (!status.ready) {
+			expect(status.error).toMatch(
+				/fused libelizainference|ABI|FFI|libelizainference/i,
+			);
+		}
+	});
+
+	it("rejects a malformed frame batch with 400", async () => {
+		const res = new FakeRes();
+		const handled = await handleLiveDiarizationRoute(
+			makeReq({
+				method: "POST",
+				url: "/api/voice/audio-frames",
+				body: { frames: [{ pcm16: "AA==" /* missing fields */ }] },
+			}),
+			res as unknown as http.ServerResponse,
+			runtimeState(),
+		);
+		expect(handled).toBe(true);
+		expect(res.statusCode).toBe(400);
+		expect((res.json() as { error: string }).error).toMatch(/Malformed/);
+	});
+
+	it("rejects a non-array frames field with 400", async () => {
+		const res = new FakeRes();
+		const handled = await handleLiveDiarizationRoute(
+			makeReq({
+				method: "POST",
+				url: "/api/voice/audio-frames",
+				body: { frames: "nope" },
+			}),
+			res as unknown as http.ServerResponse,
+			runtimeState(),
+		);
+		expect(handled).toBe(true);
+		expect(res.statusCode).toBe(400);
+	});
+
+	it("accepts a well-formed batch shape (validation passes before model build)", async () => {
+		// Well-formed frames clear the route's shape gate. Without on-device GGUFs
+		// the session build then throws; the route surfaces that as a 500-class
+		// failure, NOT a 400 — proving the wire contract is satisfied.
+		const res = new FakeRes();
+		const handled = await handleLiveDiarizationRoute(
+			makeReq({
+				method: "POST",
+				url: "/api/voice/audio-frames",
+				body: { frames: [silentFrame(0), silentFrame(1)] },
+			}),
+			res as unknown as http.ServerResponse,
+			runtimeState(),
+		).catch(() => "threw");
+		// Either it threw inside ingest (no models) or returned true; either way
+		// the request was NOT rejected as malformed (no 400).
+		expect(res.statusCode).not.toBe(400);
+		expect(handled === true || handled === "threw").toBe(true);
+	});
+
+	it("returns 503 when the runtime is not ready", async () => {
+		const res = new FakeRes();
+		const handled = await handleLiveDiarizationRoute(
+			makeReq({ method: "GET", url: "/api/voice/audio-frames/status" }),
+			res as unknown as http.ServerResponse,
+			{ current: null },
+		);
+		expect(handled).toBe(true);
+		expect(res.statusCode).toBe(503);
+	});
+});