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

package/src/services/downloader.ts

@@ -21,14 +21,21 @@ import fsp from "node:fs/promises";
 import path from "node:path";
 import { Readable, type Writable } from "node:stream";
 import { pipeline } from "node:stream/promises";
+import { logger } from "@elizaos/core";
 import { ensureDefaultAssignment } from "./assignments";
 import {
 	buildHuggingFaceResolveUrl,
 	buildHuggingFaceResolveUrlForPath,
 	findCatalogModel,
 	isDefaultEligibleId,
+	resolveHfDownloadBase,
 } from "./catalog";
 import { deviceCapsFromProbe, probeHardware } from "./hardware";
+import {
+	libStagedName,
+	resolveHostLibTargets,
+	selectBundleLibFiles,
+} from "./lib-target";
 import {
 	type Eliza1DeviceCaps,
 	type Eliza1FileEntry,
@@ -43,12 +50,14 @@ import {
 	localInferenceRoot,
 } from "./paths";
 import { upsertElizaModel } from "./registry";
-import type {
-	CatalogModel,
-	DownloadEvent,
-	DownloadJob,
-	DownloadState,
-	InstalledModel,
+import {
+	type CatalogModel,
+	classifyCatalogModelRuntimeClass,
+	type DownloadEvent,
+	type DownloadJob,
+	type DownloadState,
+	type HardwareProbe,
+	type InstalledModel,
 } from "./types";
 import { hashFile } from "./verify";
 
@@ -97,6 +106,8 @@ export interface DownloaderOptions {
 	probeDeviceCaps?: () => Promise<Eliza1DeviceCaps>;
 	/** Verify-on-device smoke run; see {@link VerifyBundleOnDevice}. */
 	verifyOnDevice?: VerifyBundleOnDevice;
+	/** Override the hardware probe used by the disk-space preflight (tests). */
+	probeHardware?: () => Promise<HardwareProbe>;
 }
 
 async function defaultProbeDeviceCaps(): Promise<Eliza1DeviceCaps> {
@@ -147,6 +158,8 @@ interface DownloadedFile {
 const PROGRESS_THROTTLE_MS = 250;
 const TERMINAL_DOWNLOADS_FILENAME = "download-status.json";
 const TERMINAL_DOWNLOAD_LIMIT = 32;
+/** Headroom kept free above the download size for the disk-space preflight. */
+const DISK_HEADROOM_GB = 0.5;
 
 interface TerminalDownloadsFile {
 	version: 1;
@@ -181,19 +194,23 @@ function finalFilename(model: CatalogModel): string {
 }
 
 /**
- * HuggingFace bearer token for gated/metered repos, read from the same env
- * aliases the embedding manager uses (HF_TOKEN / HUGGINGFACE_TOKEN /
- * HF_HUB_TOKEN). Returns `{}` when unset so public repos are unaffected. The
- * resolve endpoints for gated bundles (e.g. the Eliza-1 mono-repo) 401 without
- * it, so weight + bundle downloads MUST forward it.
+ * GGUF files begin with the ASCII magic `GGUF`. A non-GGUF body (e.g. an HTML
+ * auth/redirect page returned with HTTP 200 by a gated repo) must never be
+ * registered as an installed model.
  */
-function huggingFaceAuthHeader(): Record<string, string> {
-	const token =
-		process.env.HF_TOKEN?.trim() ||
-		process.env.HUGGINGFACE_TOKEN?.trim() ||
-		process.env.HF_HUB_TOKEN?.trim() ||
-		"";
-	return token ? { authorization: `Bearer ${token}` } : {};
+async function hasGgufMagic(filePath: string): Promise<boolean> {
+	try {
+		const handle = await fsp.open(filePath, "r");
+		try {
+			const buffer = Buffer.alloc(4);
+			await handle.read(buffer, 0, 4, 0);
+			return buffer.toString("ascii") === "GGUF";
+		} finally {
+			await handle.close();
+		}
+	} catch {
+		return false;
+	}
 }
 
 function bundleDirname(modelId: string): string {
@@ -302,10 +319,12 @@ export class Downloader {
 	private readonly lastEmit = new Map<string, number>();
 	private readonly probeDeviceCaps: () => Promise<Eliza1DeviceCaps>;
 	private readonly verifyOnDevice?: VerifyBundleOnDevice;
+	private readonly probeHardware: () => Promise<HardwareProbe>;
 
 	constructor(options: DownloaderOptions = {}) {
 		this.probeDeviceCaps = options.probeDeviceCaps ?? defaultProbeDeviceCaps;
 		this.verifyOnDevice = options.verifyOnDevice;
+		this.probeHardware = options.probeHardware ?? probeHardware;
 		this.loadTerminalDownloads();
 	}
 
@@ -335,9 +354,10 @@ export class Downloader {
 	}
 
 	/**
-	 * Start a download for a model. Accepts either a curated catalog id, or
-	 * a full `CatalogModel` spec for ad-hoc HF-search results. Idempotent —
-	 * returns the existing job if one is already running for the same id.
+	 * Start a download for a curated Eliza-1 catalog entry. Object specs are
+	 * accepted only for internal tests that decorate a known Eliza-1 id; ad-hoc
+	 * Hugging Face / ModelScope specs are rejected before any reservation or
+	 * network I/O.
 	 */
 	async start(modelIdOrSpec: string | CatalogModel): Promise<DownloadJob> {
 		const catalogEntry =
@@ -349,6 +369,12 @@ export class Downloader {
 				`Unknown model id: ${typeof modelIdOrSpec === "string" ? modelIdOrSpec : "(no id)"}`,
 			);
 		}
+		const curated = findCatalogModel(catalogEntry.id);
+		if (!curated || !isDefaultEligibleId(curated.id)) {
+			throw new Error(
+				"Custom model downloads are disabled; choose an Eliza-1 tier from the curated catalog.",
+			);
+		}
 		const modelId = catalogEntry.id;
 		this.clearTerminalDownload(modelId);
 
@@ -503,12 +529,41 @@ export class Downloader {
 		this.emit({ type: "progress", job: { ...record.job } });
 	}
 
+	/**
+	 * Disk-space preflight. The remaining download must fit on the models
+	 * volume with a small headroom margin, or we fail the job up front with an
+	 * actionable message instead of letting it stream gigabytes and die with
+	 * ENOSPC near the end. Best-effort: when free disk can't be probed we let
+	 * the download proceed (the post-hoc ENOSPC handling still catches it).
+	 */
+	private async assertDiskSpaceForJob(record: ActiveJob): Promise<void> {
+		const remainingBytes = Math.max(0, record.job.total - record.job.received);
+		if (remainingBytes <= 0) return;
+		let freeDiskGb: number | undefined;
+		try {
+			const probe = await this.probeHardware();
+			freeDiskGb = probe.freeDiskGb ?? probe.mobile?.freeStorageGb ?? undefined;
+		} catch {
+			return; // probe failure must never block a download
+		}
+		if (freeDiskGb === undefined) return;
+		const requiredGb = remainingBytes / 1024 ** 3 + DISK_HEADROOM_GB;
+		if (freeDiskGb < requiredGb) {
+			throw new Error(
+				`Not enough disk space: this download needs ~${requiredGb.toFixed(1)} GB ` +
+					`but only ${freeDiskGb.toFixed(1)} GB is free on the models volume. ` +
+					"Free up space and retry.",
+			);
+		}
+	}
+
 	private async runJob(
 		catalogEntry: CatalogModel,
 		record: ActiveJob,
 	): Promise<void> {
 		try {
 			this.updateState(record, "downloading");
+			await this.assertDiskSpaceForJob(record);
 			if (catalogEntry.bundleManifestFile) {
 				await this.runBundleJob(catalogEntry, record);
 				return;
@@ -521,7 +576,7 @@ export class Downloader {
 
 			const headers: Record<string, string> = {
 				"user-agent": "Eliza-LocalInference/1.0",
-				...huggingFaceAuthHeader(),
+				...resolveHfDownloadBase().authHeader,
 			};
 			if (startByte > 0) {
 				headers.range = `bytes=${startByte}-`;
@@ -584,6 +639,22 @@ export class Downloader {
 
 			await fsp.rename(record.stagingPath, record.finalPath);
 
+			// Integrity gate: a gated/private repo can answer HTTP 200 with an
+			// HTML login/error body, which would otherwise be renamed `<id>.gguf`
+			// and registered as an installed model. Reject anything that is not a
+			// real GGUF before it enters the registry, and point the user at the
+			// likely cause (gated bundles resolve through the Eliza Cloud HF
+			// proxy, so the device must be linked to Eliza Cloud).
+			if (!(await hasGgufMagic(record.finalPath))) {
+				await fsp.rm(record.finalPath, { force: true }).catch(() => undefined);
+				throw new Error(
+					`Downloaded file for ${catalogEntry.hfRepo ?? catalogEntry.id} is not a valid GGUF ` +
+						"(it looks like an auth/redirect page, not a model). If the bundle is gated, " +
+						"link this device to Eliza Cloud and retry — gated downloads route through " +
+						"the cloud HuggingFace proxy.",
+				);
+			}
+
 			const finalStat = await fsp.stat(record.finalPath);
 			// Compute SHA256 on commit so we have an integrity baseline. The
 			// chunk hasher we maintain during streaming gives the same result
@@ -604,6 +675,7 @@ export class Downloader {
 				source: "eliza-download",
 				sha256,
 				lastVerifiedAt: new Date().toISOString(),
+				runtimeClass: classifyCatalogModelRuntimeClass(catalogEntry),
 				...(catalogEntry.runtimeRole
 					? { runtimeRole: catalogEntry.runtimeRole }
 					: {}),
@@ -611,8 +683,7 @@ export class Downloader {
 			await upsertElizaModel(installed);
 
 			// First-light convenience: only default-eligible Eliza-1 downloads
-			// can fill empty slots. Ad-hoc Hugging Face downloads remain
-			// explicit opt-in even though Eliza owns the downloaded file.
+			// can fill empty slots.
 			if (isDefaultEligibleId(installed.id)) {
 				await ensureDefaultAssignment(installed.id);
 			}
@@ -679,7 +750,8 @@ export class Downloader {
 		// §7: schema version, RAM budget, and kernel-backend availability are
 		// checked against this device BEFORE any weight byte is fetched. An
 		// incompatible bundle aborts here — there is no "download anyway" path.
-		assertBundleInstallable(manifest, await this.probeDeviceCaps());
+		const deviceCaps = await this.probeDeviceCaps();
+		assertBundleInstallable(manifest, deviceCaps);
 
 		let completedBytes = manifestDownloaded.sizeBytes;
 		const downloaded = new Map<string, DownloadedFile>();
@@ -704,6 +776,47 @@ export class Downloader {
 			this.throttleEmit(record);
 		}
 
+		// Fused-lib bundle delivery (#9105): fetch the host-matching native-lib
+		// SET into `<bundleRoot>/lib/`, which the desktop FFI runtime resolves
+		// with no env wiring (`resolveFusedLibraryPath` path #2). Only entries
+		// whose `target` matches the host are fetched; no `lib[]` / no host match
+		// ⇒ skipped (the runtime falls back to a host-staged lib dir, else cloud).
+		// Mobile resolves to no targets — phones ship the lib natively.
+		// Prefer the GPU lib target when this device actually has a CUDA backend
+		// (NVIDIA), so a CUDA-capable host pulls the accelerated set when the
+		// bundle hosts one; everything else takes the CPU baseline. macOS arm64
+		// already resolves to the metal set (which carries the CPU fallback).
+		const preferGpu = deviceCaps.availableBackends.includes("cuda");
+		const selectedLib = selectBundleLibFiles(
+			manifest,
+			resolveHostLibTargets({ preferGpu }),
+		);
+		if (selectedLib) {
+			for (const libEntry of selectedLib.files) {
+				const relPath = `lib/${libStagedName(libEntry)}`;
+				const result = await this.downloadRemotePath(
+					catalogEntry,
+					libEntry.path,
+					path.join(
+						downloadsStagingDir(),
+						bundleStagingFilename(catalogEntry.id, relPath),
+					),
+					bundleTargetPath(bundleRoot, relPath),
+					record,
+					completedBytes,
+					libEntry.sha256,
+				);
+				completedBytes += result.sizeBytes;
+				record.job.received = completedBytes;
+				record.job.total = Math.max(record.job.total, completedBytes);
+				this.throttleEmit(record);
+			}
+			logger.info(
+				`[local-inference] staged fused lib set for ${catalogEntry.id} ` +
+					`(target=${selectedLib.target}, ${selectedLib.files.length} file(s)) → ${bundleRoot}/lib`,
+			);
+		}
+
 		const textEntry = manifest.files.text.find(
 			(entry) => entry.path === catalogEntry.ggufFile,
 		);
@@ -756,6 +869,7 @@ export class Downloader {
 			source: "eliza-download",
 			sha256: textFile.sha256,
 			lastVerifiedAt: now,
+			runtimeClass: classifyCatalogModelRuntimeClass(catalogEntry),
 			...bundleMeta,
 		};
 		await upsertElizaModel(installed);
@@ -812,16 +926,16 @@ export class Downloader {
 		let startByte = expectedSha256 ? await partialSize(stagingPath) : 0;
 		record.job.received = baseBytes + startByte;
 
+		const url = buildHuggingFaceResolveUrlForPath(catalogEntry, remotePath);
 		const headers: Record<string, string> = {
 			"user-agent": "Eliza-LocalInference/1.0",
-			...huggingFaceAuthHeader(),
+			...resolveHfDownloadBase().authHeader,
 		};
 		if (startByte > 0) {
 			headers.range = `bytes=${startByte}-`;
 		}
 
 		const httpClient = await this.loadHttpClient();
-		const url = buildHuggingFaceResolveUrlForPath(catalogEntry, remotePath);
 		const response = await httpClient.request(url, {
 			method: "GET",
 			headers,

package/src/services/engine-direct-bundle.test.ts

@@ -5,6 +5,7 @@ import { afterEach, describe, expect, it } from "vitest";
 
 import type { BackendPlan } from "./backend";
 import { LocalInferenceEngine } from "./engine";
+import type { VoiceStartupError } from "./voice/engine-bridge";
 
 const ORIGINAL_ENV = { ...process.env };
 
@@ -27,21 +28,25 @@ describe("LocalInferenceEngine direct Eliza-1 bundle loads", () => {
 			captured = plan;
 		};
 
-		const bundleRoot = path.join(root, "eliza-1-0_8b.bundle");
-		const modelPath = path.join(bundleRoot, "text", "eliza-1-0_8b-128k.gguf");
+		const bundleRoot = path.join(root, "eliza-1-2b.bundle");
+		const litertPath = path.join(bundleRoot, "text", "eliza-1-2b.litertlm");
+		fs.mkdirSync(path.dirname(litertPath), { recursive: true });
+		fs.writeFileSync(litertPath, "fake litert bundle");
+		const modelPath = path.join(bundleRoot, "text", "eliza-1-2b-128k.gguf");
 		await engine.load(modelPath, {
 			modelPath,
-			modelId: "eliza-1-0_8b",
+			modelId: "eliza-1-2b",
 		});
 
 		expect(captured).toBeDefined();
 		expect(captured?.modelPath).toBe(modelPath);
-		expect(captured?.modelId).toBe("eliza-1-0_8b");
-		expect(captured?.catalog?.id).toBe("eliza-1-0_8b");
+		expect(captured?.modelId).toBe("eliza-1-2b");
+		expect(captured?.catalog?.id).toBe("eliza-1-2b");
 		expect(captured?.overrides?.bundleRoot).toBe(bundleRoot);
 		expect(captured?.overrides?.manifestPath).toBe(
 			path.join(bundleRoot, "eliza-1.manifest.json"),
 		);
+		expect(captured?.overrides?.litertModelPath).toBe(litertPath);
 		expect(
 			(
 				engine as unknown as {
@@ -51,8 +56,35 @@ describe("LocalInferenceEngine direct Eliza-1 bundle loads", () => {
 		).toEqual(
 			expect.objectContaining({
 				root: bundleRoot,
-				tierId: "eliza-1-0_8b",
+				tierId: "eliza-1-2b",
 			}),
 		);
 	});
+
+	it("rejects Qwen ASR provenance before starting the fused voice bridge", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-engine-test-"));
+		process.env.ELIZA_STATE_DIR = root;
+		const bundleRoot = path.join(root, "eliza-1-2b.bundle");
+		fs.mkdirSync(path.join(bundleRoot, "asr"), { recursive: true });
+		fs.writeFileSync(path.join(bundleRoot, "asr", "model.gguf"), "asr");
+		fs.writeFileSync(
+			path.join(bundleRoot, "eliza-1.manifest.json"),
+			JSON.stringify({ lineage: { asr: { base: "Qwen3-ASR" } } }),
+		);
+
+		const engine = new LocalInferenceEngine();
+		(
+			engine as unknown as {
+				activeEliza1Bundle: { root: string; tierId: "eliza-1-2b" };
+			}
+		).activeEliza1Bundle = { root: bundleRoot, tierId: "eliza-1-2b" };
+		(
+			engine as unknown as { dispatcher: { hasLoadedModel(): boolean } }
+		).dispatcher.hasLoadedModel = () => true;
+
+		await expect(engine.ensureActiveBundleAsrReady()).rejects.toMatchObject({
+			name: "VoiceStartupError",
+			code: "blocked-asr-provenance",
+		} satisfies Partial<VoiceStartupError>);
+	});
 });