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

package/src/services/imagegen/backend-selector.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, it } from "vitest";
+import {
+	type ImageGenRuntimeProfile,
+	resolveDefaultImageGenModel,
+	selectImageGenBackends,
+} from "./backend-selector";
+
+/**
+ * Image-gen backend selection (#8848 / WS3).
+ *
+ * `selectImageGenBackends` is the deterministic per-platform decision tree the
+ * arbiter walks at model-load time; `resolveDefaultImageGenModel` maps a tier
+ * id to a concrete diffusion file. The whole `imagegen/` dir was untested, so a
+ * regression in the accelerator ordering or the `requiredAccelerator` override
+ * (which exists precisely so release smoke tests can't silently fall back to
+ * CPU) would pass unnoticed. Both functions are pure.
+ */
+
+const profile = (
+	o: Partial<ImageGenRuntimeProfile>,
+): ImageGenRuntimeProfile => ({
+	platform: "linux",
+	arch: "x64",
+	...o,
+});
+
+describe("selectImageGenBackends — requiredAccelerator override", () => {
+	it("pins a single backend for each explicit accelerator", () => {
+		expect(
+			selectImageGenBackends(profile({ requiredAccelerator: "cuda" })),
+		).toEqual([{ backendId: "sd-cpp", accelerator: "cuda" }]);
+		expect(
+			selectImageGenBackends(profile({ requiredAccelerator: "vulkan" })),
+		).toEqual([{ backendId: "sd-cpp", accelerator: "vulkan" }]);
+		expect(
+			selectImageGenBackends(profile({ requiredAccelerator: "cpu" })),
+		).toEqual([{ backendId: "sd-cpp", accelerator: "cpu" }]);
+		expect(
+			selectImageGenBackends(profile({ requiredAccelerator: "coreml" })),
+		).toEqual([{ backendId: "coreml", accelerator: "coreml" }]);
+		expect(
+			selectImageGenBackends(profile({ requiredAccelerator: "tensorrt" })),
+		).toEqual([{ backendId: "tensorrt", accelerator: "tensorrt" }]);
+	});
+
+	it("routes a required metal accelerator to mflux only on Apple Silicon", () => {
+		expect(
+			selectImageGenBackends(
+				profile({
+					requiredAccelerator: "metal",
+					platform: "darwin",
+					arch: "arm64",
+				}),
+			),
+		).toEqual([{ backendId: "mflux", accelerator: "metal" }]);
+		// Intel Mac (or anything not darwin/arm64) → sd-cpp metal.
+		expect(
+			selectImageGenBackends(
+				profile({
+					requiredAccelerator: "metal",
+					platform: "darwin",
+					arch: "x64",
+				}),
+			),
+		).toEqual([{ backendId: "sd-cpp", accelerator: "metal" }]);
+	});
+
+	it("lets the explicit override win over the mobile shells", () => {
+		expect(
+			selectImageGenBackends(
+				profile({ requiredAccelerator: "cuda", isIos: true }),
+			),
+		).toEqual([{ backendId: "sd-cpp", accelerator: "cuda" }]);
+	});
+});
+
+describe("selectImageGenBackends — platform policy", () => {
+	it("returns Core ML only on iOS and aosp only on Android", () => {
+		expect(selectImageGenBackends(profile({ isIos: true }))).toEqual([
+			{ backendId: "coreml", accelerator: "coreml" },
+		]);
+		expect(selectImageGenBackends(profile({ isAndroid: true }))).toEqual([
+			{ backendId: "aosp", accelerator: "auto" },
+		]);
+	});
+
+	it("orders mflux→sd-cpp on Apple Silicon, sd-cpp auto→cpu on Intel Mac", () => {
+		expect(
+			selectImageGenBackends(profile({ platform: "darwin", arch: "arm64" })),
+		).toEqual([
+			{ backendId: "mflux", accelerator: "metal" },
+			{ backendId: "sd-cpp", accelerator: "cpu" },
+		]);
+		expect(
+			selectImageGenBackends(profile({ platform: "darwin", arch: "x64" })),
+		).toEqual([
+			{ backendId: "sd-cpp", accelerator: "auto" },
+			{ backendId: "sd-cpp", accelerator: "cpu" },
+		]);
+	});
+
+	it("orders tensorrt→cuda→cpu on Windows NVIDIA and vulkan→cpu on Windows AMD", () => {
+		expect(
+			selectImageGenBackends(profile({ platform: "win32", gpu: "nvidia" })),
+		).toEqual([
+			{ backendId: "tensorrt", accelerator: "tensorrt" },
+			{ backendId: "sd-cpp", accelerator: "cuda" },
+			{ backendId: "sd-cpp", accelerator: "cpu" },
+		]);
+		expect(
+			selectImageGenBackends(profile({ platform: "win32", gpu: "amd" })),
+		).toEqual([
+			{ backendId: "sd-cpp", accelerator: "vulkan" },
+			{ backendId: "sd-cpp", accelerator: "cpu" },
+		]);
+		expect(
+			selectImageGenBackends(profile({ platform: "win32", gpu: "none" })),
+		).toEqual([{ backendId: "sd-cpp", accelerator: "cpu" }]);
+	});
+
+	it("gates Linux NVIDIA CUDA on real sd-cpp evidence", () => {
+		// GPU vendor alone is NOT evidence the installed binary has CUDA.
+		expect(
+			selectImageGenBackends(profile({ platform: "linux", gpu: "nvidia" })),
+		).toEqual([{ backendId: "sd-cpp", accelerator: "cpu" }]);
+		// cudaCapable evidence promotes CUDA ahead of the CPU fallback.
+		expect(
+			selectImageGenBackends(
+				profile({
+					platform: "linux",
+					gpu: "nvidia",
+					sdCpp: { cudaCapable: true },
+				}),
+			),
+		).toEqual([
+			{ backendId: "sd-cpp", accelerator: "cuda" },
+			{ backendId: "sd-cpp", accelerator: "cpu" },
+		]);
+		// an accelerators list that includes cuda is equivalent evidence.
+		expect(
+			selectImageGenBackends(
+				profile({
+					platform: "linux",
+					gpu: "nvidia",
+					sdCpp: { accelerators: ["cuda"] },
+				}),
+			),
+		).toEqual([
+			{ backendId: "sd-cpp", accelerator: "cuda" },
+			{ backendId: "sd-cpp", accelerator: "cpu" },
+		]);
+	});
+
+	it("falls back to sd-cpp CPU for an unknown platform", () => {
+		expect(
+			selectImageGenBackends(
+				profile({ platform: "freebsd" as ImageGenRuntimeProfile["platform"] }),
+			),
+		).toEqual([{ backendId: "sd-cpp", accelerator: "cpu" }]);
+	});
+});
+
+describe("resolveDefaultImageGenModel", () => {
+	it("resolves a small tier to the SD-1.5 file (no split-diffusion fields)", () => {
+		expect(resolveDefaultImageGenModel("eliza-1-2b")).toEqual({
+			modelId: "imagegen-sd-1_5-q5_0",
+			file: "imagegen/sd-1.5-Q5_0.gguf",
+		});
+	});
+
+	it("resolves a large tier to the split Z-Image diffusion bundle", () => {
+		expect(resolveDefaultImageGenModel("eliza-1-9b")).toMatchObject({
+			modelId: "imagegen-z-image-turbo-q4_k_m",
+			file: "imagegen/z-image-turbo-Q4_K_M.gguf",
+			splitDiffusionModel: true,
+			vae: "imagegen/vae/ae.safetensors",
+		});
+	});
+
+	it("echoes back a bare model id that matches a known tier entry", () => {
+		expect(resolveDefaultImageGenModel("imagegen-sd-1_5-q5_0")).toMatchObject({
+			modelId: "imagegen-sd-1_5-q5_0",
+			file: "imagegen/sd-1.5-Q5_0.gguf",
+		});
+	});
+
+	it("returns null for an unknown key", () => {
+		expect(resolveDefaultImageGenModel("does-not-exist")).toBeNull();
+	});
+});

package/src/services/imagegen/sd-cpp.ts

@@ -108,6 +108,7 @@ export type SdCppSpawnLike = (
 	stdout: AsyncIterable<Buffer> | NodeJS.ReadableStream | null;
 	stderr: AsyncIterable<Buffer> | NodeJS.ReadableStream | null;
 	on(event: "exit", listener: (code: number | null) => void): unknown;
+	on(event: "close", listener: (code: number | null) => void): unknown;
 	on(event: "error", listener: (err: Error) => void): unknown;
 	kill?(signal?: NodeJS.Signals): void;
 };
@@ -389,14 +390,7 @@ function runCollect(
 		proc.on("error", (err: Error) => reject(err));
 		if (typeof (proc as { on?: unknown }).on === "function") {
 			try {
-				(
-					proc as unknown as {
-						on(
-							event: "close",
-							listener: (code: number | null) => void,
-						): unknown;
-					}
-				).on("close", finish);
+				proc.on("close", finish);
 			} catch {
 				// Test doubles may only implement the narrower SdCppSpawnLike
 				// exit/error event set. The exit listener below still resolves.
@@ -714,5 +708,8 @@ export function assertPngOutput(
 export function defaultSpawn(
 	spawnImpl: SdCppSpawnLike | undefined,
 ): SdCppSpawnLike {
-	return spawnImpl ?? (spawn as unknown as SdCppSpawnLike);
+	if (spawnImpl) return spawnImpl;
+	const nodeSpawn: SdCppSpawnLike = (command, args, options) =>
+		spawn(command, [...args], options);
+	return nodeSpawn;
 }

package/src/services/index.ts

@@ -6,12 +6,15 @@ export {
 export {
 	type BackendDecision,
 	BackendDispatcher,
+	type BackendId,
 	type BackendOverride,
 	type BackendPlan,
 	decideBackend,
+	ELIZA_LLM_BACKEND_ENV,
 	type GenerateArgs as BackendGenerateArgs,
 	type GenerateResult,
 	type LocalInferenceBackend,
+	litertBackendSupported,
 	readBackendOverride,
 	resolveCatalogForPlan,
 } from "./backend";
@@ -30,6 +33,11 @@ export {
 	type LocalGenerateOutcome,
 	makeCloudFallbackHandler,
 } from "./cloud-fallback";
+export {
+	computeRuntimeContextFit,
+	type RuntimeContextFit,
+	type RuntimeContextFitInput,
+} from "./context-fit";
 export {
 	buildDeviceResourceMetricsDevPayload,
 	type DeviceBridgeStatus,
@@ -132,6 +140,16 @@ export {
 	setMemoryArbiter,
 	tryGetMemoryArbiter,
 } from "./memory-arbiter";
+export {
+	buildMemoryBenchmarkPlan,
+	buildMemoryBenchmarkReport,
+	type MemoryBenchmarkLoadResult,
+	type MemoryBenchmarkModelPlan,
+	type MemoryBenchmarkOptions,
+	type MemoryBenchmarkReport,
+	runMemoryBenchmark,
+	summarizeMemoryBenchmark,
+} from "./memory-benchmark";
 export {
 	type CapacitorPressureSource,
 	capacitorPressureSource,

package/src/services/ios-llama-streaming.ts

@@ -141,7 +141,7 @@ interface CapacitorWindow {
 }
 
 function tryGetCapacitorPlugin(): CapacitorLlamaStreamingPlugin | null {
-	const w = globalThis as unknown as CapacitorWindow;
+	const w = globalThis as CapacitorWindow;
 	const plugin = w.Capacitor?.Plugins?.LlamaStreaming;
 	if (!plugin) return null;
 	if (

package/src/services/kv-spill.ts

@@ -96,11 +96,12 @@ export interface KvGeometry {
 
 /**
  * Fallback per-token KV estimate when the manifest doesn't carry an explicit
- * figure. Order-of-magnitude only: QJL K-cache is ~1 bit/coord + a bf16 norm,
- * Polar V-cache is ~4 bits/coord + per-block norms, summed over the
- * full-attention layers. For Qwen3.5-class geometry that lands roughly at
- * the table below (bytes/token across the whole cache). These are the figures
- * the catalog's per-tier `ramBudgetMb` was sized against.
+ * figure. Order-of-magnitude only. Gemma 4 E2B uses stock q8_0 KV over an MQA
+ * geometry (n_head_kv=1) with dual head dims — 512 global / 256 SWA — summed
+ * over the global + sliding-window attention layers. For Gemma-4-class
+ * geometry that lands roughly at the table below (bytes/token across the whole
+ * cache). These are the figures the catalog's per-tier `ramBudgetMb` was sized
+ * against.
  */
 const QUANTIZED_KV_BYTES_PER_TOKEN_BY_PARAMS: Readonly<Record<string, number>> =
 	{

package/src/services/lib-target.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it } from "vitest";
+import {
+	libStagedName,
+	resolveHostLibTargets,
+	selectBundleLibFiles,
+} from "./lib-target";
+import { Eliza1LibFileEntrySchema } from "./manifest";
+
+const SHA = "a".repeat(64);
+const entry = (target: string, p: string, name?: string) => ({
+	target,
+	path: p,
+	sha256: SHA,
+	...(name ? { name } : {}),
+});
+
+describe("resolveHostLibTargets", () => {
+	it("pins to ELIZA_INFERENCE_LIB_TARGET when set", () => {
+		expect(
+			resolveHostLibTargets({
+				env: { ELIZA_INFERENCE_LIB_TARGET: "win-x64-cuda" },
+				platform: "linux",
+				arch: "x64",
+			}),
+		).toEqual(["win-x64-cuda"]);
+	});
+
+	it("returns [] on mobile (phones ship the lib natively)", () => {
+		expect(
+			resolveHostLibTargets({
+				env: { ELIZA_PLATFORM: "android" },
+				platform: "linux",
+				arch: "arm64",
+			}),
+		).toEqual([]);
+		expect(
+			resolveHostLibTargets({
+				env: { ELIZA_PLATFORM: "ios" },
+				platform: "darwin",
+				arch: "arm64",
+			}),
+		).toEqual([]);
+	});
+
+	it("maps darwin/arm64 to the metal set first (metal carries CPU fallback)", () => {
+		expect(
+			resolveHostLibTargets({ env: {}, platform: "darwin", arch: "arm64" }),
+		).toEqual(["darwin-arm64-metal", "darwin-arm64-cpu", "darwin-arm64"]);
+	});
+
+	it("prefers CPU on win32 by default, GPU when preferGpu", () => {
+		expect(
+			resolveHostLibTargets({ env: {}, platform: "win32", arch: "x64" }),
+		).toEqual(["win-x64-cpu", "win-x64", "win-x64-cuda"]);
+		expect(
+			resolveHostLibTargets({
+				env: {},
+				platform: "win32",
+				arch: "x64",
+				preferGpu: true,
+			}),
+		).toEqual(["win-x64-cuda", "win-x64-cpu", "win-x64"]);
+	});
+
+	it("maps linux/x64", () => {
+		expect(
+			resolveHostLibTargets({ env: {}, platform: "linux", arch: "x64" }),
+		).toEqual(["linux-x64-cpu", "linux-x64", "linux-x64-cuda"]);
+	});
+});
+
+describe("selectBundleLibFiles", () => {
+	it("returns null when the bundle has no lib[]", () => {
+		expect(selectBundleLibFiles({ files: {} }, ["win-x64-cpu"])).toBeNull();
+		expect(
+			selectBundleLibFiles({ files: { lib: [] } }, ["win-x64-cpu"]),
+		).toBeNull();
+	});
+
+	it("returns null when no host target matches", () => {
+		expect(
+			selectBundleLibFiles(
+				{ files: { lib: [entry("linux-x64-cpu", "lib/x.so")] } },
+				["win-x64-cpu", "win-x64"],
+			),
+		).toBeNull();
+	});
+
+	it("picks the first matching target in preference order, with all its files", () => {
+		const lib = [
+			entry("win-x64-cpu", "lib/cpu/elizainference.dll"),
+			entry("win-x64-cpu", "lib/cpu/ggml.dll"),
+			entry("win-x64-cuda", "lib/cuda/elizainference.dll"),
+		];
+		const cudaFirst = selectBundleLibFiles({ files: { lib } }, [
+			"win-x64-cuda",
+			"win-x64-cpu",
+		]);
+		expect(cudaFirst?.target).toBe("win-x64-cuda");
+		expect(cudaFirst?.files).toHaveLength(1);
+
+		const cpuFirst = selectBundleLibFiles({ files: { lib } }, [
+			"win-x64-cpu",
+			"win-x64-cuda",
+		]);
+		expect(cpuFirst?.target).toBe("win-x64-cpu");
+		expect(cpuFirst?.files).toHaveLength(2);
+	});
+});
+
+describe("libStagedName", () => {
+	it("uses the basename of path", () => {
+		expect(libStagedName(entry("t", "lib/win-x64/elizainference.dll"))).toBe(
+			"elizainference.dll",
+		);
+	});
+
+	it("prefers name when set, reduced to a basename (no path traversal)", () => {
+		expect(libStagedName(entry("t", "a/b.dll", "custom.dll"))).toBe(
+			"custom.dll",
+		);
+		expect(libStagedName(entry("t", "a/b.dll", "../../evil.dll"))).toBe(
+			"evil.dll",
+		);
+	});
+});
+
+describe("Eliza1LibFileEntrySchema", () => {
+	it("accepts a valid platform-targeted lib entry", () => {
+		const e = Eliza1LibFileEntrySchema.parse({
+			path: "lib/win-x64/elizainference.dll",
+			sha256: SHA,
+			target: "win-x64-cpu",
+			name: "elizainference.dll",
+		});
+		expect(e.target).toBe("win-x64-cpu");
+		expect(e.name).toBe("elizainference.dll");
+	});
+
+	it("requires a target", () => {
+		expect(() =>
+			Eliza1LibFileEntrySchema.parse({ path: "x", sha256: SHA }),
+		).toThrow();
+	});
+});

package/src/services/lib-target.ts

@@ -0,0 +1,102 @@
+/**
+ * Host → fused-lib target resolution for bundle delivery (#9105 / local-
+ * inference).
+ *
+ * An Eliza-1 bundle's `files.lib[]` carries the fused `libelizainference` SET
+ * (the fused lib + its ggml/llama/mtmd sibling backends) per platform `target`.
+ * The downloader fetches ONLY the set matching the host into `<bundleRoot>/lib/`,
+ * which the desktop FFI runtime resolves with no env wiring
+ * (`desktop-fused-ffi-backend-runtime.ts` `resolveFusedLibraryPath`, path #2).
+ *
+ * Pure + injectable (platform / arch / env are all overridable) so the mapping
+ * is unit-testable on any host.
+ */
+
+import type { Eliza1Files, Eliza1LibFileEntry } from "./manifest";
+
+export interface HostLibTargetOptions {
+	platform?: NodeJS.Platform;
+	arch?: string;
+	env?: NodeJS.ProcessEnv;
+	/** Prefer a GPU-accelerated target when the bundle hosts one. */
+	preferGpu?: boolean;
+}
+
+function platformKey(platform: NodeJS.Platform): string {
+	if (platform === "win32") return "win";
+	return platform; // "linux" | "darwin"
+}
+
+/**
+ * Ordered list of acceptable `target` keys for the host, best-first. The
+ * downloader picks the first target the bundle actually hosts.
+ *
+ *   - `ELIZA_INFERENCE_LIB_TARGET` pins a single target (power users / CI).
+ *   - Mobile (`ELIZA_PLATFORM=android|ios`) returns `[]` — phones ship the lib
+ *     natively (jniLibs / xcframework), never via bundle delivery.
+ *   - CPU is preferred by default: the fused lib always has GGML_CPU built in,
+ *     so the CPU set works on every host and is the smallest download. GPU sets
+ *     (`…-cuda`) are opt-in via `preferGpu` or the env pin.
+ *   - macOS arm64 maps to the `metal` set, which itself carries the CPU
+ *     fallback, so it is the canonical mac target.
+ */
+export function resolveHostLibTargets(
+	opts: HostLibTargetOptions = {},
+): string[] {
+	const platform = opts.platform ?? process.platform;
+	const arch = opts.arch ?? process.arch;
+	const env = opts.env ?? process.env;
+
+	const mobile = (env.ELIZA_PLATFORM ?? "").toLowerCase();
+	if (mobile === "android" || mobile === "ios") return [];
+
+	const pinned = env.ELIZA_INFERENCE_LIB_TARGET?.trim();
+	if (pinned) return [pinned];
+
+	const base = `${platformKey(platform)}-${arch}`;
+	const cpu = `${base}-cpu`;
+	const cuda = `${base}-cuda`;
+	const metal = `${base}-metal`;
+
+	if (platform === "darwin") {
+		// The metal set carries a CPU fallback, so it is the mac default.
+		return [metal, cpu, base];
+	}
+	return opts.preferGpu === true ? [cuda, cpu, base] : [cpu, base, cuda];
+}
+
+export interface SelectedLibTarget {
+	readonly target: string;
+	readonly files: ReadonlyArray<Eliza1LibFileEntry>;
+}
+
+/**
+ * Pick the bundle's lib file set for the first host target the manifest
+ * actually carries. Returns null when the bundle has no `lib[]` or hosts no
+ * target the host accepts (⇒ the runtime falls back to other resolution paths,
+ * ultimately cloud).
+ */
+export function selectBundleLibFiles(
+	manifest: { files: Pick<Eliza1Files, "lib"> },
+	targets: ReadonlyArray<string>,
+): SelectedLibTarget | null {
+	const lib = manifest.files.lib;
+	if (!lib || lib.length === 0) return null;
+	for (const target of targets) {
+		const files = lib.filter((e) => e.target === target);
+		if (files.length > 0) return { target, files };
+	}
+	return null;
+}
+
+/**
+ * Flat staged filename under `<bundleRoot>/lib/` for a lib entry. Always a
+ * basename (any directory component in `name`/`path` is stripped) so a manifest
+ * can never write outside the lib dir.
+ */
+export function libStagedName(entry: Eliza1LibFileEntry): string {
+	const raw =
+		entry.name && entry.name.trim().length > 0 ? entry.name.trim() : entry.path;
+	const parts = raw.split(/[\\/]/);
+	return parts[parts.length - 1] || raw;
+}

package/src/services/live-signals.test.ts

@@ -0,0 +1,132 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { inferenceTelemetry } from "./inference-telemetry";
+import {
+	estimateDecodeTokens,
+	type LiveDeviceSignals,
+	liveSignalsDemoteLocal,
+	MIN_DECODE_TPS_BUDGET,
+	readLiveDeviceSignals,
+	recordDecodeThroughput,
+	setLiveDeviceSignalsSource,
+} from "./live-signals";
+
+afterEach(() => {
+	setLiveDeviceSignalsSource(null);
+	inferenceTelemetry.reset();
+});
+
+const signals = (over: Partial<LiveDeviceSignals>): LiveDeviceSignals => ({
+	thermalState: null,
+	decodeTokensPerSecond: null,
+	...over,
+});
+
+describe("liveSignalsDemoteLocal", () => {
+	it("demotes on serious thermal", () => {
+		expect(liveSignalsDemoteLocal(signals({ thermalState: "serious" }))).toBe(
+			true,
+		);
+	});
+
+	it("demotes on critical thermal", () => {
+		expect(liveSignalsDemoteLocal(signals({ thermalState: "critical" }))).toBe(
+			true,
+		);
+	});
+
+	it("does not demote on nominal / fair thermal", () => {
+		expect(liveSignalsDemoteLocal(signals({ thermalState: "nominal" }))).toBe(
+			false,
+		);
+		expect(liveSignalsDemoteLocal(signals({ thermalState: "fair" }))).toBe(
+			false,
+		);
+	});
+
+	it("demotes when decode TPS is below budget", () => {
+		expect(
+			liveSignalsDemoteLocal(
+				signals({ decodeTokensPerSecond: MIN_DECODE_TPS_BUDGET - 1 }),
+			),
+		).toBe(true);
+	});
+
+	it("does not demote at or above the TPS budget", () => {
+		expect(
+			liveSignalsDemoteLocal(
+				signals({ decodeTokensPerSecond: MIN_DECODE_TPS_BUDGET }),
+			),
+		).toBe(false);
+		expect(
+			liveSignalsDemoteLocal(signals({ decodeTokensPerSecond: 100 })),
+		).toBe(false);
+	});
+
+	it("does not demote when both signals are unmeasured (null)", () => {
+		expect(liveSignalsDemoteLocal(signals({}))).toBe(false);
+	});
+});
+
+describe("readLiveDeviceSignals source injection", () => {
+	it("returns whatever the injected source provides", () => {
+		setLiveDeviceSignalsSource(() =>
+			signals({ thermalState: "serious", decodeTokensPerSecond: 3 }),
+		);
+		const out = readLiveDeviceSignals();
+		expect(out.thermalState).toBe("serious");
+		expect(out.decodeTokensPerSecond).toBe(3);
+	});
+
+	it("restores the default source when set to null", () => {
+		setLiveDeviceSignalsSource(() =>
+			signals({ thermalState: "critical", decodeTokensPerSecond: 1 }),
+		);
+		setLiveDeviceSignalsSource(null);
+		// Default source reads the (empty, in test) device bridge + telemetry:
+		// no device connected and no decode samples → both null.
+		const out = readLiveDeviceSignals();
+		expect(out.thermalState).toBeNull();
+		expect(out.decodeTokensPerSecond).toBeNull();
+	});
+});
+
+describe("estimateDecodeTokens", () => {
+	it("approximates ~4 characters per token", () => {
+		expect(estimateDecodeTokens("")).toBe(0);
+		expect(estimateDecodeTokens("abcd")).toBe(1);
+		expect(estimateDecodeTokens("a".repeat(40))).toBe(10);
+	});
+});
+
+describe("recordDecodeThroughput → default source → demotion (end-to-end)", () => {
+	it("a sub-budget generation makes the default source demote local", () => {
+		// 8 tokens in 2 s = 4 tok/s, below the 6 tok/s budget.
+		recordDecodeThroughput({ tokens: 8, elapsedMs: 2000 });
+
+		const out = readLiveDeviceSignals();
+		expect(out.decodeTokensPerSecond).toBeLessThan(MIN_DECODE_TPS_BUDGET);
+		expect(out.decodeTokensPerSecond).toBeCloseTo(4, 5);
+		expect(liveSignalsDemoteLocal(out)).toBe(true);
+	});
+
+	it("a healthy generation does not demote local", () => {
+		// 100 tokens in 1 s = 100 tok/s, comfortably above budget.
+		recordDecodeThroughput({ tokens: 100, elapsedMs: 1000 });
+
+		const out = readLiveDeviceSignals();
+		expect(out.decodeTokensPerSecond).toBeGreaterThanOrEqual(
+			MIN_DECODE_TPS_BUDGET,
+		);
+		expect(liveSignalsDemoteLocal(out)).toBe(false);
+	});
+
+	it("drops noise samples so the signal stays null", () => {
+		recordDecodeThroughput({ tokens: 2, elapsedMs: 1000 }); // too few tokens
+		recordDecodeThroughput({ tokens: 50, elapsedMs: 0 }); // clock didn't advance
+		recordDecodeThroughput({ tokens: 50, elapsedMs: -10 }); // negative span
+
+		const out = readLiveDeviceSignals();
+		expect(out.decodeTokensPerSecond).toBeNull();
+		expect(liveSignalsDemoteLocal(out)).toBe(false);
+	});
+});