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

package/src/services/device-tier.ts

@@ -27,6 +27,14 @@
  * 3–4 GB ceiling; Android foreground-service requirement).
  */
 
+import { isMobilePlatform } from "@elizaos/shared";
+import {
+	type Eliza1Fit,
+	// Aliased to a distinct name (no shared `selectBestEliza1Fit*` prefix with the
+	// local `selectBestEliza1FitForDevice`) — the mobile Bun.build minifier was
+	// observed to mangle the same-prefix pair into a dangling `…Fit2` reference.
+	selectBestEliza1Fit as resolveBestEliza1FitForRam,
+} from "@elizaos/shared/local-inference";
 import type { HardwareProbe } from "./types";
 
 /** The four device tiers used by the runtime + UI. */
@@ -67,7 +75,11 @@ export const DEVICE_TIER_THRESHOLDS = {
 		effectiveModelMemoryGb: 6,
 		freeRamGbAtSession: 3,
 		minTotalRamGb: 16,
-		mobileMinTotalRamGb: 12,
+		// A phone can run eliza-1 2B (≈2.5 GB resident) locally — 6 GB+ total /
+		// ≈3 GB effective is enough — so an 8 GB Pixel is OKAY (local-capable),
+		// not POOR/cloud-only. The desktop floors stay higher.
+		mobileMinTotalRamGb: 6,
+		mobileEffectiveModelMemoryGb: 3,
 	},
 } as const;
 
@@ -87,6 +99,12 @@ export interface DeviceTierAssessment {
 	canRunLocalVoice: boolean;
 	/** Default backend mode for the user. */
 	recommendedMode: RecommendedMode;
+	/**
+	 * The biggest eliza-1 tier (+ 128k-targeted QJL context) that fits this device,
+	 * or `null` when nothing local fits and the modality should route to Cloud.
+	 * This is the single forced-model decision the consumer UI renders read-only.
+	 */
+	recommendedFit: Eliza1Fit | null;
 	/** Numeric snapshot to drive UI badges and first-run copy. */
 	numericContext: {
 		totalRamGb: number;
@@ -114,6 +132,72 @@ export function effectiveModelMemoryGb(probe: HardwareProbe): number {
 	return probe.totalRamGb * 0.5;
 }
 
+/**
+ * Mobile OS background-task model makes large local tiers unsafe regardless of how
+ * much RAM the phone reports, so cap mobile fit at the 4B floor. A strong phone may
+ * run 4B; a typical one lands on 2B; both still flow through `selectBestEliza1Fit`.
+ */
+const MOBILE_FIT_CEILING_GB = 6;
+
+/**
+ * Largest context window we advertise on a phone. A full 128k QJL KV cache does
+ * not fit alongside the weights in a handset's real free RAM (the resident agent +
+ * WebView + OS leave well under `totalRam × 0.5`), so we clamp mobile windows here
+ * even when the coarse RAM math would allow more.
+ */
+const MOBILE_CONTEXT_CEILING = 65536; // 64k
+
+/**
+ * True when this host should be treated as a phone for fit purposes. The on-device
+ * bun agent's hardware probe often reports `platform: "linux"` with no `mobile`
+ * field (it sees the bionic/musl env as linux), so the probe alone under-detects
+ * Android/iOS — fall back to the runtime `ELIZA_PLATFORM` signal so the mobile cap
+ * still applies. Without this, a high-RAM phone would be handed a 9B+ tier.
+ */
+function isMobileHost(probe: HardwareProbe): boolean {
+	return isMobile(probe) || isMobilePlatform();
+}
+
+/**
+ * The canonical "biggest eliza-1 that fits this device" decision: normalize the
+ * hardware probe to usable model memory, then pick the largest tier at a 128k QJL
+ * window (or a downscaled 2B window, or `null` → route to Cloud). This is the one
+ * function callers should use to answer "what local model runs here" — it always
+ * applies TurboQuant weights + the QJL KV cache and targets a 128k window. On
+ * mobile it caps the tier at 4B and the context at 64k (a phone cannot hold a 128k
+ * cache).
+ */
+export function selectBestEliza1FitForDevice(
+	probe: HardwareProbe,
+): Eliza1Fit | null {
+	const mobile = isMobileHost(probe);
+	let memGb = effectiveModelMemoryGb(probe);
+	if (mobile) memGb = Math.min(memGb, MOBILE_FIT_CEILING_GB);
+	let fit: Eliza1Fit | null;
+	try {
+		fit = resolveBestEliza1FitForRam(memGb);
+	} catch (err) {
+		// `recommendedFit` is an advisory hint, never a routing gate — but
+		// `classifyDeviceTier` (which embeds it) IS called on the routing hot path.
+		// A mobile-bundle minifier artifact has been observed to leave a dangling
+		// reference at this cross-module call, so guard it: degrade to no
+		// recommendation rather than letting an undefined-symbol error crash the
+		// whole device-tier assessment (and with it the AUTO router) on-device.
+		console.warn(
+			`[device-tier] recommendedFit unavailable: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		return null;
+	}
+	if (fit && mobile && fit.contextLength > MOBILE_CONTEXT_CEILING) {
+		return {
+			...fit,
+			contextLength: MOBILE_CONTEXT_CEILING,
+			contextDownscaled: true,
+		};
+	}
+	return fit;
+}
+
 /**
  * Treat the host as a mobile device. Mobile clamps to OKAY at best
  * regardless of RAM because the OS background-task model breaks
@@ -127,19 +211,22 @@ function isMobile(probe: HardwareProbe): boolean {
 
 /**
  * Compute the CPU SIMD baseline. The hardware probe has no direct AVX2 field
- * today for x86_64, so Linux/Win x86_64 ≥ 4 cores qualifies. ARM must expose
- * NEON/Advanced SIMD in the probe; when ARM feature data is absent, do not
- * claim the CPU route.
+ * today for x86_64, so Linux/Win x86_64 ≥ 4 cores qualifies.
+ *
+ * **arm64 / ARMv8-A architecturally MANDATES NEON (Advanced SIMD)** — every arm64
+ * phone has it — so we trust the architecture rather than the probe's
+ * `cpuFeatures.neon` (the on-device os-fallback probe omits it, which used to
+ * misclassify every Pixel as POOR → cloud-only even though it runs local 2B fine).
+ * We do not support 32-bit ARM (ARMv7), so it (and any other non-x64 arch) is
+ * treated as unsupported.
  *
  * This is a coarse heuristic; the precise check belongs in the FFI layer
  * (it can `cpuid` the actual flags). The tier classifier just refuses POOR
  * when the probe is clearly under-equipped.
  */
 function hasAvx2Baseline(probe: HardwareProbe): boolean {
-	if (probe.arch === "arm64" || probe.arch === "arm") {
-		return probe.cpuFeatures?.neon === true && probe.cpuCores >= 4;
-	}
-	if (probe.arch !== "x64") return false;
+	if (probe.arch === "arm64") return probe.cpuCores >= 4;
+	if (probe.arch !== "x64") return false; // 32-bit ARM + others: unsupported
 	return probe.cpuCores >= 4;
 }
 
@@ -167,7 +254,9 @@ function isAppleSilicon8gb(probe: HardwareProbe): boolean {
 export function classifyDeviceTier(probe: HardwareProbe): DeviceTierAssessment {
 	const reasons: string[] = [];
 	const effective = effectiveModelMemoryGb(probe);
-	const mobile = isMobile(probe);
+	// isMobileHost (not isMobile) so a phone whose bun-agent probe reports
+	// platform:"linux" with no mobile field still gets mobile thresholds + clamp.
+	const mobile = isMobileHost(probe);
 	const avx2 = hasAvx2Baseline(probe);
 	const vramGb = probe.gpu?.totalVramGb ?? null;
 	const cpuCores = probe.cpuCores;
@@ -230,6 +319,7 @@ export function classifyDeviceTier(probe: HardwareProbe): DeviceTierAssessment {
 		canRunLocalLm,
 		canRunLocalVoice,
 		recommendedMode,
+		recommendedFit: selectBestEliza1FitForDevice(probe),
 		numericContext: {
 			totalRamGb,
 			freeRamGb,
@@ -319,8 +409,10 @@ function classifyRawTier(args: ClassifyArgs): DeviceTier {
 		return "GOOD";
 	}
 
-	// OKAY gate.
-	const meetsOkayEffective = effective >= okay.effectiveModelMemoryGb;
+	// OKAY gate. Mobile uses lower effective/total floors — a phone runs 2B fine.
+	const meetsOkayEffective =
+		effective >=
+		(mobile ? okay.mobileEffectiveModelMemoryGb : okay.effectiveModelMemoryGb);
 	const meetsOkayFree = freeRamGb >= okay.freeRamGbAtSession;
 	const meetsOkayTotal =
 		totalRamGb >= (mobile ? okay.mobileMinTotalRamGb : okay.minTotalRamGb);

package/src/services/downloader.test.ts

@@ -7,8 +7,29 @@ import { readAssignments } from "./assignments";
 import { findCatalogModel } from "./catalog";
 import { Downloader } from "./downloader";
 import type { Eliza1DeviceCaps } from "./manifest";
-import { listInstalledModels } from "./registry";
-import type { DownloadJob } from "./types";
+import { registryPath } from "./paths";
+import type {
+	CatalogModel,
+	DownloadJob,
+	HardwareProbe,
+	InstalledModel,
+} from "./types";
+
+/** Minimal HardwareProbe with a controllable free-disk value for preflight tests. */
+function fakeProbe(freeDiskGb: number): HardwareProbe {
+	return {
+		totalRamGb: 32,
+		freeRamGb: 16,
+		freeDiskGb,
+		gpu: null,
+		cpuCores: 8,
+		platform: "darwin",
+		arch: "arm64",
+		appleSilicon: true,
+		recommendedBucket: "mid",
+		source: "os-fallback",
+	};
+}
 
 function eliza1Manifest(overrides: {
 	ramBudgetMin?: number;
@@ -22,7 +43,6 @@ function eliza1Manifest(overrides: {
 	const textPath = "text/eliza-1-2b-128k.gguf";
 	const voicePath = "tts/voice.gguf";
 	const asrPath = "asr/asr.gguf";
-	const drafterPath = "mtp/drafter-2b.gguf";
 	const cachePath = "cache/voice-preset-default.bin";
 	const vadPath = "vad/eliza-1-vad.onnx";
 	const visionPath = "vision/mmproj-2b.gguf";
@@ -43,10 +63,14 @@ function eliza1Manifest(overrides: {
 			voice: { base: "eliza-1-voice", license: "test" },
 			asr: { base: "eliza-1-asr", license: "test" },
 			vad: { base: "eliza-1-vad", license: "test" },
-			drafter: { base: "eliza-1-drafter", license: "test" },
 			vision: { base: "eliza-1-vision", license: "test" },
 		},
 		defaultEligible: true,
+		// Downloader-mechanics fixture: MTP mode is incidental here, so this
+		// bundle is the legacy embedded-draft-head shape (no separate drafter
+		// GGUF to serve). The Gemma-4 separate-drafter contract is exercised in
+		// manifest.test.ts.
+		mtp: "embedded-draft-head",
 		files: {
 			text: [
 				{
@@ -58,12 +82,7 @@ function eliza1Manifest(overrides: {
 			voice: [{ path: voicePath, sha256: overrides.shaFor("voice") }],
 			asr: [{ path: asrPath, sha256: overrides.shaFor("asr") }],
 			vision: [{ path: visionPath, sha256: overrides.shaFor("vision") }],
-			mtp: [
-				{
-					path: drafterPath,
-					sha256: overrides.shaFor("drafter"),
-				},
-			],
+			mtp: [],
 			cache: [
 				{
 					path: cachePath,
@@ -167,6 +186,14 @@ function sha256(content: string): string {
 	return createHash("sha256").update(content).digest("hex");
 }
 
+function readOwnedRegistryModels(): InstalledModel[] {
+	if (!fs.existsSync(registryPath())) return [];
+	const parsed = JSON.parse(fs.readFileSync(registryPath(), "utf8")) as {
+		models?: InstalledModel[];
+	};
+	return parsed.models ?? [];
+}
+
 function installFetchFixture(files: Map<string, string>): void {
 	globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
 		const href =
@@ -243,7 +270,7 @@ describe("local inference downloader status", () => {
 		expect(job?.error).toBe("network reset");
 	});
 
-	it("installs Eliza-1 manifest bundles with the bundled MTP drafter", async () => {
+	it("installs Eliza-1 manifest bundles with embedded-draft-head MTP metadata", async () => {
 		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-download-test-"));
 		process.env.ELIZA_STATE_DIR = root;
 		const model = findCatalogModel("eliza-1-2b");
@@ -256,14 +283,12 @@ describe("local inference downloader status", () => {
 		const voice = "GGUF voice model";
 		const asr = "GGUF ASR model";
 		const vad = "VAD model";
-		const drafter = "GGUF drafter model";
 		const cache = "voice preset";
 		const vision = "vision projector";
 		const textPath = "text/eliza-1-2b-128k.gguf";
 		const voicePath = "tts/voice.gguf";
 		const asrPath = "asr/asr.gguf";
 		const vadPath = "vad/eliza-1-vad.onnx";
-		const drafterPath = "mtp/drafter-2b.gguf";
 		const cachePath = "cache/voice-preset-default.bin";
 		const visionPath = "vision/mmproj-2b.gguf";
 		const manifest = JSON.stringify({
@@ -276,10 +301,10 @@ describe("local inference downloader status", () => {
 				voice: { base: "eliza-1-voice", license: "test" },
 				asr: { base: "eliza-1-asr", license: "test" },
 				vad: { base: "eliza-1-vad", license: "test" },
-				drafter: { base: "eliza-1-drafter", license: "test" },
 				vision: { base: "eliza-1-vision", license: "test" },
 			},
 			defaultEligible: true,
+			mtp: "embedded-draft-head",
 			files: {
 				text: [
 					{
@@ -291,12 +316,7 @@ describe("local inference downloader status", () => {
 				voice: [{ path: voicePath, sha256: sha256(voice) }],
 				asr: [{ path: asrPath, sha256: sha256(asr) }],
 				vision: [{ path: visionPath, sha256: sha256(vision) }],
-				mtp: [
-					{
-						path: drafterPath,
-						sha256: sha256(drafter),
-					},
-				],
+				mtp: [],
 				cache: [
 					{
 						path: cachePath,
@@ -354,7 +374,6 @@ describe("local inference downloader status", () => {
 				[bundleRemotePath(model, voicePath), voice],
 				[bundleRemotePath(model, asrPath), asr],
 				[bundleRemotePath(model, vadPath), vad],
-				[bundleRemotePath(model, drafterPath), drafter],
 				[bundleRemotePath(model, cachePath), cache],
 				[bundleRemotePath(model, visionPath), vision],
 			]),
@@ -366,7 +385,7 @@ describe("local inference downloader status", () => {
 		const completed = waitForTerminal(downloader, model.id);
 		await downloader.start(model);
 		const job = await completed;
-		const installed = await listInstalledModels();
+		const installed = readOwnedRegistryModels();
 		const main = installed.find((entry) => entry.id === model.id);
 		expect(main).toBeDefined();
 		const bundleRoot = main?.bundleRoot;
@@ -389,7 +408,6 @@ describe("local inference downloader status", () => {
 		expect(fs.existsSync(path.join(bundleRoot, asrPath))).toBe(true);
 		expect(fs.existsSync(path.join(bundleRoot, vadPath))).toBe(true);
 		expect(fs.existsSync(path.join(bundleRoot, visionPath))).toBe(true);
-		expect(fs.existsSync(path.join(bundleRoot, drafterPath))).toBe(true);
 		expect(installed.some((entry) => entry.id.endsWith("-drafter"))).toBe(
 			false,
 		);
@@ -406,7 +424,6 @@ describe("local inference downloader status", () => {
 		const fetchSpy = installManifestOnlyFetch("tampered manifest");
 		const pinnedModel = {
 			...model,
-			id: "eliza-1-2b-manifest-hash-test",
 			companionModelIds: [],
 			bundleManifestSha256: sha256("expected manifest"),
 		};
@@ -415,7 +432,7 @@ describe("local inference downloader status", () => {
 		});
 		const failed = new Promise<DownloadJob>((resolve) => {
 			const unsub = downloader.subscribe((event) => {
-				if (event.job.modelId === pinnedModel.id && event.type === "failed") {
+				if (event.job.modelId === model.id && event.type === "failed") {
 					unsub();
 					resolve(event.job);
 				}
@@ -431,12 +448,12 @@ describe("local inference downloader status", () => {
 		expect(fetchSpy).toHaveBeenCalledTimes(1);
 	});
 
-	it("restarts single-file partial downloads when a server ignores Range", async () => {
+	it("rejects custom CatalogModel specs before starting a download", async () => {
 		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-download-test-"));
 		process.env.ELIZA_STATE_DIR = root;
 		const baseModel = findCatalogModel("eliza-1-2b");
 		if (!baseModel) throw new Error("missing test catalog model");
-		const model = {
+		const customSpec: CatalogModel = {
 			...baseModel,
 			id: "hf:test/partial::model.gguf",
 			displayName: "Partial Test Model",
@@ -447,28 +464,13 @@ describe("local inference downloader status", () => {
 			runtimeRole: undefined,
 		};
 
-		const body = "complete model";
-		installFetchFixture(
-			new Map([[bundleRemotePath(model, model.ggufFile), body]]),
-		);
-
-		const downloadsDir = path.join(root, "local-inference", "downloads");
-		fs.mkdirSync(downloadsDir, { recursive: true });
-		fs.writeFileSync(
-			path.join(downloadsDir, "hf_test_partial__model.gguf.part"),
-			"stale partial",
-		);
-
 		const downloader = new Downloader();
-		const completed = waitForTerminal(downloader, model.id);
-		await downloader.start(model);
-		await completed;
+		await expect(downloader.start(customSpec)).rejects.toThrow(
+			/Custom model downloads are disabled/i,
+		);
 
-		const installed = await listInstalledModels();
-		const entry = installed.find((m) => m.id === model.id);
-		expect(entry).toBeDefined();
-		if (!entry) throw new Error("missing installed model");
-		expect(fs.readFileSync(entry.path, "utf8")).toBe(body);
+		expect(fs.existsSync(registryPath())).toBe(false);
+		expect(downloader.snapshot()).toEqual([]);
 	});
 
 	it("aborts before any weight byte when no verified backend overlaps the device", async () => {
@@ -492,7 +494,6 @@ describe("local inference downloader status", () => {
 
 		const textPath = model.ggufFile;
 		const voicePath = "tts/voice.gguf";
-		const drafterPath = "mtp/drafter-27b-256k.gguf";
 		const cachePath = "cache/voice-preset-default.bin";
 		const visionPath = "vision/mmproj-27b-256k.gguf";
 		const manifest = JSON.stringify({
@@ -503,7 +504,6 @@ describe("local inference downloader status", () => {
 			lineage: {
 				text: { base: "eliza-1-text", license: "test" },
 				voice: { base: "eliza-1-voice", license: "test" },
-				drafter: { base: "eliza-1-drafter", license: "test" },
 				vision: { base: "eliza-1-vision", license: "test" },
 			},
 			defaultEligible: false,
@@ -518,7 +518,7 @@ describe("local inference downloader status", () => {
 				voice: [{ path: voicePath, sha256: sha256("v") }],
 				asr: [],
 				vision: [{ path: visionPath, sha256: sha256("vision") }],
-				mtp: [{ path: drafterPath, sha256: sha256("d") }],
+				mtp: [],
 				cache: [{ path: cachePath, sha256: sha256("c") }],
 			},
 			kernels: {
@@ -565,7 +565,7 @@ describe("local inference downloader status", () => {
 			([u]) => remotePathOf(u) !== bundleRemotePath(model, manifestFile),
 		);
 		expect(weightFetches).toHaveLength(0);
-		expect((await listInstalledModels()).some((m) => m.id === model.id)).toBe(
+		expect(readOwnedRegistryModels().some((m) => m.id === model.id)).toBe(
 			false,
 		);
 	});
@@ -597,7 +597,7 @@ describe("local inference downloader status", () => {
 		await downloader.start(model.id);
 		const job = await failed;
 		expect(job.error).toMatch(/needs at least 999999 MB RAM/);
-		expect((await listInstalledModels()).some((m) => m.id === model.id)).toBe(
+		expect(readOwnedRegistryModels().some((m) => m.id === model.id)).toBe(
 			false,
 		);
 	});
@@ -613,7 +613,6 @@ describe("local inference downloader status", () => {
 			voice: "GGUF voice",
 			asr: "GGUF asr",
 			vad: "VAD onnx",
-			drafter: "GGUF drafter",
 			cache: "voice preset",
 			vision: "vision projector",
 		} as const;
@@ -627,7 +626,6 @@ describe("local inference downloader status", () => {
 				[eliza1BundleRemotePath("tts/voice.gguf"), bytes.voice],
 				[eliza1BundleRemotePath("asr/asr.gguf"), bytes.asr],
 				[eliza1BundleRemotePath("vad/eliza-1-vad.onnx"), bytes.vad],
-				[eliza1BundleRemotePath("mtp/drafter-2b.gguf"), bytes.drafter],
 				[eliza1BundleRemotePath("cache/voice-preset-default.bin"), bytes.cache],
 				[eliza1BundleRemotePath("vision/mmproj-2b.gguf"), bytes.vision],
 			]),
@@ -662,7 +660,7 @@ describe("local inference downloader status", () => {
 				.normalize(verifyCalls[0]?.textGgufPath ?? "")
 				.endsWith(path.normalize("text/eliza-1-2b-128k.gguf")),
 		).toBe(true);
-		const installed = await listInstalledModels();
+		const installed = readOwnedRegistryModels();
 		const main = installed.find((m) => m.id === model.id);
 		expect(main?.bundleVerifiedAt).toBeTruthy();
 		expect(verifyCalls[0]?.bundleRoot).toBe(main?.bundleRoot);
@@ -680,7 +678,6 @@ describe("local inference downloader status", () => {
 			voice: "GGUF voice",
 			asr: "GGUF asr",
 			vad: "VAD onnx",
-			drafter: "GGUF drafter",
 			cache: "voice preset",
 			vision: "vision projector",
 		} as const;
@@ -694,7 +691,6 @@ describe("local inference downloader status", () => {
 				[eliza1BundleRemotePath("tts/voice.gguf"), bytes.voice],
 				[eliza1BundleRemotePath("asr/asr.gguf"), bytes.asr],
 				[eliza1BundleRemotePath("vad/eliza-1-vad.onnx"), bytes.vad],
-				[eliza1BundleRemotePath("mtp/drafter-2b.gguf"), bytes.drafter],
 				[eliza1BundleRemotePath("cache/voice-preset-default.bin"), bytes.cache],
 				[eliza1BundleRemotePath("vision/mmproj-2b.gguf"), bytes.vision],
 			]),
@@ -717,7 +713,7 @@ describe("local inference downloader status", () => {
 		await downloader.start(model.id);
 		const job = await failed;
 		expect(job.error).toMatch(/barge-in cancel test failed/);
-		expect((await listInstalledModels()).some((m) => m.id === model.id)).toBe(
+		expect(readOwnedRegistryModels().some((m) => m.id === model.id)).toBe(
 			false,
 		);
 	});
@@ -744,4 +740,149 @@ describe("local inference downloader status", () => {
 		).toHaveLength(1);
 		downloader.cancel(model.id);
 	});
+
+	it("rejects a non-GGUF (HTML) body on the single-file path", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-download-test-"));
+		process.env.ELIZA_STATE_DIR = root;
+		const base = findCatalogModel("eliza-1-2b");
+		if (!base) throw new Error("missing test catalog model");
+		// Decorate a default-eligible id as a single-file (non-bundle) download so
+		// it routes through runJob's single-file path.
+		const singleFileSpec: CatalogModel = {
+			...base,
+			hfRepo: "test/single-file",
+			ggufFile: "model.gguf",
+			sizeGb: 0.000001,
+			bundleManifestFile: undefined,
+			bundleManifestSha256: undefined,
+			companionModelIds: [],
+			runtimeRole: undefined,
+		};
+
+		// A gated repo can answer HTTP 200 with an HTML login page.
+		globalThis.fetch = vi.fn(
+			async () =>
+				new Response("<html><body>Sign in to HuggingFace</body></html>", {
+					status: 200,
+					headers: { "content-type": "text/html" },
+				}),
+		) as unknown as typeof fetch;
+
+		const downloader = new Downloader({
+			probeDeviceCaps: async () => cpuOnlyCaps,
+			probeHardware: async () => fakeProbe(100),
+		});
+		const failed = new Promise<DownloadJob>((resolve) => {
+			const unsub = downloader.subscribe((event) => {
+				if (event.job.modelId === base.id && event.type === "failed") {
+					unsub();
+					resolve(event.job);
+				}
+			});
+		});
+
+		await downloader.start(singleFileSpec);
+		const job = await failed;
+
+		expect(job.error).toContain("not a valid GGUF");
+		// The HTML body must never be registered or left on disk as a model.
+		const finalPath = path.join(
+			root,
+			"local-inference",
+			"models",
+			"eliza-1-2b.gguf",
+		);
+		// (registry path lives elsewhere; the rejected file is removed regardless)
+		expect(fs.existsSync(finalPath)).toBe(false);
+	});
+
+	it("forwards the Eliza Cloud bearer on a single-file download when cloud-linked", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-download-test-"));
+		process.env.ELIZA_STATE_DIR = root;
+		// The product never holds a local HF token. When cloud-linked, all HF
+		// resolve traffic is routed through the cloud HF proxy and authenticated
+		// with the Eliza Cloud API key (the proxy attaches the cloud-side HF_TOKEN).
+		const savedKey = process.env.ELIZAOS_CLOUD_API_KEY;
+		process.env.ELIZAOS_CLOUD_API_KEY = "secret-token";
+
+		const base = findCatalogModel("eliza-1-2b");
+		if (!base) throw new Error("missing test catalog model");
+		const singleFileSpec: CatalogModel = {
+			...base,
+			hfRepo: "test/single-file",
+			ggufFile: "model.gguf",
+			sizeGb: 0.000001,
+			bundleManifestFile: undefined,
+			bundleManifestSha256: undefined,
+			companionModelIds: [],
+			runtimeRole: undefined,
+		};
+
+		const ggufBody = Buffer.concat([Buffer.from("GGUF"), Buffer.alloc(60, 0)]);
+		let capturedAuth: string | undefined;
+		globalThis.fetch = vi.fn(
+			async (_url: string | URL | Request, init?: RequestInit) => {
+				const headers = (init?.headers ?? {}) as Record<string, string>;
+				capturedAuth = headers.authorization;
+				return new Response(ggufBody, {
+					status: 200,
+					headers: { "content-length": String(ggufBody.length) },
+				});
+			},
+		) as unknown as typeof fetch;
+
+		const downloader = new Downloader({
+			probeDeviceCaps: async () => cpuOnlyCaps,
+			probeHardware: async () => fakeProbe(100),
+		});
+		const completed = new Promise<DownloadJob>((resolve) => {
+			const unsub = downloader.subscribe((event) => {
+				if (event.job.modelId === base.id && event.type === "completed") {
+					unsub();
+					resolve(event.job);
+				}
+			});
+		});
+
+		try {
+			await downloader.start(singleFileSpec);
+			await completed;
+			expect(capturedAuth).toBe("Bearer secret-token");
+		} finally {
+			if (savedKey === undefined) delete process.env.ELIZAOS_CLOUD_API_KEY;
+			else process.env.ELIZAOS_CLOUD_API_KEY = savedKey;
+		}
+	});
+
+	it("blocks a download that does not fit on the models volume", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-download-test-"));
+		process.env.ELIZA_STATE_DIR = root;
+		const model = findCatalogModel("eliza-1-2b");
+		if (!model) throw new Error("missing test catalog model");
+
+		// Fetch must never be called: the preflight fails before any byte.
+		const fetchSpy = vi.fn(async () => {
+			throw new Error("network must not be touched when disk is full");
+		});
+		globalThis.fetch = fetchSpy as unknown as typeof fetch;
+
+		const downloader = new Downloader({
+			probeDeviceCaps: async () => cpuOnlyCaps,
+			probeHardware: async () => fakeProbe(0.05),
+		});
+		const failed = new Promise<DownloadJob>((resolve) => {
+			const unsub = downloader.subscribe((event) => {
+				if (event.job.modelId === model.id && event.type === "failed") {
+					unsub();
+					resolve(event.job);
+				}
+			});
+		});
+
+		await downloader.start(model.id);
+		const job = await failed;
+
+		expect(job.error).toContain("Not enough disk space");
+		expect(fetchSpy).not.toHaveBeenCalled();
+	});
 });