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

package/src/services/cache-bridge.ts

@@ -0,0 +1,423 @@
+/**
+ * Cache bridge for the local-inference path.
+ *
+ * Translates the runtime's `ProviderCachePlan` (a provider-neutral cache
+ * plan emitted by `@elizaos/core`'s `buildProviderCachePlan`) into
+ * concrete behaviour for the two local backends:
+ *
+ *   1. Out-of-process llama-server (MTP / buun-llama-cpp): stable
+ *      slot-id derivation + on-disk slot KV save/restore directory layout
+ *      + TTL-based eviction by mtime.
+ *   2. In-process node-llama-cpp: a session pool (see
+ *      `session-pool.ts`) keyed by `promptCacheKey`.
+ *
+ * This module is pure logic — no llama-server process management, no
+ * node-llama-cpp imports. All filesystem state is rooted under
+ * `local-inference/llama-cache/` so cleanup is easy and explicit.
+ */
+
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { localInferenceRoot } from "./paths";
+
+/**
+ * TTLs for cached prefix data, mirroring the cloud-side semantics:
+ *   - `short`: roughly the "default" Anthropic ephemeral cache window.
+ *   - `long`: roughly the "1h" Anthropic ephemeral cache window.
+ *   - `extended`: the OpenAI 24h prompt-cache retention window.
+ *
+ * Values are in milliseconds. Eviction uses file mtime, not access time,
+ * so a slot that is read repeatedly without being rewritten still ages
+ * out — which matches how llama-server writes the slot file each turn.
+ */
+export interface CacheTtls {
+	short: number;
+	long: number;
+	extended?: number;
+}
+
+export const DEFAULT_CACHE_TTLS: CacheTtls = {
+	short: 5 * 60 * 1000,
+	long: 60 * 60 * 1000,
+	extended: 24 * 60 * 60 * 1000,
+};
+
+/**
+ * Root directory for all local llama-cache state. Anything inside is
+ * Eliza-owned and safe to delete to reset the cache.
+ */
+export function llamaCacheRoot(): string {
+	return path.join(localInferenceRoot(), "llama-cache");
+}
+
+/**
+ * Per-model-hash cache directory. Slot save files for one model never
+ * collide with another model's; switching active model does not need to
+ * wipe the cache.
+ */
+export function cacheRoot(modelHash: string): string {
+	if (!modelHash) {
+		throw new Error("[cache-bridge] cacheRoot requires a non-empty modelHash");
+	}
+	return path.join(llamaCacheRoot(), modelHash);
+}
+
+/**
+ * llama-server `--slot-save-path` argument: the directory llama-server
+ * writes per-slot KV state into when a request includes
+ * `cache_prompt: true`. One directory per model hash.
+ */
+export function slotSavePath(modelHash: string): string {
+	return cacheRoot(modelHash);
+}
+
+/**
+ * Stable model-fingerprint hash. Combines the absolute paths of the
+ * target / drafter GGUFs and the cache-type knobs so two distinct
+ * configurations don't share a slot directory.
+ */
+export function buildModelHash(input: {
+	targetModelPath: string;
+	drafterModelPath?: string | null;
+	cacheTypeK?: string | null;
+	cacheTypeV?: string | null;
+	/** Optional extra discriminator (context size, parallel, etc.). */
+	extra?: string | null;
+}): string {
+	const hash = createHash("sha256");
+	hash.update(input.targetModelPath);
+	hash.update("
");
+	hash.update(input.drafterModelPath ?? "");
+	hash.update("
");
+	hash.update(input.cacheTypeK ?? "");
+	hash.update("
");
+	hash.update(input.cacheTypeV ?? "");
+	hash.update("
");
+	hash.update(input.extra ?? "");
+	return hash.digest("hex").slice(0, 16);
+}
+
+/**
+ * Map a `promptCacheKey` to a llama-server slot id in [0, parallel).
+ *
+ * llama-server's `--parallel N` flag pre-allocates N decoding slots and
+ * accepts a `slot_id` integer in `[0, N-1]` on each request. By hashing
+ * the cache key into that range we get:
+ *
+ *   - The same prefix hash always lands on the same slot, so the in-RAM
+ *     KV cache from the previous turn is reused.
+ *   - Different prefix hashes spread across slots and don't fight for
+ *     the same KV memory.
+ *
+ * Pass `parallel <= 0` to disable slot pinning (returns -1, the
+ * llama-server "any free slot" sentinel).
+ */
+export function deriveSlotId(promptCacheKey: string, parallel: number): number {
+	if (!Number.isFinite(parallel) || parallel <= 0) return -1;
+	if (!promptCacheKey) return -1;
+	const integerParallel = Math.max(1, Math.floor(parallel));
+	if (integerParallel === 1) return 0;
+	const digest = createHash("sha256").update(promptCacheKey).digest();
+	// Read first 4 bytes as an unsigned big-endian int. Plenty of entropy
+	// for parallel ≤ 64.
+	const value = digest.readUInt32BE(0);
+	return value % integerParallel;
+}
+
+/**
+ * Convert the runtime-side `CacheTTL` enum + OpenAI extended retention
+ * hint into a concrete TTL in milliseconds. This is what the eviction
+ * sweep uses when deciding whether a slot file is still live.
+ */
+export function ttlMsForKey(
+	ttl: "short" | "long" | "extended" | undefined,
+	ttls: CacheTtls = DEFAULT_CACHE_TTLS,
+): number {
+	if (ttl === "long") return ttls.long;
+	if (ttl === "extended") return ttls.extended ?? ttls.long;
+	return ttls.short;
+}
+
+/** TTL classes that can be encoded into a slot `.bin` filename. */
+export type SlotCacheTtlClass = "short" | "long" | "extended";
+
+/**
+ * Build the basename for a persisted slot/conversation `.bin` file with
+ * its TTL class encoded as a middle component: `<base>.<ttl>.bin`. The
+ * eviction sweep reads that component back via `parseSlotCacheTtlClass`
+ * so a slot persisted with the long retention window isn't deleted on
+ * the short horizon (and vice versa). Pass `"long"` for cross-restart
+ * conversation KV — that matches the prior global (long-only) behaviour
+ * for those files.
+ */
+export function slotCacheFileName(
+	base: string,
+	ttl: SlotCacheTtlClass,
+): string {
+	return `${base}.${ttl}.bin`;
+}
+
+/**
+ * Parse the TTL class encoded into a slot `.bin` filename by
+ * `slotCacheFileName`. Returns `undefined` for legacy / hand-written
+ * filenames without an encoded class — those keep the `long` horizon
+ * (the prior global behaviour for persisted slot files).
+ */
+export function parseSlotCacheTtlClass(
+	fileName: string,
+): SlotCacheTtlClass | undefined {
+	// `<base>.<ttl>.bin` — the penultimate dot-component is the class.
+	const withoutBin = fileName.endsWith(".bin")
+		? fileName.slice(0, -".bin".length)
+		: fileName;
+	const lastDot = withoutBin.lastIndexOf(".");
+	if (lastDot < 0) return undefined;
+	const candidate = withoutBin.slice(lastDot + 1);
+	if (
+		candidate === "short" ||
+		candidate === "long" ||
+		candidate === "extended"
+	) {
+		return candidate;
+	}
+	return undefined;
+}
+
+/**
+ * Sweep the slot-save directory and delete files older than their
+ * per-file TTL horizon. The TTL class is read from the filename
+ * (`<base>.<ttl>.bin` — see `slotCacheFileName`); files without an
+ * encoded class use the `long` horizon (the prior global behaviour).
+ * Mtime is the watermark; llama-server rewrites the slot file on every
+ * save, so a slot that's actively used keeps a fresh mtime.
+ *
+ * Returns the number of files deleted. Missing directories are not
+ * errors — eviction on a clean install just no-ops.
+ */
+export async function evictExpired(
+	rootDir: string,
+	ttls: CacheTtls = DEFAULT_CACHE_TTLS,
+	now: number = Date.now(),
+): Promise<number> {
+	let entries: string[];
+	try {
+		entries = await fs.readdir(rootDir);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") return 0;
+		throw err;
+	}
+	let deleted = 0;
+	for (const entry of entries) {
+		const full = path.join(rootDir, entry);
+		let stat: Awaited<ReturnType<typeof fs.stat>>;
+		try {
+			stat = await fs.stat(full);
+		} catch {
+			continue;
+		}
+		if (!stat.isFile()) continue;
+		const ttlClass = parseSlotCacheTtlClass(entry) ?? "long";
+		const horizon = ttlMsForKey(ttlClass, ttls);
+		if (now - stat.mtimeMs > horizon) {
+			try {
+				await fs.unlink(full);
+				deleted += 1;
+			} catch {
+				// Best-effort cleanup; another process may already have removed it.
+			}
+		}
+	}
+	return deleted;
+}
+
+export interface CacheStatsEntry {
+	file: string;
+	sizeBytes: number;
+	mtimeMs: number;
+	ageMs: number;
+}
+
+/**
+ * Snapshot of the on-disk slot-save directory. Used by the public
+ * `getLocalCacheStats()` debugging endpoint.
+ */
+export async function readCacheStats(
+	rootDir: string,
+	now: number = Date.now(),
+): Promise<CacheStatsEntry[]> {
+	let entries: string[];
+	try {
+		entries = await fs.readdir(rootDir);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw err;
+	}
+	const out: CacheStatsEntry[] = [];
+	for (const entry of entries) {
+		const full = path.join(rootDir, entry);
+		let stat: Awaited<ReturnType<typeof fs.stat>>;
+		try {
+			stat = await fs.stat(full);
+		} catch {
+			continue;
+		}
+		if (!stat.isFile()) continue;
+		out.push({
+			file: entry,
+			sizeBytes: stat.size,
+			mtimeMs: stat.mtimeMs,
+			ageMs: Math.max(0, now - stat.mtimeMs),
+		});
+	}
+	out.sort((left, right) => left.file.localeCompare(right.file));
+	return out;
+}
+
+/**
+ * Resolve `promptCacheKey` from a `providerOptions` payload as emitted
+ * by `buildProviderCachePlan`. The runtime stuffs it under
+ * `providerOptions.eliza.promptCacheKey`. Returns `null` when the key is
+ * missing or not a non-empty string — callers fall back to the default
+ * "_default" session in that case.
+ */
+export function extractPromptCacheKey(providerOptions: unknown): string | null {
+	if (!providerOptions || typeof providerOptions !== "object") return null;
+	const eliza = (providerOptions as Record<string, unknown>).eliza;
+	if (!eliza || typeof eliza !== "object") return null;
+	const raw = (eliza as Record<string, unknown>).promptCacheKey;
+	if (typeof raw !== "string" || raw.length === 0) return null;
+	return raw;
+}
+
+/**
+ * Resolve `prefixHash` from `providerOptions.eliza.prefixHash`. Mirrors
+ * `extractPromptCacheKey` — returns null when missing or not a non-empty
+ * string. The prefix hash covers ONLY the stable prompt prefix (system
+ * prompt + tool definitions + large constant context), so a runtime
+ * timestamp in the unstable tail does not invalidate it.
+ *
+ * Local backends prefer this over `promptCacheKey` when available because
+ * it gives the strongest "same prefix → same slot" guarantee: two
+ * conversations with byte-identical stable prefixes will land on the same
+ * slot regardless of how their tail content differs.
+ */
+export function extractPrefixHash(providerOptions: unknown): string | null {
+	if (!providerOptions || typeof providerOptions !== "object") return null;
+	const eliza = (providerOptions as Record<string, unknown>).eliza;
+	if (!eliza || typeof eliza !== "object") return null;
+	const raw = (eliza as Record<string, unknown>).prefixHash;
+	if (typeof raw !== "string" || raw.length === 0) return null;
+	return raw;
+}
+
+/**
+ * Stable annotation describing a single segment of the prompt as it was
+ * emitted by the runtime planner. The cache-bridge consumes this to
+ * compute a stable-prefix-only hash for slot pinning, without having to
+ * look at the (timestamp-laden) tail.
+ *
+ * Mirrors `PromptSegment` in @elizaos/core/src/types/model.ts but is kept
+ * standalone so the cache-bridge can be imported by the local-inference
+ * backends without a hard dep on `@elizaos/core`.
+ */
+export interface AnnotatedPromptSegment {
+	content: string;
+	stable: boolean;
+}
+
+/**
+ * Hash the longest stable prefix of `segments`. Stops at the first
+ * unstable segment, so a runtime timestamp in the unstable tail never
+ * shifts the hash. Returns `null` when no stable segment exists, signaling
+ * to the caller that prefix-cache reuse cannot be derived purely from the
+ * prompt structure (fall back to the prompt-cache-key path instead).
+ *
+ * The hash is sha256-truncated to 16 hex chars, matching `buildModelHash`
+ * — short enough for log lines, wide enough that collision is not a
+ * realistic concern for any plausible number of concurrent prefixes.
+ */
+export function hashStablePrefix(
+	segments: readonly AnnotatedPromptSegment[],
+): string | null {
+	if (segments.length === 0) return null;
+	const hash = createHash("sha256");
+	let consumed = 0;
+	for (const segment of segments) {
+		if (!segment.stable) break;
+		hash.update(segment.content);
+		hash.update("
");
+		consumed += 1;
+	}
+	if (consumed === 0) return null;
+	return hash.digest("hex").slice(0, 16);
+}
+
+/**
+ * Extract the per-segment stable annotations from a `providerOptions`
+ * payload. The runtime emits these as `providerOptions.eliza.promptSegments`
+ * when a structured prompt is available — local backends use it to compute
+ * `hashStablePrefix` directly, without having to re-parse the prompt text.
+ *
+ * Returns `null` when the field is absent or malformed; callers fall back
+ * to `extractPromptCacheKey` / `extractPrefixHash`.
+ */
+export function extractAnnotatedSegments(
+	providerOptions: unknown,
+): AnnotatedPromptSegment[] | null {
+	if (!providerOptions || typeof providerOptions !== "object") return null;
+	const eliza = (providerOptions as Record<string, unknown>).eliza;
+	if (!eliza || typeof eliza !== "object") return null;
+	const raw = (eliza as Record<string, unknown>).promptSegments;
+	if (!Array.isArray(raw)) return null;
+	const out: AnnotatedPromptSegment[] = [];
+	for (const entry of raw) {
+		if (!entry || typeof entry !== "object") return null;
+		const content = (entry as { content?: unknown }).content;
+		const stable = (entry as { stable?: unknown }).stable;
+		if (typeof content !== "string" || typeof stable !== "boolean") return null;
+		out.push({ content, stable });
+	}
+	return out;
+}
+
+/**
+ * Resolve the conversation handle id from a `providerOptions` payload.
+ * The runtime stuffs it under `providerOptions.eliza.conversationId` when
+ * the calling context represents a long-lived conversation (chat handler,
+ * planner loop). When present, local backends should use it as the
+ * primary slot key — it's stable across turns regardless of prompt
+ * content drift, which gives the strongest possible cache reuse for
+ * agentic loops.
+ */
+export function extractConversationId(providerOptions: unknown): string | null {
+	if (!providerOptions || typeof providerOptions !== "object") return null;
+	const eliza = (providerOptions as Record<string, unknown>).eliza;
+	if (!eliza || typeof eliza !== "object") return null;
+	const raw = (eliza as Record<string, unknown>).conversationId;
+	if (typeof raw !== "string" || raw.length === 0) return null;
+	return raw;
+}
+
+/**
+ * Resolve the stable per-call cache key for the local backends. Order of
+ * precedence:
+ *   1. Conversation id — strongest signal, identical across turns.
+ *   2. Annotated stable-prefix hash — survives unstable-tail drift.
+ *   3. `prefixHash` from the runtime cache plan — already stable-only via
+ *      `cachePrefixSegments` upstream.
+ *   4. `promptCacheKey` (`v5:<prefixHash>`) — back-compat fallback.
+ * Returns null when none are available.
+ */
+export function resolveLocalCacheKey(providerOptions: unknown): string | null {
+	const conversationId = extractConversationId(providerOptions);
+	if (conversationId) return `conv:${conversationId}`;
+	const segments = extractAnnotatedSegments(providerOptions);
+	if (segments) {
+		const hashed = hashStablePrefix(segments);
+		if (hashed) return `seg:${hashed}`;
+	}
+	const prefixHash = extractPrefixHash(providerOptions);
+	if (prefixHash) return `pfx:${prefixHash}`;
+	return extractPromptCacheKey(providerOptions);
+}

package/src/services/catalog.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Local inference catalog re-exports.
+ *
+ * The canonical catalog (Eliza-1 tier ids, default-eligibility set,
+ * `MODEL_CATALOG`, HuggingFace URL builders) lives in
+ * `@elizaos/shared/local-inference`. This shim preserves the historical
+ * import path `./catalog` for server-side code.
+ */
+export { buildHuggingFaceResolveUrl, buildHuggingFaceResolveUrlForPath, DEFAULT_ELIGIBLE_MODEL_IDS, ELIZA_1_HF_REPO, ELIZA_1_MTP_TIER_IDS, ELIZA_1_PLACEHOLDER_IDS, ELIZA_1_RELEASE_TIER_IDS, ELIZA_1_TIER_IDS, ELIZA_1_TIER_PUBLISH_STATUS, ELIZA_1_VISION_TIER_IDS, type Eliza1TierId, eliza1TierPublishStatus, FIRST_RUN_DEFAULT_MODEL_ID, findCatalogModel, isDefaultEligibleId, MODEL_CATALOG, } from "@elizaos/shared";
+//# sourceMappingURL=catalog.d.ts.map

package/src/services/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACN,0BAA0B,EAC1B,iCAAiC,EACjC,0BAA0B,EAC1B,eAAe,EACf,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,gBAAgB,EAChB,2BAA2B,EAC3B,uBAAuB,EACvB,KAAK,YAAY,EACjB,uBAAuB,EACvB,0BAA0B,EAC1B,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,GACb,MAAM,iBAAiB,CAAC"}

package/src/services/catalog.test.ts

@@ -0,0 +1,238 @@
+import { describe, expect, it } from "vitest";
+import {
+	buildHuggingFaceResolveUrl,
+	DEFAULT_ELIGIBLE_MODEL_IDS,
+	ELIZA_1_MTP_TIER_IDS,
+	ELIZA_1_TIER_IDS,
+	FIRST_RUN_DEFAULT_MODEL_ID,
+	findCatalogModel,
+	MODEL_CATALOG,
+} from "./catalog";
+import { recommendForFirstRun } from "./recommendation";
+import { localInferenceService } from "./service";
+
+describe("local inference catalog", () => {
+	it("ships exactly the visible Eliza-1 tiers", () => {
+		const visible = MODEL_CATALOG.filter((m) => !m.hiddenFromCatalog);
+		expect(visible.map((m) => m.id).sort()).toEqual(
+			[...ELIZA_1_TIER_IDS].sort(),
+		);
+	});
+
+	it("marks ONLY the Eliza-1 tiers as default-eligible", () => {
+		expect([...DEFAULT_ELIGIBLE_MODEL_IDS].sort()).toEqual(
+			[...ELIZA_1_TIER_IDS].sort(),
+		);
+		for (const id of ELIZA_1_TIER_IDS) {
+			expect(DEFAULT_ELIGIBLE_MODEL_IDS.has(id), `${id} not eligible`).toBe(
+				true,
+			);
+		}
+		for (const model of MODEL_CATALOG.filter((m) => !m.hiddenFromCatalog)) {
+			expect(model.id.startsWith("eliza-1-")).toBe(true);
+		}
+	});
+
+	it("uses eliza-1 size ids as user-facing display names", () => {
+		for (const id of ELIZA_1_TIER_IDS) {
+			const model = findCatalogModel(id);
+			expect(model, `${id} missing`).toBeTruthy();
+			expect(model?.displayName).toMatch(/^(?:Eliza-1\b|eliza-1-)/);
+			expect(model?.blurb).toMatch(/^(?:Eliza-1\b|eliza-1-)/);
+			expect(`${model?.displayName} ${model?.blurb}`).not.toMatch(
+				/\b(?:Qwen|Llama)\b/i,
+			);
+		}
+	});
+
+	it("uses the single elizaOS HuggingFace repo for every visible Eliza-1 tier", () => {
+		for (const model of MODEL_CATALOG.filter((m) => !m.hiddenFromCatalog)) {
+			const tier = model.id.slice("eliza-1-".length);
+			expect(model.hfRepo).toBe("elizaos/eliza-1");
+			expect(model.hfPathPrefix).toBe(`bundles/${tier}`);
+			expect(buildHuggingFaceResolveUrl(model)).toContain(
+				`/elizaos/eliza-1/resolve/main/bundles/${tier}/`,
+			);
+		}
+	});
+
+	it("does not expose hidden companion entries in the hub", () => {
+		const visible = localInferenceService.getCatalog();
+		const visibleIds = new Set(visible.map((model) => model.id));
+		const hiddenCompanionIds = MODEL_CATALOG.filter(
+			(model) => model.hiddenFromCatalog,
+		).map((model) => model.id);
+		expect(hiddenCompanionIds.filter((id) => visibleIds.has(id))).toEqual([]);
+		expect(visible.flatMap((model) => model.companionModelIds ?? [])).toEqual(
+			[],
+		);
+	});
+
+	it("keeps the visible model hub focused on Eliza-1 only", () => {
+		const visible = localInferenceService.getCatalog();
+		expect(visible.map((model) => model.id).sort()).toEqual(
+			[...ELIZA_1_TIER_IDS].sort(),
+		);
+		expect(
+			visible.filter((model) => DEFAULT_ELIGIBLE_MODEL_IDS.has(model.id))
+				.length,
+		).toBe(visible.length);
+	});
+
+	it("declares contextLength on every entry whose blurb claims a long window", () => {
+		const longContextRegex =
+			/\b(?:128k|256k|long.*context|long-context|128 ?k tokens?)\b/i;
+		const offenders: string[] = [];
+		for (const model of MODEL_CATALOG) {
+			if (!longContextRegex.test(model.blurb)) continue;
+			if (
+				typeof model.contextLength !== "number" ||
+				model.contextLength < 65536
+			) {
+				offenders.push(
+					`${model.id} claims long context in blurb but contextLength=${String(model.contextLength)}`,
+				);
+			}
+		}
+		expect(offenders).toEqual([]);
+	});
+
+	it("sets contextLength on every Eliza-1 tier per the tier matrix", () => {
+		const expected: Record<string, number> = {
+			"eliza-1-2b": 131072,
+			"eliza-1-4b": 131072,
+			"eliza-1-9b": 131072,
+			"eliza-1-27b": 131072,
+			"eliza-1-27b-256k": 262144,
+		};
+		for (const [id, expectedLength] of Object.entries(expected)) {
+			const model = findCatalogModel(id);
+			expect(model, `${id} missing from catalog`).toBeTruthy();
+			expect(model?.contextLength, `${id} contextLength mismatch`).toBe(
+				expectedLength,
+			);
+		}
+	});
+
+	it("sets a tokenizerFamily on every chat/code/reasoning entry", () => {
+		const offenders: string[] = [];
+		for (const model of MODEL_CATALOG) {
+			if (!model.tokenizerFamily) {
+				offenders.push(model.id);
+			}
+		}
+		expect(offenders).toEqual([]);
+	});
+
+	it("declares native MTP on every Eliza-1 tier", () => {
+		for (const id of ELIZA_1_MTP_TIER_IDS) {
+			const model = findCatalogModel(id);
+			expect(model?.runtime?.mtp?.specType, `${id} mtp`).toBe("draft-mtp");
+			expect(model?.companionModelIds, `${id} companions`).toBeUndefined();
+		}
+	});
+
+	it("declares the mandatory local runtime contract for every default tier", () => {
+		const baseKernels = ["turbo3", "turbo4", "qjl_full", "polarquant"];
+		for (const id of ELIZA_1_TIER_IDS) {
+			const model = findCatalogModel(id);
+			expect(model?.runtime?.preferredBackend, `${id} backend`).toBe(
+				"llama-cpp",
+			);
+			for (const kernel of baseKernels) {
+				expect(
+					model?.runtime?.optimizations?.requiresKernel,
+					`${id} kernel ${kernel}`,
+				).toContain(kernel);
+			}
+			expect(model?.runtime?.mtp?.specType, `${id} mtp`).toBe("draft-mtp");
+			expect(model?.companionModelIds, `${id} companions`).toBeUndefined();
+			if ((model?.contextLength ?? 0) >= 65536) {
+				expect(model?.runtime?.optimizations?.requiresKernel).toContain(
+					"turbo3_tcq",
+				);
+			}
+			expect(model?.runtime?.optimizations?.requiresKernel).not.toContain(
+				"openvino",
+			);
+		}
+	});
+
+	it("does not publish external speculative drafter companions", () => {
+		const drafters = MODEL_CATALOG.filter((m) => m.companionModelIds?.length);
+		expect(drafters).toEqual([]);
+	});
+
+	it("declares the text quantization matrix and voice boundary by tier", () => {
+		for (const id of ELIZA_1_TIER_IDS) {
+			const model = findCatalogModel(id);
+			expect(model?.quantization?.defaultVariantId).toBe("q4_k_m");
+			expect(model?.quantization?.variants.map((v) => v.id)).toEqual([
+				"q3_k_m",
+				"q4_k_m",
+				"q5_k_m",
+				"q6_k",
+				"q8_0",
+			]);
+		}
+
+		// Mobile-class tiers (2b/4b) ship Kokoro only — it is smaller +
+		// faster and is the exclusive mobile TTS. 9B keeps OmniVoice first with
+		// Kokoro bundled; large tiers are OmniVoice-only.
+		// See catalog.ts ELIZA_1_VOICE_BACKENDS for the policy rationale.
+		expect(findCatalogModel("eliza-1-2b")?.voiceBackends).toEqual(["kokoro"]);
+		expect(findCatalogModel("eliza-1-4b")?.voiceBackends).toEqual(["kokoro"]);
+		expect(findCatalogModel("eliza-1-9b")?.voiceBackends).toEqual([
+			"omnivoice",
+			"kokoro",
+		]);
+		expect(findCatalogModel("eliza-1-27b")?.voiceBackends).toEqual([
+			"omnivoice",
+		]);
+		expect(findCatalogModel("eliza-1-27b-256k")?.voiceBackends).toEqual([
+			"omnivoice",
+		]);
+	});
+
+	it("does not leak implementation-family names in visible catalog copy", () => {
+		const banned = /\b(?:qwen|llama|turboquant|qjl|polarquant)\b/i;
+		for (const model of MODEL_CATALOG.filter((m) => !m.hiddenFromCatalog)) {
+			expect(model.displayName).not.toMatch(banned);
+			expect(model.quant).not.toMatch(banned);
+			expect(model.blurb).not.toMatch(banned);
+		}
+	});
+
+	it("does not ship non-Eliza local model entries", () => {
+		const offenders: string[] = [];
+		for (const model of MODEL_CATALOG) {
+			if (!model.id.startsWith("eliza-1-")) {
+				offenders.push(model.id);
+			}
+		}
+		expect(offenders).toEqual([]);
+	});
+
+	it("keeps external HF search-shaped ids custom-only", () => {
+		const externalId = "hf:some-org/custom-model::model.Q4_K_M.gguf";
+		expect(DEFAULT_ELIGIBLE_MODEL_IDS.has(externalId)).toBe(false);
+		expect(externalId.startsWith("eliza-1-")).toBe(false);
+	});
+
+	it("FIRST_RUN_DEFAULT_MODEL_ID resolves to a default-eligible Eliza-1 tier", () => {
+		const defaultModel = findCatalogModel(FIRST_RUN_DEFAULT_MODEL_ID);
+		expect(defaultModel, `${FIRST_RUN_DEFAULT_MODEL_ID} missing`).toBeTruthy();
+		expect(DEFAULT_ELIGIBLE_MODEL_IDS.has(FIRST_RUN_DEFAULT_MODEL_ID)).toBe(
+			true,
+		);
+	});
+
+	it("recommendForFirstRun resolves to a default-eligible Eliza-1 tier", () => {
+		const picked = recommendForFirstRun();
+		expect(picked).not.toBeNull();
+		if (!picked) throw new Error("missing first-run recommendation");
+		expect(picked.id).toBe(FIRST_RUN_DEFAULT_MODEL_ID);
+		expect(DEFAULT_ELIGIBLE_MODEL_IDS.has(picked.id)).toBe(true);
+		expect(picked.displayName).toMatch(/^(?:Eliza-1\b|eliza-1-)/);
+	});
+});

package/src/services/catalog.ts

@@ -0,0 +1,27 @@
+/**
+ * Local inference catalog re-exports.
+ *
+ * The canonical catalog (Eliza-1 tier ids, default-eligibility set,
+ * `MODEL_CATALOG`, HuggingFace URL builders) lives in
+ * `@elizaos/shared/local-inference`. This shim preserves the historical
+ * import path `./catalog` for server-side code.
+ */
+
+export {
+	buildHuggingFaceResolveUrl,
+	buildHuggingFaceResolveUrlForPath,
+	DEFAULT_ELIGIBLE_MODEL_IDS,
+	ELIZA_1_HF_REPO,
+	ELIZA_1_MTP_TIER_IDS,
+	ELIZA_1_PLACEHOLDER_IDS,
+	ELIZA_1_RELEASE_TIER_IDS,
+	ELIZA_1_TIER_IDS,
+	ELIZA_1_TIER_PUBLISH_STATUS,
+	ELIZA_1_VISION_TIER_IDS,
+	type Eliza1TierId,
+	eliza1TierPublishStatus,
+	FIRST_RUN_DEFAULT_MODEL_ID,
+	findCatalogModel,
+	isDefaultEligibleId,
+	MODEL_CATALOG,
+} from "@elizaos/shared";