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

package/src/services/backend.test.ts

@@ -0,0 +1,84 @@
+// Coverage for the pure backend-routing decision (#8848). decideBackend is the
+// optimization-kernel enforcement point: a catalog model declares the fused
+// kernels it requires (turbo/qjl/polarquant/…), and the dispatcher computes
+// which of them the installed binary's CAPABILITIES.json does NOT satisfy so the
+// caller can tell the operator to rebuild instead of letting the model silently
+// run de-optimized. These branches gate that contract, so they are pinned here.
+
+import type { CatalogModel } from "@elizaos/shared";
+import { describe, expect, it } from "vitest";
+import { decideBackend } from "./backend";
+
+/** Minimal CatalogModel carrying only the requiresKernel field decideBackend reads. */
+function catalog(requiresKernel: string[]): CatalogModel {
+	return {
+		runtime: { optimizations: { requiresKernel } },
+	} as unknown as CatalogModel;
+}
+
+describe("decideBackend", () => {
+	it("routes to llama-cpp with reason=env-override when forced, regardless of kernels", () => {
+		const d = decideBackend({
+			override: "llama-cpp",
+			catalog: catalog(["turbo3"]),
+			llamaCppAvailable: true,
+		});
+		expect(d.backend).toBe("llama-cpp");
+		expect(d.reason).toBe("env-override");
+		expect(d.kernels).toEqual(["turbo3"]);
+	});
+
+	it("uses reason=default for a model with no required kernels", () => {
+		const d = decideBackend({
+			override: "auto",
+			catalog: undefined,
+			llamaCppAvailable: true,
+		});
+		expect(d.reason).toBe("default");
+		expect(d.kernels).toEqual([]);
+		expect(d.unsatisfiedKernels).toBeUndefined();
+	});
+
+	it("uses reason=kernel-required when the catalog declares required kernels", () => {
+		const d = decideBackend({
+			override: "auto",
+			catalog: catalog(["turbo3", "qjl_full"]),
+			llamaCppAvailable: true,
+		});
+		expect(d.reason).toBe("kernel-required");
+		expect(d.kernels).toEqual(["turbo3", "qjl_full"]);
+		// No CAPABILITIES probe → trust the declaration, defer to load attempt.
+		expect(d.unsatisfiedKernels).toBeUndefined();
+	});
+
+	it("flags the required kernels the installed binary does not satisfy", () => {
+		const d = decideBackend({
+			override: "auto",
+			catalog: catalog(["turbo3", "qjl_full"]),
+			llamaCppAvailable: true,
+			binaryKernels: { turbo3: true, qjl_full: false },
+		});
+		// turbo3 satisfied, qjl_full not → operator must rebuild for qjl_full.
+		expect(d.unsatisfiedKernels).toEqual(["qjl_full"]);
+	});
+
+	it("reports an empty unsatisfied set when every required kernel is present", () => {
+		const d = decideBackend({
+			override: "auto",
+			catalog: catalog(["turbo3"]),
+			llamaCppAvailable: true,
+			binaryKernels: { turbo3: true },
+		});
+		expect(d.unsatisfiedKernels).toEqual([]);
+	});
+
+	it("treats a kernel missing from the probe as unsatisfied (not silently ok)", () => {
+		const d = decideBackend({
+			override: "auto",
+			catalog: catalog(["turbo3", "polarquant"]),
+			llamaCppAvailable: true,
+			binaryKernels: { turbo3: true }, // polarquant absent from the map
+		});
+		expect(d.unsatisfiedKernels).toEqual(["polarquant"]);
+	});
+});

package/src/services/backend.ts

@@ -1,21 +1,33 @@
 /**
  * Local-inference backend interface and dispatcher.
  *
- * One shipping implementation lives behind this interface:
+ * Both shipping backends are served by the SAME in-process FFI
+ * `libelizainference` library behind the SAME streaming symbols — the
+ * difference is which in-process runtime the FFI's `llm_backend_select` drives:
  *
- *   - `llama-cpp`       → the optimized in-process FFI llama.cpp path.
+ *   - `llama-cpp`  → the optimized in-process FFI llama.cpp path (the default).
  *     MTP, n-gram drafter, lookahead, `-ot` MoE offload, TurboQuant KV
- *     cache, mlock/no-mmap/mmproj, etc. all live here.
+ *     cache, mlock/no-mmap/mmproj, etc. all live here. Serves the `.gguf`.
+ *   - `litert-lm`  → the in-process LiteRT-LM backend (Android NPU / GPU
+ *     delegate, gated `-DELIZA_ENABLE_LITERT`). Serves a `.litertlm` text
+ *     artifact staged under `<bundleRoot>/text/`. The dispatcher passes
+ *     `ELIZA_LLM_BACKEND=litert-lm` through the load; the C-side
+ *     `llm_backend_select` reads it (and probes `text/*.litertlm`) and routes
+ *     to the LiteRT factory. See `tools/omnivoice/src/llm-backend.h`.
  *
  * The dispatcher decides which one to use per-load based on:
  *
- *   1. Catalog `runtime.optimizations.requiresKernel` — if any specialised
+ *   1. `ELIZA_INFERENCE_BACKEND` env override — `llama-cpp` / `litert-lm` /
+ *      `auto`. A `litert-lm` force is honoured only when the build/platform
+ *      supports LiteRT and the bundle ships a `.litertlm` (else hard error).
+ *   2. A `.litertlm` text artifact in the bundle AND LiteRT support on this
+ *      build/platform → `litert-lm`. GGUF stays the default whenever the
+ *      LiteRT artifact or the build support is absent.
+ *   3. Catalog `runtime.optimizations.requiresKernel` — if any specialised
  *      llama.cpp kernel is required (e.g. `turbo3`), the
- *      dispatcher MUST pick `llama-cpp`. Legacy bindings cannot
+ *      dispatcher picks `llama-cpp`. Legacy bindings cannot
  *      provide these kernels at all.
- *   2. Catalog `runtime.preferredBackend` — retained for metadata
- *      compatibility, but generation still routes through `llama-cpp`.
- *   3. Default: optimized llama.cpp FFI.
+ *   4. Default: optimized llama.cpp FFI.
  *
  * The dispatcher does NOT own backend internals. It owns selection only,
  * plus a small load-state
@@ -53,6 +65,13 @@ export interface BackendLoadOverrides {
 	bundleRoot?: string;
 	/** Manifest path for direct bundle loads not present in the registry. */
 	manifestPath?: string;
+	/**
+	 * Absolute path to a `.litertlm` LiteRT-LM text artifact staged under
+	 * `<bundleRoot>/text/`, when the bundle ships one. Presence (plus LiteRT
+	 * build/platform support) routes the load to the `litert-lm` backend; the
+	 * `.gguf` `modelPath` stays the GGUF default otherwise.
+	 */
+	litertModelPath?: string;
 }
 
 export interface BackendPlan {
@@ -112,6 +131,14 @@ export interface GenerateArgs extends StructuredGenerateParams {
 	 * streams even when a `grammar` is set).
 	 */
 	onTextChunk?: (chunk: string) => void | Promise<void>;
+	/**
+	 * Max tokens the FFI backend decodes per `llmStreamNext` step — i.e. the
+	 * granularity of `onTextChunk` emission. Smaller ⇒ smoother token-by-token
+	 * streaming to the UI at the cost of more FFI round-trips per response.
+	 * Unset ⇒ the backend default (coarse, throughput-tuned). The text/chat
+	 * handler sets a small value for smooth streaming; voice leaves it unset.
+	 */
+	maxTokensPerStep?: number;
 	/**
 	 * Whether this generation is user-visible text and therefore eligible for
 	 * voice-mode TTS. Internal JSON / planner calls must not be spoken.
@@ -143,6 +170,16 @@ export interface LocalGenerateWithUsageResult {
 	};
 }
 
+/**
+ * The in-process runtime the FFI streaming pipe drives for a given load.
+ * `llama-cpp` is the default GGUF path; `litert-lm` is the LiteRT-LM
+ * `.litertlm` path (same FFI symbols, selected via `ELIZA_LLM_BACKEND` +
+ * the C-side `llm_backend_select`). This is the dispatcher's *selection*,
+ * distinct from `LocalInferenceBackend.id` (the implementation surface, which
+ * stays the single fused FFI backend regardless of the runtime it drives).
+ */
+export type BackendId = "llama-cpp" | "litert-lm";
+
 export interface LocalRuntimeLoadConfig {
 	modelId: string | null;
 	modelPath: string | null;
@@ -152,7 +189,7 @@ export interface LocalRuntimeLoadConfig {
 	gpuLayers: number | null;
 	parallel: number;
 	binaryPath: string | null;
-	backend: "capacitor-llama" | "llama-cpp" | null;
+	backend: BackendId | null;
 	mtp: {
 		specType: "draft-mtp";
 		draftMin: number;
@@ -169,7 +206,7 @@ export interface LocalRuntimeLoadConfig {
  */
 export interface LocalInferenceBackend {
 	/** Identifier for the concrete backend implementation. */
-	readonly id: "capacitor-llama" | "llama-cpp";
+	readonly id: "llama-cpp";
 	available(): Promise<boolean>;
 	load(plan: BackendPlan): Promise<void>;
 	unload(): Promise<void>;
@@ -201,6 +238,12 @@ export interface LocalInferenceBackend {
 		maxTokens?: number;
 		temperature?: number;
 		signal?: AbortSignal;
+		/** Per-token callback for streaming vision describe (ABI v13). When set and
+		 * the backend supports streaming, the description is decoded token-by-token
+		 * through the same pipe as chat text; otherwise the backend returns the
+		 * full description and ignores it. */
+		onTextChunk?: (chunk: string) => void | Promise<void>;
+		maxTokensPerStep?: number;
 	}): Promise<{
 		text: string;
 		projectorMs?: number;
@@ -249,7 +292,15 @@ export interface LocalInferenceBackend {
 	currentRuntimeLoadConfig?(): LocalRuntimeLoadConfig | null;
 }
 
-export type BackendOverride = "auto" | "llama-cpp";
+export type BackendOverride = "auto" | "llama-cpp" | "litert-lm";
+
+/**
+ * The env name the C-side `llm_backend_select` reads to HARD-select an
+ * in-process runtime. The dispatcher sets it to `litert-lm` for a LiteRT load
+ * and clears it for a llama.cpp load so a prior LiteRT select never leaks into
+ * the next GGUF load. Mirrors `tools/omnivoice/src/llm-backend.h`.
+ */
+export const ELIZA_LLM_BACKEND_ENV = "ELIZA_LLM_BACKEND" as const;
 
 export function readBackendOverride(): BackendOverride {
 	const raw = process.env.ELIZA_INFERENCE_BACKEND?.trim().toLowerCase();
@@ -257,9 +308,42 @@ export function readBackendOverride(): BackendOverride {
 	if (raw === "llama-cpp") {
 		return "llama-cpp";
 	}
+	if (raw === "litert-lm" || raw === "litert" || raw === "litert_lm") {
+		return "litert-lm";
+	}
 	return "auto";
 }
 
+/**
+ * Whether the LiteRT-LM in-process backend is usable on THIS build/platform.
+ * The C-side `LlmBackendFactory::available()` is the runtime authority (it is
+ * compiled in only under `-DELIZA_ENABLE_LITERT` and reports false when the
+ * NPU/GPU delegate is absent), but the TS dispatcher must decide *before* the
+ * FFI load whether to route there at all, so we gate on the same signals the
+ * build/launcher exports:
+ *
+ *   - `ELIZA_ENABLE_LITERT=1` — the explicit opt-in the LiteRT-enabled build
+ *     sets (matches the `-DELIZA_ENABLE_LITERT` CMake gate).
+ *   - `ELIZA_PLATFORM=android` — the NPU/GPU-delegate target where a LiteRT
+ *     `.litertlm` bundle is the on-device path.
+ *
+ * A bundle that ships a `.litertlm` but runs on a build without LiteRT support
+ * loads the GGUF (`llama-cpp`) instead — the artifact is additive, never a
+ * requirement. Returns false unless one of the signals is present, so GGUF
+ * stays the default everywhere LiteRT is not wired.
+ */
+export function litertBackendSupported(
+	env: NodeJS.ProcessEnv = process.env,
+): boolean {
+	if (envFlagIn(env, "ELIZA_ENABLE_LITERT")) return true;
+	return env.ELIZA_PLATFORM?.trim().toLowerCase() === "android";
+}
+
+function envFlagIn(env: NodeJS.ProcessEnv, name: string): boolean {
+	const v = env[name]?.trim().toLowerCase();
+	return v === "1" || v === "true" || v === "yes" || v === "on";
+}
+
 function envFlag(name: string): boolean {
 	const v = process.env[name]?.trim().toLowerCase();
 	return v === "1" || v === "true" || v === "yes" || v === "on";
@@ -310,9 +394,29 @@ export function __resetReducedModeWarnedForTests(): void {
 }
 
 export interface BackendDecision {
-	backend: "llama-cpp";
+	/**
+	 * In-process runtime the dispatcher routes this load to. `llama-cpp` (the
+	 * GGUF path) is the default; `litert-lm` is selected only when the bundle
+	 * ships a `.litertlm` AND the build/platform supports LiteRT (or it was
+	 * forced via `ELIZA_INFERENCE_BACKEND=litert-lm`). Both run through the same
+	 * fused `libelizainference` FFI — the selection only changes the env the
+	 * C-side `llm_backend_select` reads.
+	 */
+	backend: BackendId;
 	/** Why this backend was chosen — for diagnostics and warnings. */
-	reason: "env-override" | "kernel-required" | "preferred-backend" | "default";
+	reason:
+		| "env-override"
+		| "kernel-required"
+		| "preferred-backend"
+		| "litert-artifact"
+		| "default";
+	/**
+	 * Absolute path to the selected `.litertlm` artifact when `backend ===
+	 * "litert-lm"`, else undefined. The dispatcher exports
+	 * `ELIZA_LLM_BACKEND=litert-lm` for this load so the FFI picks the LiteRT
+	 * factory; the path is surfaced for diagnostics.
+	 */
+	litertModelPath?: string;
 	/** Required kernels declared by the catalog, when any. */
 	kernels: LocalRuntimeKernel[];
 	/**
@@ -331,19 +435,30 @@ export interface BackendDecision {
  * Pure decision function. Easy to unit-test without spawning anything.
  *
  * Inputs are deliberately explicit — the caller resolves the catalog entry,
- * the binary availability, and the env override before calling us.
+ * the binary availability, the env override, and (for LiteRT) the staged
+ * `.litertlm` path + the build/platform support flag before calling us.
  *
  * `binaryKernels`, when present, is the parsed CAPABILITIES.json kernels
  * map from the installed llama.cpp FFI runtime. The dispatcher uses it to
  * compute `unsatisfiedKernels`; null means the binary is older / has no
  * capabilities probe, in which case we trust the model's declaration and
  * let the load attempt clarify.
+ *
+ * `litertModelPath` is the absolute path to a `.litertlm` text artifact when
+ * the bundle ships one (else undefined); `litertSupported` is whether this
+ * build/platform can run LiteRT ({@link litertBackendSupported}). LiteRT is
+ * selected only when BOTH hold, or when forced via
+ * `ELIZA_INFERENCE_BACKEND=litert-lm` (a forced LiteRT select with no
+ * `.litertlm` or no support throws — no silent downgrade to GGUF). GGUF stays
+ * the default in every other case.
  */
 export function decideBackend(input: {
 	override: BackendOverride;
 	catalog: CatalogModel | undefined;
 	llamaCppAvailable: boolean;
 	binaryKernels?: Partial<Record<LocalRuntimeKernel | string, boolean>> | null;
+	litertModelPath?: string | null;
+	litertSupported?: boolean;
 }): BackendDecision {
 	const { override, catalog } = input;
 	const optimizations = catalog?.runtime?.optimizations;
@@ -352,7 +467,38 @@ export function decideBackend(input: {
 		kernels,
 		input.binaryKernels ?? null,
 	);
+	const litertModelPath = input.litertModelPath ?? undefined;
+	const litertSupported = input.litertSupported ?? false;
+
+	// `ELIZA_INFERENCE_BACKEND=litert-lm` HARD-forces the LiteRT runtime. It is a
+	// real select, not a hint: a forced LiteRT load with no staged `.litertlm`
+	// or on a build without LiteRT support is an error, never a silent fall back
+	// to GGUF (Commandment 8 — don't paper over a broken pipeline).
+	if (override === "litert-lm") {
+		if (!litertSupported) {
+			throw new Error(
+				"[local-inference] ELIZA_INFERENCE_BACKEND=litert-lm forces the LiteRT-LM " +
+					"backend, but this build/platform does not support it (set ELIZA_ENABLE_LITERT=1 " +
+					"on a LiteRT-enabled build, or run on android). Use llama-cpp, or unset the override.",
+			);
+		}
+		if (!litertModelPath) {
+			throw new Error(
+				"[local-inference] ELIZA_INFERENCE_BACKEND=litert-lm forces the LiteRT-LM " +
+					"backend, but the bundle ships no .litertlm text artifact under text/. " +
+					"Stage a .litertlm into the bundle, or use llama-cpp.",
+			);
+		}
+		return {
+			backend: "litert-lm",
+			reason: "env-override",
+			litertModelPath,
+			kernels,
+			unsatisfiedKernels,
+		};
+	}
 
+	// `ELIZA_INFERENCE_BACKEND=llama-cpp` forces the fused GGUF path explicitly.
 	if (override === "llama-cpp") {
 		return {
 			backend: "llama-cpp",
@@ -362,6 +508,19 @@ export function decideBackend(input: {
 		};
 	}
 
+	// Auto: when the bundle ships a `.litertlm` AND this build/platform supports
+	// LiteRT, route there (it is the on-device NPU/GPU-delegate path). GGUF stays
+	// the default whenever the artifact or the support is absent.
+	if (litertSupported && litertModelPath) {
+		return {
+			backend: "litert-lm",
+			reason: "litert-artifact",
+			litertModelPath,
+			kernels,
+			unsatisfiedKernels,
+		};
+	}
+
 	if (kernels.length > 0) {
 		return {
 			backend: "llama-cpp",
@@ -412,7 +571,7 @@ export function resolveCatalogForPlan(
  * they differ.
  */
 export class BackendDispatcher implements LocalInferenceBackend {
-	readonly id = "capacitor-llama" as const;
+	readonly id = "llama-cpp" as const;
 	// The dispatcher's `id` is informational; the active backend's id is what
 	// matters for diagnostics. We expose `activeBackendId()` for that.
 
@@ -438,7 +597,7 @@ export class BackendDispatcher implements LocalInferenceBackend {
 		return this.ffiStreaming.available();
 	}
 
-	activeBackendId(): "capacitor-llama" | "llama-cpp" | null {
+	activeBackendId(): "llama-cpp" | null {
 		return this.active ? this.active.id : null;
 	}
 
@@ -457,13 +616,33 @@ export class BackendDispatcher implements LocalInferenceBackend {
 			catalog,
 			llamaCppAvailable: this.probeFfiAvailable(),
 			binaryKernels: this.probeBinaryKernels?.() ?? null,
+			litertModelPath: plan.overrides?.litertModelPath ?? null,
+			litertSupported: litertBackendSupported(),
 		});
 	}
 
 	async load(plan: BackendPlan): Promise<void> {
-		let effectivePlan = plan;
 		const decision = this.decide(plan);
-		if (decision.unsatisfiedKernels && decision.unsatisfiedKernels.length > 0) {
+
+		// Tell the C-side `llm_backend_select` which in-process runtime to drive.
+		// `litert-lm` sets the HARD select; the GGUF path clears it so a prior
+		// LiteRT select never leaks into the next llama.cpp load. The FFI library
+		// is the same singleton either way (`this.ffiStreaming`); only the env
+		// (read at `_open`) changes which factory it picks.
+		if (decision.backend === "litert-lm") {
+			process.env[ELIZA_LLM_BACKEND_ENV] = "litert-lm";
+		} else {
+			delete process.env[ELIZA_LLM_BACKEND_ENV];
+		}
+
+		let effectivePlan = plan;
+		// Kernel-mismatch enforcement is a llama.cpp-only contract — the LiteRT
+		// `.litertlm` path uses none of the fork's KV kernels, so skip it there.
+		if (
+			decision.backend === "llama-cpp" &&
+			decision.unsatisfiedKernels &&
+			decision.unsatisfiedKernels.length > 0
+		) {
 			const missing = decision.unsatisfiedKernels.join(", ");
 			if (localAllowStockKv()) {
 				// Reduced-optimization local mode: the build hasn't dispatched these
@@ -488,7 +667,7 @@ export class BackendDispatcher implements LocalInferenceBackend {
 				);
 			}
 		}
-		if (decision.backend === "llama-cpp" && !this.probeFfiAvailable()) {
+		if (!this.probeFfiAvailable()) {
 			throw new Error(
 				"[local-inference] Optimized llama.cpp requires the in-process FFI backend. " +
 					"Install/rebuild libelizainference with streaming-LLM + MTP support; " +

package/src/services/bionic-host-loader.test.ts

@@ -1,4 +1,7 @@
+import fs from "node:fs";
 import net from "node:net";
+import os from "node:os";
+import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { BionicHostLoader } from "./bionic-host-loader";
 
@@ -38,14 +41,35 @@ function startHost(
 }
 
 let host: net.Server | null = null;
+const tempDirs: string[] = [];
 afterEach(() => {
 	host?.close();
 	host = null;
+	for (const dir of tempDirs.splice(0)) {
+		fs.rmSync(dir, { recursive: true, force: true });
+	}
 });
 
 const SOCK = `eliza-bionic-test-${process.pid}`;
+const describeLinuxOnly =
+	process.platform === "linux" ? describe : describe.skip;
 
-describe("BionicHostLoader (real abstract-UDS)", () => {
+function makeBundleModelPath(manifest: unknown = {}): string {
+	const bundleRoot = fs.mkdtempSync(
+		path.join(os.tmpdir(), "eliza-bionic-bundle-"),
+	);
+	tempDirs.push(bundleRoot);
+	fs.mkdirSync(path.join(bundleRoot, "text"), { recursive: true });
+	fs.mkdirSync(path.join(bundleRoot, "asr"), { recursive: true });
+	fs.writeFileSync(path.join(bundleRoot, "asr", "gemma-asr.gguf"), "asr");
+	fs.writeFileSync(
+		path.join(bundleRoot, "eliza-1.manifest.json"),
+		JSON.stringify(manifest),
+	);
+	return path.join(bundleRoot, "text", "model.gguf");
+}
+
+describeLinuxOnly("BionicHostLoader (real abstract-UDS)", () => {
 	it("round-trips a buffered generate and returns the host completion", async () => {
 		let seen: Record<string, unknown> | null = null;
 		host = startHost(SOCK, (req) => {
@@ -130,4 +154,73 @@ describe("BionicHostLoader (real abstract-UDS)", () => {
 		await loader.loadModel({ modelPath: "/m/text/x.gguf" });
 		await expect(loader.generate({ prompt: "x" })).rejects.toThrow();
 	});
+
+	it("transcribe forwards op=asr with pcm + sampleRate and returns the transcript", async () => {
+		let seen: Record<string, unknown> | null = null;
+		host = startHost(SOCK, (req) => {
+			seen = req;
+			return JSON.stringify({ ok: true, text: "the quick brown fox" });
+		});
+		const loader = new BionicHostLoader(SOCK);
+		const modelPath = makeBundleModelPath();
+		await loader.loadModel({ modelPath });
+		const out = await loader.transcribe({
+			pcmBase64: "AAAA",
+			sampleRate: 16000,
+		});
+		expect(out).toBe("the quick brown fox");
+		expect(seen).toMatchObject({
+			op: "asr",
+			pcmBase64: "AAAA",
+			sampleRate: 16000,
+			bundleDir: path.dirname(path.dirname(modelPath)),
+		});
+	});
+
+	it("transcribe refuses Qwen ASR provenance before contacting the host", async () => {
+		const loader = new BionicHostLoader(SOCK);
+		await loader.loadModel({
+			modelPath: makeBundleModelPath({
+				lineage: { asr: { base: "Qwen3-ASR" } },
+			}),
+		});
+		await expect(
+			loader.transcribe({ pcmBase64: "AAAA", sampleRate: 16000 }),
+		).rejects.toThrow(/Qwen ASR provenance/);
+	});
+
+	it("describeImage forwards op=image with bytes + prompt and returns the description", async () => {
+		let seen: Record<string, unknown> | null = null;
+		host = startHost(SOCK, (req) => {
+			seen = req;
+			return JSON.stringify({ ok: true, text: "a cat on a desk" });
+		});
+		const loader = new BionicHostLoader(SOCK);
+		await loader.loadModel({
+			modelPath: "/data/x/eliza-1/bundle/text/model.gguf",
+		});
+		const out = await loader.describeImage({
+			imageBase64: "iVBORw0K",
+			prompt: "what is this?",
+		});
+		expect(out).toBe("a cat on a desk");
+		expect(seen).toMatchObject({
+			op: "image",
+			imageBase64: "iVBORw0K",
+			prompt: "what is this?",
+			mmprojPath: "",
+			bundleDir: "/data/x/eliza-1/bundle",
+		});
+	});
+
+	it("transcribe throws on host ok:false", async () => {
+		host = startHost(SOCK, () =>
+			JSON.stringify({ ok: false, error: "no asr weights staged" }),
+		);
+		const loader = new BionicHostLoader(SOCK);
+		await loader.loadModel({ modelPath: makeBundleModelPath() });
+		await expect(
+			loader.transcribe({ pcmBase64: "AAAA", sampleRate: 16000 }),
+		).rejects.toThrow(/no asr weights staged/);
+	});
 });

package/src/services/bionic-host-loader.ts

@@ -28,6 +28,10 @@ import type {
 	LocalInferenceLoadArgs,
 	LocalInferenceLoader,
 } from "./active-model";
+import {
+	bundleHasAsrModelFiles,
+	readBundleAsrProvenanceBlockers,
+} from "./asr-provenance";
 
 /** Connect + full round-trip budget. A cold GPU decode of a long reply fits. */
 const REQUEST_TIMEOUT_MS = 120_000;
@@ -43,6 +47,13 @@ interface BionicGenerateResponse {
 	tokS?: number;
 }
 
+/** {ok, text} response for the asr / image ops (transcript / description). */
+interface BionicTextResponse {
+	ok: boolean;
+	text?: string;
+	error?: string;
+}
+
 /**
  * Derive the fused-bundle root from a model GGUF path. The host's
  * `eliza_inference_create(bundleDir)` expects the directory that contains
@@ -106,6 +117,67 @@ export class BionicHostLoader implements LocalInferenceLoader {
 		return res.text ?? "";
 	}
 
+	/**
+	 * On-device STT: transcribe mono fp32 PCM via the bionic host's fused
+	 * Gemma ASR path (op="asr"). The musl agent can't load the fused lib, so
+	 * the TRANSCRIPTION delegate routes the audio here over the UDS and gets
+	 * the transcript back. `pcm` is little-endian fp32 already base64-encoded.
+	 */
+	async transcribe(args: {
+		pcmBase64: string;
+		sampleRate: number;
+	}): Promise<string> {
+		if (!this.bundleDir || !bundleHasAsrModelFiles(this.bundleDir)) {
+			throw new Error(
+				"[BionicHostLoader] host asr requires an active Gemma ASR-capable bundle; refusing to use the bionic host default bundle",
+			);
+		}
+		const blockers = readBundleAsrProvenanceBlockers(this.bundleDir);
+		if (blockers.length > 0) {
+			throw new Error(
+				`[BionicHostLoader] host asr refused non-Gemma ASR provenance: ${blockers.join("; ")}`,
+			);
+		}
+		const res = await this.roundTrip<BionicTextResponse>({
+			op: "asr",
+			bundleDir: this.bundleDir,
+			pcmBase64: args.pcmBase64,
+			sampleRate: args.sampleRate,
+		});
+		if (!res.ok) {
+			throw new Error(
+				`[BionicHostLoader] host asr failed: ${res.error ?? "unknown error"}`,
+			);
+		}
+		return res.text ?? "";
+	}
+
+	/**
+	 * On-device vision / screen-recognition: describe a raw image (PNG/JPEG/WebP
+	 * bytes, base64) via the bionic host's mmproj describe-image (op="image").
+	 * `mmprojPath` may be empty — the host resolves the projector from the
+	 * bundle's `vision/` dir.
+	 */
+	async describeImage(args: {
+		imageBase64: string;
+		mmprojPath?: string;
+		prompt?: string;
+	}): Promise<string> {
+		const res = await this.roundTrip<BionicTextResponse>({
+			op: "image",
+			bundleDir: this.bundleDir,
+			imageBase64: args.imageBase64,
+			mmprojPath: args.mmprojPath ?? "",
+			prompt: args.prompt ?? "",
+		});
+		if (!res.ok) {
+			throw new Error(
+				`[BionicHostLoader] host image describe failed: ${res.error ?? "unknown error"}`,
+			);
+		}
+		return res.text ?? "";
+	}
+
 	/**
 	 * One request → one response over a fresh connection. Length-prefixed frames:
 	 * `[int32 BE byte length][UTF-8 JSON]` in each direction.

package/src/services/cache-bridge.test.ts

@@ -109,28 +109,28 @@ describe("cache-bridge path layout", () => {
 
 	it("buildModelHash is stable + sensitive to its inputs", () => {
 		const a = buildModelHash({
-			targetModelPath: "/models/eliza-1-0_8b.gguf",
-			drafterModelPath: "/models/eliza-1-0_8b-drafter.gguf",
+			targetModelPath: "/models/eliza-1-2b.gguf",
+			drafterModelPath: "/models/eliza-1-2b-drafter.gguf",
 			cacheTypeK: "f16",
 			cacheTypeV: "f16",
 		});
 		const b = buildModelHash({
-			targetModelPath: "/models/eliza-1-0_8b.gguf",
-			drafterModelPath: "/models/eliza-1-0_8b-drafter.gguf",
+			targetModelPath: "/models/eliza-1-2b.gguf",
+			drafterModelPath: "/models/eliza-1-2b-drafter.gguf",
 			cacheTypeK: "f16",
 			cacheTypeV: "f16",
 		});
 		expect(a).toBe(b);
 		const c = buildModelHash({
-			targetModelPath: "/models/eliza-1-0_8b.gguf",
+			targetModelPath: "/models/eliza-1-2b.gguf",
 			drafterModelPath: "/models/other-drafter.gguf",
 			cacheTypeK: "f16",
 			cacheTypeV: "f16",
 		});
 		expect(c).not.toBe(a);
 		const d = buildModelHash({
-			targetModelPath: "/models/eliza-1-0_8b.gguf",
-			drafterModelPath: "/models/eliza-1-0_8b-drafter.gguf",
+			targetModelPath: "/models/eliza-1-2b.gguf",
+			drafterModelPath: "/models/eliza-1-2b-drafter.gguf",
 			cacheTypeK: "q8_0",
 			cacheTypeV: "f16",
 		});