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

package/src/runtime/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Runtime-side exports for plugin-local-inference.
+ *
+ * Consumers (app-core/runtime/eliza.ts, agent bootstrap) import from
+ * `@elizaos/plugin-local-inference/runtime` to wire boot-time handler
+ * registration, embedding warm-up policy, and the mobile inference gate.
+ */
+
+// The cross-provider prefer-local router. ensureLocalInferenceHandler installs
+// it on desktop; the mobile boot path (capacitor-bridge android/bridge) must
+// install it too, otherwise cloud providers (registered at priority 50) win
+// over the local handlers (priority 0) — the "stuck-cloud" failure where the
+// chat hits plugin-elizacloud's generateNativeChatCompletion and 401s.
+export { installRouterHandler } from "../services/router-handler.js";
+export {
+	DEFAULT_MODELS_DIR,
+	type EmbeddingProgressCallback,
+	embeddingGgufFilePresent,
+	ensureModel,
+	findExistingEmbeddingModelForWarmupReuse,
+	isEmbeddingWarmupReuseDisabled,
+} from "./embedding-manager-support.js";
+export { detectEmbeddingPreset } from "./embedding-presets.js";
+export { shouldWarmupLocalEmbeddingModel } from "./embedding-warmup-policy.js";
+export { ensureLocalInferenceHandler } from "./ensure-local-inference-handler.js";
+export {
+	shouldEnableMobileLocalInference,
+	warnIfMobileGateActiveWithoutPlatform,
+} from "./mobile-local-inference-gate.js";
+export {
+	type EmitVoiceTurnObservedArgs,
+	emitVoiceTurnObserved,
+	getVoiceProfileStore,
+	handleVoiceEntityBound,
+	setVoiceEntityBindingStore,
+} from "./voice-entity-binding.js";

package/src/runtime/mobile-local-inference-gate.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+	shouldEnableMobileLocalInference,
+	warnIfMobileGateActiveWithoutPlatform,
+} from "./mobile-local-inference-gate";
+
+describe("shouldEnableMobileLocalInference", () => {
+	it("returns false when no env flags and arch is not riscv64", () => {
+		expect(shouldEnableMobileLocalInference({}, "x64")).toBe(false);
+		expect(shouldEnableMobileLocalInference({}, "arm64")).toBe(false);
+	});
+
+	it("returns true when ELIZA_DEVICE_BRIDGE_ENABLED=1", () => {
+		expect(
+			shouldEnableMobileLocalInference(
+				{ ELIZA_DEVICE_BRIDGE_ENABLED: "1" },
+				"x64",
+			),
+		).toBe(true);
+	});
+
+	it("returns true when ELIZA_LOCAL_LLAMA=1", () => {
+		expect(
+			shouldEnableMobileLocalInference({ ELIZA_LOCAL_LLAMA: "1" }, "x64"),
+		).toBe(true);
+	});
+
+	it("returns true when ELIZA_BIONIC_HOST_DELEGATED=1 (Android bionic delegation)", () => {
+		// The agent delegates inference to the in-process bionic Vulkan host over
+		// UDS; without this trigger ensureLocalInferenceHandler is skipped on the
+		// phone, so the bionic loader + TTS/TRANSCRIPTION/IMAGE_DESCRIPTION
+		// handlers never register and only the direct-reply chat path works (#8848).
+		expect(
+			shouldEnableMobileLocalInference(
+				{ ELIZA_BIONIC_HOST_DELEGATED: "1" },
+				"arm64",
+			),
+		).toBe(true);
+	});
+
+	it("ELIZA_DISABLE_FFI_LLAMA=1 does not block the bionic-host path (process-external UDS)", () => {
+		expect(
+			shouldEnableMobileLocalInference(
+				{
+					ELIZA_DISABLE_FFI_LLAMA: "1",
+					ELIZA_BIONIC_HOST_DELEGATED: "1",
+				},
+				"arm64",
+			),
+		).toBe(true);
+	});
+
+	it("auto-fires on riscv64 with no env flags", () => {
+		// node-llama-cpp has no riscv64 prebuild; the FFI loader (which dlopens
+		// the cross-built libllama.so) is the only in-process llama.cpp path
+		// available on riscv64, so the gate auto-fires there.
+		expect(shouldEnableMobileLocalInference({}, "riscv64")).toBe(true);
+	});
+
+	it("ELIZA_DISABLE_FFI_LLAMA=1 hard-disables the riscv64 auto-fire", () => {
+		// Operator opt-out: route inference to Cloud instead of the on-device
+		// FFI path. The device-bridge is process-external and unaffected.
+		expect(
+			shouldEnableMobileLocalInference(
+				{ ELIZA_DISABLE_FFI_LLAMA: "1" },
+				"riscv64",
+			),
+		).toBe(false);
+	});
+
+	it("ELIZA_DISABLE_FFI_LLAMA=1 does not block the device-bridge path", () => {
+		expect(
+			shouldEnableMobileLocalInference(
+				{
+					ELIZA_DISABLE_FFI_LLAMA: "1",
+					ELIZA_DEVICE_BRIDGE_ENABLED: "1",
+				},
+				"riscv64",
+			),
+		).toBe(true);
+	});
+
+	it("ELIZA_DISABLE_FFI_LLAMA=1 suppresses ELIZA_LOCAL_LLAMA=1 too", () => {
+		// `ELIZA_LOCAL_LLAMA` is the AOSP/FFI in-process trigger, so the
+		// disable flag must override it. Otherwise a riscv64 operator who set
+		// disable would still be forced into the FFI path on an AOSP build.
+		expect(
+			shouldEnableMobileLocalInference(
+				{
+					ELIZA_DISABLE_FFI_LLAMA: "1",
+					ELIZA_LOCAL_LLAMA: "1",
+				},
+				"riscv64",
+			),
+		).toBe(false);
+	});
+});
+
+describe("warnIfMobileGateActiveWithoutPlatform", () => {
+	it("warns when the gate is active (ELIZA_LOCAL_LLAMA=1) but ELIZA_PLATFORM is unset", () => {
+		const warn = vi.fn();
+		const fired = warnIfMobileGateActiveWithoutPlatform({
+			mobilePlatform: false,
+			warn,
+			env: { ELIZA_LOCAL_LLAMA: "1" },
+			arch: "arm64",
+		});
+		expect(fired).toBe(true);
+		expect(warn).toHaveBeenCalledTimes(1);
+		const message = warn.mock.calls[0]?.[0] ?? "";
+		expect(message).toContain("ELIZA_PLATFORM");
+		expect(message).toContain("Kokoro-exclusive mobile");
+	});
+
+	it("warns when the gate is active via the device bridge and ELIZA_PLATFORM is unset", () => {
+		const warn = vi.fn();
+		const fired = warnIfMobileGateActiveWithoutPlatform({
+			mobilePlatform: false,
+			warn,
+			env: { ELIZA_DEVICE_BRIDGE_ENABLED: "1" },
+			arch: "arm64",
+		});
+		expect(fired).toBe(true);
+		expect(warn).toHaveBeenCalledTimes(1);
+	});
+
+	it("does NOT warn when ELIZA_PLATFORM=android (mobilePlatform true)", () => {
+		// On a real phone the platform flag is set, so isMobilePlatform() is true
+		// and the selector already pins Kokoro — no mismatch to report.
+		const warn = vi.fn();
+		const fired = warnIfMobileGateActiveWithoutPlatform({
+			mobilePlatform: true,
+			warn,
+			env: { ELIZA_LOCAL_LLAMA: "1", ELIZA_PLATFORM: "android" },
+			arch: "arm64",
+		});
+		expect(fired).toBe(false);
+		expect(warn).not.toHaveBeenCalled();
+	});
+
+	it("does NOT warn when the gate is inactive (desktop x64, no flags)", () => {
+		const warn = vi.fn();
+		const fired = warnIfMobileGateActiveWithoutPlatform({
+			mobilePlatform: false,
+			warn,
+			env: {},
+			arch: "x64",
+		});
+		expect(fired).toBe(false);
+		expect(warn).not.toHaveBeenCalled();
+	});
+});

package/src/runtime/mobile-local-inference-gate.ts

@@ -0,0 +1,99 @@
+/**
+ * On a mobile platform (`ELIZA_PLATFORM=android` / `ios`) the runtime skips
+ * nearly every boot helper because they shell out to subprocesses,
+ * platform-specific binaries, or optional packages that aren't in the mobile
+ * bundle. Three mobile-safe inference paths need wiring:
+ *
+ *   - `ELIZA_DEVICE_BRIDGE_ENABLED=1`: the agent (this process) hosts the
+ *     device-bridge WSS and dials whichever paired device connects. On the
+ *     Capacitor APK the WebView's `@elizaos/capacitor-llama` is the intended
+ *     dialer over loopback. The Capacitor build always exports this env so
+ *     the bridge is ready as soon as first-run picks the local mode.
+ *
+ *   - `ELIZA_LOCAL_LLAMA=1`: AOSP path that loads `libllama.so` directly
+ *     inside the Android process via `bun:ffi`. Wired here so the gate is
+ *     in place ahead of sub-task 2 — the AOSP build flag flips this on.
+ *
+ *   - `process.arch === "riscv64"`: `capacitor-llama` has no riscv64 prebuild
+ *     and we can't NAPI-build it on-device, so the in-process FFI path
+ *     (same loader contract as the AOSP path) is the only viable option.
+ *     Auto-firing here keeps the riscv64 mobile boot path zero-config; an
+ *     operator can hard-disable via `ELIZA_DISABLE_FFI_LLAMA=1` to skip the
+ *     loader and route inference through Cloud instead. See
+ *     `plugin-aosp-local-inference/src/aosp-llama-adapter.ts:isAospEnabled`
+ *     and `plugin-local-inference/src/runtime/ensure-local-inference-handler.ts:shouldAttemptAospLlamaLoader`
+ *     — the three predicates agree on the trigger set.
+ *
+ * Kept dependency-free so it can be unit-tested without instantiating the
+ * full runtime.
+ */
+export function shouldEnableMobileLocalInference(
+	env: NodeJS.ProcessEnv = process.env,
+	arch: NodeJS.Architecture = process.arch,
+): boolean {
+	// Bionic-host delegation (Android dynamic-Vulkan): the app shell stages a
+	// dynamic-Vulkan `libelizainference.so` reachable only from the in-process
+	// bionic host and sets `ELIZA_BIONIC_HOST_DELEGATED=1` (suppressing
+	// ELIZA_LOCAL_LLAMA so the musl agent never dlopen's the lib). The agent talks
+	// to that host over the abstract UDS — a process-external backend just like
+	// the device bridge. Without counting it here, ensureLocalInferenceHandler is
+	// skipped on the phone, so `tryRegisterBionicHostLoader` + the
+	// TEXT/embedding (and TTS/TRANSCRIPTION/IMAGE_DESCRIPTION) handlers never
+	// register and only the mobile-local-direct-reply chat path works (#8848).
+	const bionicHost = env.ELIZA_BIONIC_HOST_DELEGATED?.trim() === "1";
+	if (env.ELIZA_DISABLE_FFI_LLAMA?.trim() === "1") {
+		// Operator opted out of the FFI path entirely — the device-bridge and the
+		// in-process bionic host are both process-external (WS / UDS) and don't
+		// depend on `libllama.so` being dlopen'd in this musl process.
+		return env.ELIZA_DEVICE_BRIDGE_ENABLED?.trim() === "1" || bionicHost;
+	}
+	const deviceBridge = env.ELIZA_DEVICE_BRIDGE_ENABLED?.trim() === "1";
+	const localLlama = env.ELIZA_LOCAL_LLAMA?.trim() === "1";
+	const riscv64Auto = arch === "riscv64";
+	return deviceBridge || localLlama || riscv64Auto || bionicHost;
+}
+
+/**
+ * Boot-time invariant check for the mobile voice backend selector.
+ *
+ * The voice engine passes `mobile: isMobilePlatform()` into `selectVoiceBackend`
+ * (`services/engine.ts`). That flag is what pins mobile to the Kokoro-exclusive
+ * TTS path — OmniVoice is never shipped on a phone. But `isMobilePlatform()`
+ * keys solely off `ELIZA_PLATFORM ∈ {ios, android}`, whereas
+ * {@link shouldEnableMobileLocalInference} also fires on the device-bridge /
+ * `ELIZA_LOCAL_LLAMA` / riscv64 triggers — none of which set `ELIZA_PLATFORM`.
+ * So a build that enables the mobile local-inference gate without exporting
+ * `ELIZA_PLATFORM` leaves `mobile` false in the selector and could pick
+ * OmniVoice on a phone, violating the Kokoro-exclusive mobile voice invariant.
+ *
+ * This emits exactly one boot-time warning when the gate is active but the
+ * platform flag is absent (the real mismatch). It is a diagnostic, not a
+ * behavior change: the fix is to export `ELIZA_PLATFORM` from the offending
+ * build, which this surfaces. The caller MUST evaluate it on a boot path where
+ * BOTH predicates are checked (i.e. outside any `if (isMobilePlatform())`
+ * branch) — passing the already-computed `mobilePlatform` makes that explicit.
+ *
+ * Kept dependency-free (injectable `warn` + the already-resolved
+ * `mobilePlatform` boolean) so it can be unit-tested without the runtime or a
+ * logger instance, matching the `engine.warnIfParallelTooLow({ warn })` pattern.
+ *
+ * @returns `true` when the warning fired (the mismatch is real), else `false`.
+ */
+export function warnIfMobileGateActiveWithoutPlatform(args: {
+	mobilePlatform: boolean;
+	warn: (message: string) => void;
+	env?: NodeJS.ProcessEnv;
+	arch?: NodeJS.Architecture;
+}): boolean {
+	const { mobilePlatform, warn, env = process.env, arch = process.arch } = args;
+	if (mobilePlatform) return false;
+	if (!shouldEnableMobileLocalInference(env, arch)) return false;
+	warn(
+		"[local-inference] ELIZA_PLATFORM is not set while the mobile local-inference gate is active " +
+			"(ELIZA_DEVICE_BRIDGE_ENABLED / ELIZA_LOCAL_LLAMA / riscv64), so the Kokoro-exclusive mobile " +
+			"voice invariant may be missed. The voice backend selector keys `mobile` off " +
+			"ELIZA_PLATFORM ∈ {ios,android}; with it unset the selector may pick OmniVoice on a phone. " +
+			"Set ELIZA_PLATFORM=android (or ios) on this build.",
+	);
+	return true;
+}

package/src/runtime/voice-entity-binding.transcript.test.ts

@@ -0,0 +1,98 @@
+import type { IAgentRuntime } from "@elizaos/core";
+import { EventType } from "@elizaos/core";
+import { describe, expect, it } from "vitest";
+import type { VoiceAttributionOutput } from "../services/voice/speaker/attribution-pipeline.js";
+import { handleLiveVoiceAttribution } from "./voice-entity-binding.js";
+
+/** Minimal attribution output with an observation (drives the emit path). */
+function output(): VoiceAttributionOutput {
+	return {
+		turnId: "t1",
+		primarySpeaker: { entityId: "entity-jill", confidence: 0.6 },
+		observation: {
+			imprintClusterId: "cluster-1",
+			confidence: 0.6,
+			entityId: "entity-jill",
+		},
+		turn: { metadata: {} },
+		segments: [],
+	} as unknown as VoiceAttributionOutput;
+}
+
+function captureRuntime(): {
+	runtime: IAgentRuntime;
+	events: Array<{ type: unknown; payload: Record<string, unknown> }>;
+} {
+	const events: Array<{ type: unknown; payload: Record<string, unknown> }> = [];
+	const runtime = {
+		emitEvent: async (type: unknown, payload: Record<string, unknown>) => {
+			events.push({ type, payload });
+		},
+	} as unknown as IAgentRuntime;
+	return { runtime, events };
+}
+
+describe("handleLiveVoiceAttribution — transcript carry (#8786)", () => {
+	it("rides the real transcript on VOICE_TURN_OBSERVED when provided", async () => {
+		const { runtime, events } = captureRuntime();
+		await handleLiveVoiceAttribution(runtime, output(), {
+			ownerEntityId: "entity-jill",
+			transcript: "I'm Jill",
+		});
+		const observed = events.find(
+			(e) => e.type === EventType.VOICE_TURN_OBSERVED,
+		);
+		expect(observed).toBeDefined();
+		// Was hardcoded "" — the merge engine's name extraction needs the text.
+		expect(observed?.payload.text).toBe("I'm Jill");
+	});
+
+	it("falls back to '' for diarization-only callers (no transcript)", async () => {
+		const { runtime, events } = captureRuntime();
+		await handleLiveVoiceAttribution(runtime, output(), {
+			ownerEntityId: "entity-jill",
+		});
+		const observed = events.find(
+			(e) => e.type === EventType.VOICE_TURN_OBSERVED,
+		);
+		expect(observed?.payload.text).toBe("");
+	});
+
+	it("also stamps the transcript onto the synthesized turn signal", async () => {
+		const { runtime } = captureRuntime();
+		const signal = await handleLiveVoiceAttribution(runtime, output(), {
+			ownerEntityId: "entity-jill",
+			transcript: "Jill is my wife",
+		});
+		expect(signal.transcript).toBe("Jill is my wife");
+	});
+
+	it("stamps the resolved speaker entityId onto the turn metadata (#8786)", async () => {
+		const { runtime } = captureRuntime();
+		const out = output();
+		await handleLiveVoiceAttribution(runtime, out, {
+			ownerEntityId: "entity-jill",
+			transcript: "I'm Jill",
+		});
+		// The imprint → entityId match rides on the message so providers/extraction
+		// attribute the turn to the right person, not just the EOT gate.
+		const meta = out.turn.metadata as Record<string, unknown>;
+		expect(meta.speakerEntityId).toBe("entity-jill");
+		expect(meta.voiceTurnSignal).toBeDefined();
+	});
+
+	it("omits speakerEntityId for an unbound speaker (never writes a null speaker)", async () => {
+		const { runtime } = captureRuntime();
+		const out = {
+			turnId: "t2",
+			primarySpeaker: { entityId: null, confidence: 0.2 },
+			observation: undefined,
+			turn: { metadata: {} },
+			segments: [],
+		} as unknown as VoiceAttributionOutput;
+		await handleLiveVoiceAttribution(runtime, out, {});
+		const meta = out.turn.metadata as Record<string, unknown>;
+		expect(meta.speakerEntityId).toBeUndefined();
+		expect(meta.voiceTurnSignal).toBeDefined();
+	});
+});