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

package/src/services/recommendation.ts

@@ -0,0 +1,671 @@
+import {
+	DEFAULT_ELIGIBLE_MODEL_IDS,
+	type Eliza1TierId,
+	eliza1TierPublishStatus,
+	FIRST_RUN_DEFAULT_MODEL_ID,
+	MODEL_CATALOG,
+} from "./catalog";
+import {
+	canSetAsDefault,
+	type Eliza1Backend,
+	type Eliza1DeviceCaps,
+	type Eliza1Manifest,
+	SUPPORTED_BACKENDS_BY_TIER,
+} from "./manifest";
+import {
+	assessRamFit,
+	defaultManifestLoader,
+	type ManifestLoader,
+} from "./ram-budget";
+import type {
+	CatalogModel,
+	CatalogQuantizationVariant,
+	HardwareFitLevel,
+	HardwareProbe,
+	InstalledModel,
+	TextGenerationSlot,
+} from "./types";
+
+const TIER_2B: Eliza1TierId = "eliza-1-2b";
+const TIER_4B: Eliza1TierId = "eliza-1-4b";
+const TIER_9B: Eliza1TierId = "eliza-1-9b";
+const TIER_27B: Eliza1TierId = "eliza-1-27b";
+
+export type RecommendationPlatformClass =
+	| "mobile"
+	| "apple-silicon"
+	| "linux-gpu"
+	| "linux-cpu"
+	| "desktop-gpu"
+	| "desktop-cpu";
+
+export interface RecommendedModelSelection {
+	slot: TextGenerationSlot;
+	platformClass: RecommendationPlatformClass;
+	model: CatalogModel | null;
+	fit: HardwareFitLevel | null;
+	reason: string;
+	alternatives: CatalogModel[];
+}
+
+const BYTES_PER_GB = 1024 ** 3;
+
+/**
+ * Per-platform slot ladders. Every default-recommended entry is an
+ * Eliza-1 tier (the only default-eligible line — see catalog.ts and
+ * `packages/inference/AGENTS.md` §2). Ladders bias toward the smallest
+ * tier that fits the platform; desktops/servers pick larger tiers
+ * first when memory headroom allows.
+ */
+const SLOT_LADDERS: Record<
+	RecommendationPlatformClass,
+	Record<TextGenerationSlot, ReadonlyArray<Eliza1TierId>>
+> = {
+	mobile: {
+		TEXT_SMALL: [TIER_2B],
+		TEXT_LARGE: [TIER_4B, TIER_2B],
+	},
+	"apple-silicon": {
+		TEXT_SMALL: [TIER_2B, TIER_4B],
+		TEXT_LARGE: [TIER_27B, TIER_9B, TIER_4B, TIER_2B],
+	},
+	"linux-gpu": {
+		TEXT_SMALL: [TIER_2B, TIER_4B],
+		TEXT_LARGE: [TIER_27B, TIER_9B, TIER_4B, TIER_2B],
+	},
+	"linux-cpu": {
+		TEXT_SMALL: [TIER_2B, TIER_4B],
+		TEXT_LARGE: [TIER_9B, TIER_4B, TIER_2B],
+	},
+	"desktop-gpu": {
+		TEXT_SMALL: [TIER_2B, TIER_4B],
+		TEXT_LARGE: [TIER_27B, TIER_9B, TIER_4B, TIER_2B],
+	},
+	"desktop-cpu": {
+		TEXT_SMALL: [TIER_2B, TIER_4B],
+		TEXT_LARGE: [TIER_9B, TIER_4B, TIER_2B],
+	},
+};
+
+function catalogById(catalog: CatalogModel[]): Map<string, CatalogModel> {
+	return new Map(catalog.map((model) => [model.id, model]));
+}
+
+function chatCandidates(catalog: CatalogModel[]): CatalogModel[] {
+	return catalog.filter((model) => !model.hiddenFromCatalog);
+}
+
+export function classifyRecommendationPlatform(
+	hardware: HardwareProbe,
+): RecommendationPlatformClass {
+	// Mobile detection comes from the typed `hardware.mobile.platform`
+	// field (`"ios" | "android" | "web"`). `NodeJS.Platform` doesn't
+	// include those values — the previous `process.platform as string`
+	// cast was hiding that the cast was the only way the comparison
+	// type-checked. Reading the proper typed field is both safer and
+	// accurate when a host advertises mobile via the mobile probe.
+	const mobilePlatform = hardware.mobile?.platform;
+	if (mobilePlatform === "android" || mobilePlatform === "ios") return "mobile";
+
+	const platform = hardware.platform;
+	if (hardware.appleSilicon) return "apple-silicon";
+	if (platform === "linux" && hardware.gpu) return "linux-gpu";
+	if (platform === "linux") return "linux-cpu";
+	if (hardware.gpu) return "desktop-gpu";
+	return "desktop-cpu";
+}
+
+export function catalogDownloadSizeGb(
+	model: CatalogModel,
+	catalog: CatalogModel[] = MODEL_CATALOG,
+): number {
+	void catalog;
+	return model.sizeGb;
+}
+
+export function catalogDownloadSizeBytes(
+	model: CatalogModel,
+	catalog: CatalogModel[] = MODEL_CATALOG,
+): number {
+	return Math.round(catalogDownloadSizeGb(model, catalog) * BYTES_PER_GB);
+}
+
+export function selectBestQuantizationVariant(
+	model: CatalogModel,
+): CatalogQuantizationVariant | null {
+	const quantization = model.quantization;
+	if (!quantization) return null;
+	return (
+		quantization.variants.find(
+			(variant) => variant.id === quantization.defaultVariantId,
+		) ??
+		quantization.variants.find((variant) => variant.status === "published") ??
+		quantization.variants[0] ??
+		null
+	);
+}
+
+const MB_PER_GB = 1024;
+
+/**
+ * Memory the model can actually use on this host, in GB. On Apple Silicon
+ * and mobile the GPU shares system RAM, so total RAM acts as the budget.
+ * On discrete-GPU x86 the KV cache + weights live wherever the layers do —
+ * weight VRAM higher. CPU-only hosts can give about half of RAM to a model
+ * before paging hurts.
+ */
+function effectiveMemoryGb(probe: HardwareProbe): number {
+	if (probe.appleSilicon) return probe.totalRamGb;
+	if (probe.gpu) {
+		return Math.max(probe.gpu.totalVramGb, probe.totalRamGb * 0.5);
+	}
+	return probe.totalRamGb * 0.5;
+}
+
+/**
+ * Download-size guardrail layered on top of the RAM-budget fit decision:
+ * a bundle whose on-disk footprint is a large fraction of the available
+ * memory will swap even if the RAM-budget floor says it boots. Returns
+ * `"wontfit"` / `"tight"` / `null` ("the size is fine; defer to the
+ * RAM-budget level"). Ratios match the historical `assessFit` (desktop)
+ * and `mobileFit` (mobile) thresholds.
+ */
+function downloadSizeGuardrail(
+	hardware: HardwareProbe,
+	model: CatalogModel,
+	catalog: CatalogModel[],
+	isMobile: boolean,
+): HardwareFitLevel | null {
+	const sizeGb = catalogDownloadSizeGb(model, catalog);
+	const memGb = isMobile ? hardware.totalRamGb : effectiveMemoryGb(hardware);
+	const wontFitRatio = isMobile ? 0.8 : 0.9;
+	const tightRatio = isMobile ? 0.65 : 0.7;
+	if (sizeGb > memGb * wontFitRatio) return "wontfit";
+	if (sizeGb > memGb * tightRatio) return "tight";
+	return null;
+}
+
+export function assessCatalogModelFit(
+	hardware: HardwareProbe,
+	model: CatalogModel,
+	catalog: CatalogModel[] = MODEL_CATALOG,
+	options: { installed?: InstalledModel; manifestLoader?: ManifestLoader } = {},
+): HardwareFitLevel {
+	const isMobile = classifyRecommendationPlatform(hardware) === "mobile";
+	const memGb = isMobile ? hardware.totalRamGb : effectiveMemoryGb(hardware);
+	// Single source of truth for the RAM floor + fits-vs-tight cutoff:
+	// `ram-budget.assessRamFit`. The recommender works in "memory available
+	// to the model" terms (VRAM-weighted on GPU hosts), so the OS headroom
+	// reserve is already discounted — pass `reserveMb: 0`.
+	const ramFit = assessRamFit(model, memGb * MB_PER_GB, {
+		installed: options.installed,
+		manifestLoader: options.manifestLoader ?? defaultManifestLoader,
+		reserveMb: 0,
+	});
+	if (!ramFit.fits) return "wontfit";
+	const sizeLevel = downloadSizeGuardrail(hardware, model, catalog, isMobile);
+	if (sizeLevel === "wontfit") return "wontfit";
+	if (sizeLevel === "tight" || ramFit.level === "tight") return "tight";
+	return "fits";
+}
+
+function canFit(
+	hardware: HardwareProbe,
+	model: CatalogModel,
+	catalog: CatalogModel[],
+	options: { installed?: InstalledModel; manifestLoader?: ManifestLoader } = {},
+): boolean {
+	if (!hasUsableCpuBackendForRecommendation(hardware)) return false;
+	return assessCatalogModelFit(hardware, model, catalog, options) !== "wontfit";
+}
+
+function hasUsableCpuBackendForRecommendation(
+	hardware: HardwareProbe,
+): boolean {
+	if (hardware.gpu) return true;
+	if (hardware.arch !== "arm64" && hardware.arch !== "arm") return true;
+	return hardware.cpuFeatures?.neon === true;
+}
+
+/**
+ * True when every kernel listed in `model.runtime.optimizations.requiresKernel`
+ * is advertised as `true` in the binary's CAPABILITIES.json kernels map.
+ *
+ * `binaryKernels === null` means we have no probe (older binary, or
+ * llama-server isn't installed). In that case we trust the catalog —
+ * filtering would hide every kernel-required model and the dispatcher's
+ * load-time check will surface the real error if/when the user tries to
+ * activate it.
+ *
+ * `unsupportedKernels` is a soft signal layered on top: when the binary
+ * has no satisfied `requiresKernel` anchor and exposes only an unsupported
+ * backend (OpenVINO-only Intel build for an Eliza-1 text tier), drop the
+ * tier so the recommender doesn't suggest a path that has no kernel route.
+ * A binary that already satisfies `requiresKernel` stays eligible even
+ * when it also advertises an unsupported backend (e.g. OpenVINO
+ * co-compiled — the dispatcher steers the spawn off OpenVINO via
+ * `applyUnsupportedKernelEnv` at runtime).
+ */
+function kernelRequirementsSatisfied(
+	model: CatalogModel,
+	binaryKernels: Partial<Record<string, boolean>> | null,
+): boolean {
+	const required = model.runtime?.optimizations?.requiresKernel ?? [];
+	if (!binaryKernels) return true;
+	if (required.length > 0) {
+		return required.every((k) => binaryKernels[k] === true);
+	}
+	const unsupported = model.runtime?.optimizations?.unsupportedKernels ?? [];
+	return !unsupported.some((k) => binaryKernels[k] === true);
+}
+
+function modelsFromLadder(
+	ids: ReadonlyArray<string>,
+	catalog: CatalogModel[],
+): CatalogModel[] {
+	const byId = catalogById(catalog);
+	return ids.flatMap((id) => {
+		const model = byId.get(id);
+		return model ? [model] : [];
+	});
+}
+
+/**
+ * True when this host has enough memory headroom to serve the long-context
+ * KV cache for a 64k+ window. Threshold mirrors the "16 GB workstation"
+ * line from the porting plan — a 64k context for an 8B model at fp16 KV
+ * occupies ~4 GB; with TurboQuant compression it fits inside 1 GB. Below
+ * 16 GB total we keep the historical short-context preference.
+ *
+ * For GPU hosts we look at total VRAM, since the KV cache lives wherever
+ * the layers do; for CPU-only hosts we look at total RAM.
+ */
+const LONG_CONTEXT_RAM_BUMP_THRESHOLD_GB = 16;
+const LONG_CONTEXT_MIN_LENGTH = 65536;
+
+function hasLongContextHeadroom(hardware: HardwareProbe): boolean {
+	const vramGb = hardware.gpu?.totalVramGb ?? 0;
+	if (vramGb >= LONG_CONTEXT_RAM_BUMP_THRESHOLD_GB) return true;
+	return hardware.totalRamGb >= LONG_CONTEXT_RAM_BUMP_THRESHOLD_GB;
+}
+
+function isLongContextModel(model: CatalogModel): boolean {
+	return (
+		typeof model.contextLength === "number" &&
+		model.contextLength >= LONG_CONTEXT_MIN_LENGTH
+	);
+}
+
+function fallbackCandidates(
+	slot: TextGenerationSlot,
+	hardware: HardwareProbe,
+	catalog: CatalogModel[],
+	budgetOptions: BudgetOptions,
+): CatalogModel[] {
+	const candidates = chatCandidates(catalog).filter(
+		(model) =>
+			DEFAULT_ELIGIBLE_MODEL_IDS.has(model.id) &&
+			canFit(
+				hardware,
+				model,
+				catalog,
+				budgetOptionsForModel(model, budgetOptions),
+			),
+	);
+	const preferLongContext = hasLongContextHeadroom(hardware);
+	return candidates.sort((left, right) => {
+		if (preferLongContext) {
+			const leftLong = isLongContextModel(left) ? 1 : 0;
+			const rightLong = isLongContextModel(right) ? 1 : 0;
+			if (leftLong !== rightLong) return rightLong - leftLong;
+		}
+		const sizeDelta =
+			catalogDownloadSizeGb(right, catalog) -
+			catalogDownloadSizeGb(left, catalog);
+		return slot === "TEXT_LARGE" ? sizeDelta : -sizeDelta;
+	});
+}
+
+export interface RecommendationOptions {
+	/**
+	 * Kernels actually advertised by the installed llama-server binary
+	 * (parsed from CAPABILITIES.json next to it). When provided, models
+	 * declaring `requiresKernel` not satisfied by this map are filtered
+	 * out so we don't recommend a model the user can't actually run on
+	 * this binary. Pass null/omit when no probe is available — recommender
+	 * trusts the catalog and the dispatcher's load-time check.
+	 */
+	binaryKernels?: Partial<Record<string, boolean>> | null;
+	/**
+	 * Models the user has already installed. When an Eliza-1 tier in this
+	 * list has a published `eliza-1.manifest.json` next to its bundle,
+	 * the recommender consults `manifest.ramBudgetMb` instead of the
+	 * catalog's coarse `minRamGb` scalar. See `./ram-budget.ts`.
+	 */
+	installed?: ReadonlyArray<InstalledModel>;
+	/**
+	 * Test-only override for the manifest reader. Production callers leave
+	 * this unset and the helper reads `eliza-1.manifest.json` from disk.
+	 */
+	manifestLoader?: ManifestLoader;
+}
+
+interface BudgetOptions {
+	installed: ReadonlyArray<InstalledModel>;
+	manifestLoader: ManifestLoader;
+}
+
+function budgetOptionsForModel(
+	model: CatalogModel,
+	budget: BudgetOptions,
+): { installed?: InstalledModel; manifestLoader: ManifestLoader } {
+	return {
+		installed: budget.installed.find((m) => m.id === model.id),
+		manifestLoader: budget.manifestLoader,
+	};
+}
+
+function resolveBudgetOptions(options: RecommendationOptions): BudgetOptions {
+	return {
+		installed: options.installed ?? [],
+		manifestLoader: options.manifestLoader ?? defaultManifestLoader,
+	};
+}
+
+export function selectRecommendedModelForSlot(
+	slot: TextGenerationSlot,
+	hardware: HardwareProbe,
+	catalog: CatalogModel[] = MODEL_CATALOG,
+	options: RecommendationOptions = {},
+): RecommendedModelSelection {
+	const platformClass = classifyRecommendationPlatform(hardware);
+	const ladder = modelsFromLadder(SLOT_LADDERS[platformClass][slot], catalog);
+	const binaryKernels = options.binaryKernels ?? null;
+	const budget = resolveBudgetOptions(options);
+	const eligible = ladder.filter(
+		(model) =>
+			canFit(hardware, model, catalog, budgetOptionsForModel(model, budget)) &&
+			kernelRequirementsSatisfied(model, binaryKernels),
+	);
+
+	// On hosts with >= 16 GB RAM/VRAM, give long-context (>= 64k) ladder
+	// entries a small bump so we surface 128k models when they fit. The
+	// ladder order still wins when long-context availability is the same
+	// for every entry (or when the host doesn't have the headroom).
+	const ranked =
+		slot === "TEXT_LARGE" &&
+		eligible.length > 0 &&
+		hasLongContextHeadroom(hardware)
+			? rankLadderByLongContext(eligible)
+			: eligible;
+
+	const alternatives =
+		ranked.length > 0
+			? ranked
+			: fallbackCandidates(slot, hardware, catalog, budget).filter((model) =>
+					kernelRequirementsSatisfied(model, binaryKernels),
+				);
+	const model = alternatives[0] ?? null;
+	const fit = model
+		? assessCatalogModelFit(
+				hardware,
+				model,
+				catalog,
+				budgetOptionsForModel(model, budget),
+			)
+		: null;
+	return {
+		slot,
+		platformClass,
+		model,
+		fit,
+		reason: model
+			? `${platformClass} ${slot} ladder selected ${model.id}`
+			: `${platformClass} ${slot} ladder has no fitting catalog model`,
+		alternatives,
+	};
+}
+
+/**
+ * Stable sort that pulls long-context models toward the front while
+ * preserving relative order within each group. Used only on hosts with
+ * the long-context RAM/VRAM headroom — the ladder order remains the
+ * tie-breaker so native-runtime preferences survive.
+ */
+function rankLadderByLongContext(ladder: CatalogModel[]): CatalogModel[] {
+	return ladder
+		.map((model, idx) => ({ model, idx, long: isLongContextModel(model) }))
+		.sort((left, right) => {
+			if (left.long !== right.long) return right.long ? 1 : -1;
+			return left.idx - right.idx;
+		})
+		.map((entry) => entry.model);
+}
+
+// ---------------------------------------------------------------------------
+// Default-eligibility on this device — the recommendation-engine gate that
+// consults the bundle's `eliza-1.manifest.json` (`kernels.verifiedBackends`,
+// `evals`, `defaultEligible`) against the device hardware + the bundle's
+// on-device verify state. See `packages/inference/AGENTS.md` §6 + §7.
+// ---------------------------------------------------------------------------
+
+/**
+ * Project a `HardwareProbe` onto the `Eliza1DeviceCaps` shape the manifest
+ * validator's `canSetAsDefault` consumes. CPU is always available; a probed
+ * GPU contributes exactly its one backend (`cuda` / `metal` / `vulkan`). RAM
+ * is the device total, in MB — `canSetAsDefault` compares against the
+ * manifest's `ramBudgetMb.min` floor, not the headroom-discounted figure the
+ * ladder uses, because the floor is "will it boot at all".
+ */
+export function deviceCapsFromProbe(hardware: HardwareProbe): Eliza1DeviceCaps {
+	const backends: Eliza1Backend[] =
+		hardware.arch === "arm64" || hardware.arch === "arm"
+			? hardware.cpuFeatures?.neon === true
+				? ["cpu"]
+				: []
+			: ["cpu"];
+	if (hardware.gpu) backends.push(hardware.gpu.backend);
+	return {
+		availableBackends: backends,
+		ramMb: Math.round(hardware.totalRamGb * 1024),
+		cpuFeatures: hardware.cpuFeatures,
+	};
+}
+
+export type BundleDefaultEligibility =
+	| { canBeDefault: true }
+	| {
+			canBeDefault: false;
+			reason:
+				| "no-manifest"
+				| "not-default-eligible"
+				| "ram-below-floor"
+				| "kernels-unverified-on-device"
+				| "not-verified-on-device";
+			detail: string;
+	  };
+
+/**
+ * True iff this installed Eliza-1 bundle may be offered as the recommended
+ * default on this device. The full set of conditions (any one failing →
+ * not default):
+ *
+ *  - the bundle ships a validated `eliza-1.manifest.json`,
+ *  - the manifest is contract-valid (every required kernel declared, every
+ *    required eval green for a strict release, lineage/files consistent —
+ *    enforced by `canSetAsDefault` → `collectContractErrors`),
+ *  - the device exposes at least one backend the manifest verified `pass` on
+ *    out of the tier's supported set,
+ *  - the device RAM meets the manifest's `ramBudgetMb.min` floor,
+ *  - the bundle has passed the one-time on-device verify pass
+ *    (`InstalledModel.bundleVerifiedAt` is set) — a materialized-but-unverified
+ *    bundle is never auto-selected, per AGENTS.md §7.
+ *
+ * `manifest.defaultEligible: true` is NOT required at the gate level — a
+ * `base-v1-candidate` bundle that passes every above condition is allowed
+ * to fill an empty default slot. The recommender prefers a strict release
+ * (`defaultEligible: true`) over a candidate when both are installed.
+ */
+export function canBundleBeDefaultOnDevice(
+	installed: InstalledModel,
+	hardware: HardwareProbe,
+	options: { manifestLoader?: ManifestLoader } = {},
+): BundleDefaultEligibility {
+	const loader = options.manifestLoader ?? defaultManifestLoader;
+	const manifest: Eliza1Manifest | null = loader(installed.id, installed);
+	if (!manifest) {
+		return {
+			canBeDefault: false,
+			reason: "no-manifest",
+			detail: `${installed.id}: no validated eliza-1.manifest.json next to the bundle`,
+		};
+	}
+	if (!installed.bundleVerifiedAt) {
+		return {
+			canBeDefault: false,
+			reason: "not-verified-on-device",
+			detail: `${installed.id}: bundle materialized but the on-device verify pass (load → 1-token text → 1-phrase voice → barge-in) has not run`,
+		};
+	}
+	const caps = deviceCapsFromProbe(hardware);
+	if (canSetAsDefault(manifest, caps)) return { canBeDefault: true };
+
+	// canSetAsDefault returned false — disambiguate why so the UI/log is precise.
+	if (manifest.ramBudgetMb.min > caps.ramMb) {
+		return {
+			canBeDefault: false,
+			reason: "ram-below-floor",
+			detail: `${installed.id}: device RAM ${caps.ramMb} MB is below the manifest floor ${manifest.ramBudgetMb.min} MB`,
+		};
+	}
+	const supported = new Set<Eliza1Backend>(
+		SUPPORTED_BACKENDS_BY_TIER[manifest.tier],
+	);
+	const verifiedOnDeviceBackend = caps.availableBackends.some(
+		(b) =>
+			supported.has(b) &&
+			manifest.kernels.verifiedBackends[b].status === "pass",
+	);
+	if (!verifiedOnDeviceBackend) {
+		const deviceBackends = caps.availableBackends.join(", ");
+		return {
+			canBeDefault: false,
+			reason: "kernels-unverified-on-device",
+			detail: `${installed.id}: no backend the device exposes (${deviceBackends}) has a 'pass' kernel-verify report in the manifest`,
+		};
+	}
+	// RAM ok, backend ok — the failure must be a manifest-contract path the
+	// validator caught (e.g. a required-eval gate not passed for a strict
+	// release, a lineage/files mismatch, an inconsistent provenance block).
+	// All contract failures make the bundle ineligible to be the device default.
+	return {
+		canBeDefault: false,
+		reason: "not-default-eligible",
+		detail: `${installed.id}: manifest failed the contract check (an eval gate, kernel-coverage rule, or lineage/files consistency rule)`,
+	};
+}
+
+export function selectRecommendedModels(
+	hardware: HardwareProbe,
+	catalog: CatalogModel[] = MODEL_CATALOG,
+	options: RecommendationOptions = {},
+): Record<TextGenerationSlot, RecommendedModelSelection> {
+	return {
+		TEXT_SMALL: selectRecommendedModelForSlot(
+			"TEXT_SMALL",
+			hardware,
+			catalog,
+			options,
+		),
+		TEXT_LARGE: selectRecommendedModelForSlot(
+			"TEXT_LARGE",
+			hardware,
+			catalog,
+			options,
+		),
+	};
+}
+
+/**
+ * Pick the model the engine should auto-load on first run when no user
+ * preference exists. Always resolves to an Eliza-1 default-eligible
+ * tier — never a non-Eliza catalog entry, never a HF-search result.
+ *
+ * Resolution order:
+ *   1. `FIRST_RUN_DEFAULT_MODEL_ID` when present in the catalog, in the
+ *      default-eligible set, and not marked `publishStatus: "pending"`.
+ *   2. The first default-eligible, non-pending chat entry in the catalog
+ *      as a fallback when the preferred id is missing or its HF bundle
+ *      isn't published yet (elizaOS/eliza#7629). The fall-through walks
+ *      the catalog in order, so the maintainer can keep
+ *      `FIRST_RUN_DEFAULT_MODEL_ID` pointed at the *intended* default
+ *      while the publish pipeline catches up.
+ *   3. If every default-eligible tier is pending, last-resort to ANY
+ *      default-eligible tier — the device download path will fail
+ *      cleanly with a 404 rather than silently picking a private
+ *      non-Eliza model.
+ *
+ * Returns null only when no default-eligible entry exists at all —
+ * which means the catalog is misconfigured and the caller should
+ * surface a hard error rather than degrade silently.
+ */
+export function recommendForFirstRun(
+	catalog: CatalogModel[] = MODEL_CATALOG,
+): CatalogModel | null {
+	const byId = catalogById(catalog);
+	const isEligibleChat = (model: CatalogModel): boolean =>
+		!model.hiddenFromCatalog && DEFAULT_ELIGIBLE_MODEL_IDS.has(model.id);
+	const publishStatusFor = (model: CatalogModel): "published" | "pending" =>
+		model.publishStatus ?? eliza1TierPublishStatus(model.id as Eliza1TierId);
+	const isPublishedEligibleChat = (model: CatalogModel): boolean =>
+		isEligibleChat(model) && publishStatusFor(model) === "published";
+
+	const preferred = byId.get(FIRST_RUN_DEFAULT_MODEL_ID);
+	if (preferred && isPublishedEligibleChat(preferred)) return preferred;
+
+	// Preferred is missing or its bundle is still being published — walk the
+	// catalog for the first eligible chat tier whose bundle IS published.
+	const fallbackPublished = catalog.find(isPublishedEligibleChat);
+	if (fallbackPublished) return fallbackPublished;
+
+	// Every eligible tier is "pending" — last-resort to the preferred tier
+	// when it exists in the catalog, otherwise the first default-eligible
+	// chat entry. Either path lets the downloader emit a clear "manifest
+	// 404" message rather than silently picking a non-Eliza model.
+	if (preferred && isEligibleChat(preferred)) return preferred;
+	return catalog.find(isEligibleChat) ?? null;
+}
+
+export function chooseSmallerFallbackModel(
+	currentModelId: string,
+	hardware: HardwareProbe,
+	slot: TextGenerationSlot = "TEXT_LARGE",
+	catalog: CatalogModel[] = MODEL_CATALOG,
+	options: RecommendationOptions = {},
+): CatalogModel | null {
+	const byId = catalogById(catalog);
+	const current = byId.get(currentModelId);
+	const currentSize = current
+		? catalogDownloadSizeGb(current, catalog)
+		: Number.POSITIVE_INFINITY;
+	const platformClass = classifyRecommendationPlatform(hardware);
+	const budget = resolveBudgetOptions(options);
+	const ladderFallback = modelsFromLadder(
+		SLOT_LADDERS[platformClass][slot],
+		catalog,
+	)
+		.filter((model) => model.id !== currentModelId)
+		.filter((model) => catalogDownloadSizeGb(model, catalog) < currentSize)
+		.filter((model) =>
+			canFit(hardware, model, catalog, budgetOptionsForModel(model, budget)),
+		)[0];
+	if (ladderFallback) return ladderFallback;
+
+	return (
+		fallbackCandidates(slot, hardware, catalog, budget)
+			.filter((model) => model.id !== currentModelId)
+			.filter(
+				(model) => catalogDownloadSizeGb(model, catalog) < currentSize,
+			)[0] ?? null
+	);
+}

package/src/services/registry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * On-disk registry of installed models.
+ *
+ * Two sources feed the registry:
+ *   1. Eliza-owned downloads (source: "eliza-download") — written on
+ *      successful completion by the downloader.
+ *   2. External scans (source: "external-scan") — merged in at read time
+ *      from `scanExternalModels()`. These are never persisted to the
+ *      registry file; a rescan runs whenever we read.
+ *
+ * The JSON file only holds Eliza-owned entries. That way, if a user
+ * cleans up LM Studio models we don't show stale ghosts.
+ */
+import type { InstalledModel } from "./types";
+/**
+ * Return all models currently usable: persisted Eliza downloads plus a
+ * fresh external-tool scan. External duplicates of Eliza-owned files are
+ * filtered out by path.
+ */
+export declare function listInstalledModels(): Promise<InstalledModel[]>;
+/** Add or update a Eliza-owned entry. External entries are rejected. */
+export declare function upsertElizaModel(model: InstalledModel): Promise<void>;
+/** Mark an existing Eliza-owned model as most-recently-used. */
+export declare function touchElizaModel(id: string): Promise<void>;
+/**
+ * Delete a Eliza-owned model from the registry and from disk.
+ *
+ * Refuses if the model was discovered from another tool — Eliza must not
+ * touch files it doesn't own. Callers surface that refusal as a 4xx.
+ */
+export declare function removeElizaModel(id: string): Promise<{
+    removed: boolean;
+    reason?: "external" | "not-found";
+}>;
+//# sourceMappingURL=registry.d.ts.map