@elizaos/ui 2.0.0-beta.1 → 2.0.3-beta.2

package/services/local-inference/readiness.js

@@ -0,0 +1,153 @@
+import { MODEL_CATALOG } from "./catalog.js";
+import { catalogDownloadSizeBytes } from "./recommendation.js";
+const TERMINAL_STATES = new Set([
+    "completed",
+    "failed",
+    "cancelled",
+]);
+function catalogById(catalog) {
+    return new Map(catalog.map((model) => [model.id, model]));
+}
+function installedById(installed) {
+    return new Map(installed.map((model) => [model.id, model]));
+}
+function latestJobByModel(downloads) {
+    const jobs = new Map();
+    for (const job of downloads) {
+        const current = jobs.get(job.modelId);
+        if (!current || job.updatedAt.localeCompare(current.updatedAt) > 0) {
+            jobs.set(job.modelId, job);
+        }
+    }
+    return jobs;
+}
+function requiredModelIds(assignedModelId, catalog) {
+    const model = catalog.get(assignedModelId);
+    return model ? [assignedModelId] : [assignedModelId];
+}
+function statusFromJobs(jobs, missingModelIds) {
+    const activeJobs = jobs.filter((job) => job.state === "queued" || job.state === "downloading");
+    const terminalJobs = jobs.filter((job) => TERMINAL_STATES.has(job.state));
+    const relevantJobs = activeJobs.length > 0 ? activeJobs : terminalJobs;
+    const state = relevantJobs.find((job) => job.state === "failed")?.state ??
+        relevantJobs.find((job) => job.state === "cancelled")?.state ??
+        relevantJobs.find((job) => job.state === "downloading")?.state ??
+        relevantJobs.find((job) => job.state === "queued")?.state ??
+        relevantJobs.find((job) => job.state === "completed")?.state ??
+        (missingModelIds.length > 0 ? "missing" : "completed");
+    const receivedBytes = relevantJobs.reduce((total, job) => total + job.received, 0);
+    const totalBytes = relevantJobs.reduce((total, job) => total + job.total, 0);
+    const bytesPerSec = activeJobs.reduce((total, job) => total + job.bytesPerSec, 0);
+    const etaValues = activeJobs
+        .map((job) => job.etaMs)
+        .filter((etaMs) => etaMs !== null);
+    const etaMs = etaValues.length > 0
+        ? Math.max(...etaValues)
+        : (relevantJobs[0]?.etaMs ?? null);
+    const updatedAt = relevantJobs
+        .map((job) => job.updatedAt)
+        .sort((left, right) => right.localeCompare(left))[0] ?? null;
+    const errors = relevantJobs.flatMap((job) => (job.error ? [job.error] : []));
+    return {
+        state,
+        receivedBytes,
+        totalBytes,
+        percent: totalBytes > 0
+            ? Math.max(0, Math.min(100, Math.round((receivedBytes / totalBytes) * 1000) / 10))
+            : null,
+        bytesPerSec,
+        etaMs,
+        updatedAt,
+        errors,
+    };
+}
+function slotReadiness(slot, assignments, installed, catalog, catalogList, downloads, active) {
+    const assignedModelId = assignments[slot] ?? null;
+    if (!assignedModelId) {
+        return {
+            slot,
+            assigned: false,
+            assignedModelId: null,
+            displayName: null,
+            primaryDownloaded: false,
+            downloaded: false,
+            active: false,
+            ready: false,
+            state: "unassigned",
+            requiredModelIds: [],
+            missingModelIds: [],
+            installedBytes: 0,
+            expectedBytes: 0,
+            download: {
+                state: "missing",
+                receivedBytes: 0,
+                totalBytes: 0,
+                percent: null,
+                bytesPerSec: 0,
+                etaMs: null,
+                updatedAt: null,
+                errors: [],
+            },
+            errors: [],
+        };
+    }
+    const ids = requiredModelIds(assignedModelId, catalog);
+    const missingModelIds = ids.filter((id) => !installed.has(id));
+    const primaryDownloaded = installed.has(assignedModelId);
+    const downloaded = missingModelIds.length === 0;
+    const activeReady = active.modelId === assignedModelId && active.status === "ready";
+    const model = catalog.get(assignedModelId);
+    const jobs = ids.flatMap((id) => {
+        const job = downloads.get(id);
+        return job ? [job] : [];
+    });
+    const download = statusFromJobs(jobs, missingModelIds);
+    const activeError = active.modelId === assignedModelId &&
+        active.status === "error" &&
+        active.error
+        ? [active.error]
+        : [];
+    const errors = [...download.errors, ...activeError];
+    const hasActiveJob = jobs.some((job) => job.state === "queued" || job.state === "downloading");
+    const terminalFailure = jobs.find((job) => job.state === "failed" || job.state === "cancelled");
+    return {
+        slot,
+        assigned: true,
+        assignedModelId,
+        displayName: model?.displayName ?? installed.get(assignedModelId)?.displayName ?? null,
+        primaryDownloaded,
+        downloaded,
+        active: activeReady,
+        ready: downloaded && activeReady,
+        state: terminalFailure
+            ? terminalFailure.state === "failed"
+                ? "failed"
+                : "cancelled"
+            : hasActiveJob
+                ? "downloading"
+                : activeReady
+                    ? "active"
+                    : downloaded
+                        ? "downloaded"
+                        : "missing",
+        requiredModelIds: ids,
+        missingModelIds,
+        installedBytes: ids.reduce((total, id) => total + (installed.get(id)?.sizeBytes ?? 0), 0),
+        expectedBytes: model ? catalogDownloadSizeBytes(model, catalogList) : 0,
+        download,
+        errors,
+    };
+}
+export function buildTextGenerationReadiness(input) {
+    const catalogList = input.catalog ?? MODEL_CATALOG;
+    const catalog = catalogById(catalogList);
+    const installed = installedById(input.installed);
+    const downloads = latestJobByModel(input.downloads);
+    return {
+        updatedAt: new Date().toISOString(),
+        slots: {
+            TEXT_SMALL: slotReadiness("TEXT_SMALL", input.assignments, installed, catalog, catalogList, downloads, input.active),
+            TEXT_LARGE: slotReadiness("TEXT_LARGE", input.assignments, installed, catalog, catalogList, downloads, input.active),
+        },
+    };
+}

package/services/local-inference/recommendation.d.ts

@@ -0,0 +1,49 @@
+import type { CatalogModel, HardwareFitLevel, HardwareProbe, TextGenerationSlot } from "./types";
+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[];
+}
+export declare function classifyRecommendationPlatform(hardware: HardwareProbe): RecommendationPlatformClass;
+export declare function catalogDownloadSizeGb(model: CatalogModel, catalog?: CatalogModel[]): number;
+export declare function catalogDownloadSizeBytes(model: CatalogModel, catalog?: CatalogModel[]): number;
+export declare function assessCatalogModelFit(hardware: HardwareProbe, model: CatalogModel, catalog?: CatalogModel[]): HardwareFitLevel;
+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;
+}
+export declare function selectRecommendedModelForSlot(slot: TextGenerationSlot, hardware: HardwareProbe, catalog?: CatalogModel[], options?: RecommendationOptions): RecommendedModelSelection;
+export declare function selectRecommendedModels(hardware: HardwareProbe, catalog?: CatalogModel[], options?: RecommendationOptions): Record<TextGenerationSlot, RecommendedModelSelection>;
+/**
+ * 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 (mirrors `app-core` recommendation.ts):
+ *   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's HF bundle isn't published
+ *      yet (elizaOS/eliza#7629).
+ *   3. If every default-eligible tier is pending, last-resort to ANY
+ *      default-eligible tier so the download path surfaces the 404
+ *      cleanly rather than silently picking a 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 declare function recommendForFirstRun(catalog?: CatalogModel[]): CatalogModel | null;
+export declare function chooseSmallerFallbackModel(currentModelId: string, hardware: HardwareProbe, slot?: TextGenerationSlot, catalog?: CatalogModel[]): CatalogModel | null;
+//# sourceMappingURL=recommendation.d.ts.map

package/services/local-inference/recommendation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendation.d.ts","sourceRoot":"","sources":["../../../../../../src/services/local-inference/recommendation.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAEjB,MAAM,MAAM,2BAA2B,GACnC,QAAQ,GACR,eAAe,GACf,WAAW,GACX,WAAW,GACX,aAAa,GACb,aAAa,CAAC;AAElB,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,kBAAkB,CAAC;IACzB,aAAa,EAAE,2BAA2B,CAAC;IAC3C,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IAC3B,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,YAAY,EAAE,CAAC;CAC9B;AA0DD,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,aAAa,GACtB,2BAA2B,CAQ7B;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,YAAY,EAAkB,GACtC,MAAM,CAGR;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,YAAY,EAAkB,GACtC,MAAM,CAER;AAcD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,aAAa,EACvB,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,YAAY,EAAkB,GACtC,gBAAgB,CASlB;AAuGD,MAAM,WAAW,qBAAqB;IACpC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CACzD;AAED,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,kBAAkB,EACxB,QAAQ,EAAE,aAAa,EACvB,OAAO,GAAE,YAAY,EAAkB,EACvC,OAAO,GAAE,qBAA0B,GAClC,yBAAyB,CAuC3B;AAkBD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,aAAa,EACvB,OAAO,GAAE,YAAY,EAAkB,EACvC,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAAC,kBAAkB,EAAE,yBAAyB,CAAC,CAevD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,YAAY,EAAkB,GACtC,YAAY,GAAG,IAAI,CAkBrB;AAED,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,aAAa,EACvB,IAAI,GAAE,kBAAiC,EACvC,OAAO,GAAE,YAAY,EAAkB,GACtC,YAAY,GAAG,IAAI,CAuBrB"}

package/services/local-inference/recommendation.js

@@ -0,0 +1,271 @@
+import { DEFAULT_ELIGIBLE_MODEL_IDS, eliza1TierPublishStatus, FIRST_RUN_DEFAULT_MODEL_ID, MODEL_CATALOG, } from "./catalog.js";
+import { assessFit } from "./hardware.js";
+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 TIER_2B = "eliza-1-2b";
+const TIER_4B = "eliza-1-4b";
+const TIER_9B = "eliza-1-9b";
+const TIER_27B = "eliza-1-27b";
+const SLOT_LADDERS = {
+    // 4B is the shipped mobile minimum — the 2B entry tier is too small for a
+    // quality chat experience, so the mobile ladder floors at 4B for both slots.
+    // If a low-RAM phone genuinely can't fit 4B, `fallbackCandidates` still
+    // degrades to the 2B entry tier rather than failing outright.
+    mobile: {
+        TEXT_SMALL: [TIER_4B],
+        TEXT_LARGE: [TIER_4B],
+    },
+    "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) {
+    return new Map(catalog.map((model) => [model.id, model]));
+}
+function chatCandidates(catalog) {
+    return catalog.filter((model) => !model.hiddenFromCatalog);
+}
+export function classifyRecommendationPlatform(hardware) {
+    const platform = hardware.mobile?.platform ?? hardware.platform;
+    if (platform === "android" || platform === "ios")
+        return "mobile";
+    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, catalog = MODEL_CATALOG) {
+    void catalog;
+    return model.sizeGb;
+}
+export function catalogDownloadSizeBytes(model, catalog = MODEL_CATALOG) {
+    return Math.round(catalogDownloadSizeGb(model, catalog) * BYTES_PER_GB);
+}
+function mobileFit(hardware, model, catalog) {
+    const sizeGb = catalogDownloadSizeGb(model, catalog);
+    if (hardware.totalRamGb < model.minRamGb)
+        return "wontfit";
+    if (sizeGb > hardware.totalRamGb * 0.8)
+        return "wontfit";
+    if (sizeGb > hardware.totalRamGb * 0.65)
+        return "tight";
+    return "fits";
+}
+export function assessCatalogModelFit(hardware, model, catalog = MODEL_CATALOG) {
+    if (classifyRecommendationPlatform(hardware) === "mobile") {
+        return mobileFit(hardware, model, catalog);
+    }
+    return assessFit(hardware, catalogDownloadSizeGb(model, catalog), model.minRamGb);
+}
+function canFit(hardware, model, catalog) {
+    return assessCatalogModelFit(hardware, model, catalog) !== "wontfit";
+}
+/**
+ * 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, binaryKernels) {
+    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, catalog) {
+    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) {
+    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) {
+    return (typeof model.contextLength === "number" &&
+        model.contextLength >= LONG_CONTEXT_MIN_LENGTH);
+}
+function fallbackCandidates(slot, hardware, catalog) {
+    const candidates = chatCandidates(catalog).filter((model) => DEFAULT_ELIGIBLE_MODEL_IDS.has(model.id) &&
+        canFit(hardware, model, catalog));
+    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 function selectRecommendedModelForSlot(slot, hardware, catalog = MODEL_CATALOG, options = {}) {
+    const platformClass = classifyRecommendationPlatform(hardware);
+    const ladder = modelsFromLadder(SLOT_LADDERS[platformClass][slot], catalog);
+    const binaryKernels = options.binaryKernels ?? null;
+    const eligible = ladder.filter((model) => canFit(hardware, model, catalog) &&
+        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).filter((model) => kernelRequirementsSatisfied(model, binaryKernels));
+    const model = alternatives[0] ?? null;
+    const fit = model ? assessCatalogModelFit(hardware, model, catalog) : 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) {
+    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);
+}
+export function selectRecommendedModels(hardware, catalog = MODEL_CATALOG, options = {}) {
+    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 (mirrors `app-core` recommendation.ts):
+ *   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's HF bundle isn't published
+ *      yet (elizaOS/eliza#7629).
+ *   3. If every default-eligible tier is pending, last-resort to ANY
+ *      default-eligible tier so the download path surfaces the 404
+ *      cleanly rather than silently picking a 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 = MODEL_CATALOG) {
+    const byId = catalogById(catalog);
+    const isEligibleChat = (model) => !model.hiddenFromCatalog && DEFAULT_ELIGIBLE_MODEL_IDS.has(model.id);
+    const publishStatusFor = (model) => model.publishStatus ?? eliza1TierPublishStatus(model.id);
+    const isPublishedEligibleChat = (model) => isEligibleChat(model) && publishStatusFor(model) === "published";
+    const preferred = byId.get(FIRST_RUN_DEFAULT_MODEL_ID);
+    if (preferred && isPublishedEligibleChat(preferred))
+        return preferred;
+    const fallbackPublished = catalog.find(isPublishedEligibleChat);
+    if (fallbackPublished)
+        return fallbackPublished;
+    // Last-resort: prefer the configured first-run default even when its
+    // bundle is unpublished, so the downloader's 404 surfaces with the
+    // tier the user expected to land on.
+    if (preferred && isEligibleChat(preferred))
+        return preferred;
+    return catalog.find(isEligibleChat) ?? null;
+}
+export function chooseSmallerFallbackModel(currentModelId, hardware, slot = "TEXT_LARGE", catalog = MODEL_CATALOG) {
+    const byId = catalogById(catalog);
+    const current = byId.get(currentModelId);
+    const currentSize = current
+        ? catalogDownloadSizeGb(current, catalog)
+        : Number.POSITIVE_INFINITY;
+    const platformClass = classifyRecommendationPlatform(hardware);
+    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))[0];
+    if (ladderFallback)
+        return ladderFallback;
+    return (fallbackCandidates(slot, hardware, catalog)
+        .filter((model) => model.id !== currentModelId)
+        .filter((model) => catalogDownloadSizeGb(model, catalog) < currentSize)[0] ?? null);
+}

package/services/local-inference/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../../../../src/services/local-inference/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAmC9C;;;;GAIG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAerE;AAED,wEAAwE;AACxE,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB3E;AAED,gEAAgE;AAChE,wBAAsB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM/D;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,GAAG,WAAW,CAAC;CACnC,CAAC,CA6BD"}

package/services/local-inference/registry.js

@@ -0,0 +1,118 @@
+/**
+ * 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 fs from "node:fs/promises";
+import path from "node:path";
+import { scanExternalModels } from "./external-scanner.js";
+import { isWithinElizaRoot, localInferenceRoot, registryPath } from "./paths.js";
+async function ensureRootDir() {
+    await fs.mkdir(localInferenceRoot(), { recursive: true });
+}
+async function readElizaOwned() {
+    try {
+        const raw = await fs.readFile(registryPath(), "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed?.version !== 1 || !Array.isArray(parsed.models)) {
+            return [];
+        }
+        return parsed.models.filter((m) => m && typeof m === "object" && m.source === "eliza-download");
+    }
+    catch {
+        return [];
+    }
+}
+async function writeElizaOwned(models) {
+    await ensureRootDir();
+    const tmp = `${registryPath()}.tmp`;
+    const payload = { version: 1, models };
+    await fs.writeFile(tmp, JSON.stringify(payload, null, 2), "utf8");
+    await fs.rename(tmp, registryPath());
+}
+/**
+ * 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 async function listInstalledModels() {
+    const [ownedRaw, external] = await Promise.all([
+        readElizaOwned(),
+        scanExternalModels(),
+    ]);
+    const owned = ownedRaw;
+    // Filter out Eliza-owned files that also survived a reboot of the local
+    // file and got re-detected by the scanner.
+    const ownedPaths = new Set(owned.map((m) => path.resolve(m.path)));
+    const dedupedExternal = external.filter((m) => !ownedPaths.has(path.resolve(m.path)));
+    return [...owned, ...dedupedExternal];
+}
+/** Add or update a Eliza-owned entry. External entries are rejected. */
+export async function upsertElizaModel(model) {
+    if (model.source !== "eliza-download") {
+        throw new Error("[local-inference] registry only accepts Eliza-owned models");
+    }
+    if (!isWithinElizaRoot(model.path)) {
+        throw new Error("[local-inference] Eliza-owned models must live under the local-inference root");
+    }
+    if (model.bundleRoot && !isWithinElizaRoot(model.bundleRoot)) {
+        throw new Error("[local-inference] Eliza-owned bundle roots must live under the local-inference root");
+    }
+    if (model.manifestPath && !isWithinElizaRoot(model.manifestPath)) {
+        throw new Error("[local-inference] Eliza-owned manifests must live under the local-inference root");
+    }
+    const owned = await readElizaOwned();
+    const withoutCurrent = owned.filter((m) => m.id !== model.id);
+    withoutCurrent.push(model);
+    await writeElizaOwned(withoutCurrent);
+}
+/** Mark an existing Eliza-owned model as most-recently-used. */
+export async function touchElizaModel(id) {
+    const owned = await readElizaOwned();
+    const target = owned.find((m) => m.id === id);
+    if (!target)
+        return;
+    target.lastUsedAt = new Date().toISOString();
+    await writeElizaOwned(owned);
+}
+/**
+ * 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 async function removeElizaModel(id) {
+    const owned = await readElizaOwned();
+    const target = owned.find((m) => m.id === id);
+    if (!target) {
+        // Check whether it's a known external entry so we can return a
+        // helpful error message instead of 404.
+        const external = await scanExternalModels();
+        if (external.some((m) => m.id === id)) {
+            return { removed: false, reason: "external" };
+        }
+        return { removed: false, reason: "not-found" };
+    }
+    if (!isWithinElizaRoot(target.path)) {
+        return { removed: false, reason: "external" };
+    }
+    const removePath = target.bundleRoot && isWithinElizaRoot(target.bundleRoot)
+        ? target.bundleRoot
+        : target.path;
+    try {
+        await fs.rm(removePath, { recursive: true, force: true });
+    }
+    catch {
+        // If the file was already gone we still want to clear the registry entry.
+    }
+    await writeElizaOwned(owned.filter((m) => m.id !== id));
+    return { removed: true };
+}

package/services/local-inference/resource-snapshot-bridge.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Device resource-snapshot bridge.
+ *
+ * Calls the native resource probe — `ElizaIntent.getResourceSnapshot()` on iOS,
+ * `ResourceProbe.getResourceSnapshot()` on Android — and normalises the raw
+ * Capacitor payload into a typed `DeviceResourceSnapshot` for the Mobile
+ * Resource Workbench (issue #8800).
+ *
+ * The native side returns JSON `null` (iOS `NSNull()` / Android
+ * `JSONObject.NULL`) for any quantity the OS cannot measure, so the normaliser
+ * coerces every numeric field through a strict finite-number check and reports
+ * `null` otherwise — never a fabricated zero (AGENTS.md §3/§7).
+ *
+ * Only `normalizeResourceSnapshot` is pure/unit-tested; `getDeviceResourceSnapshot`
+ * is the thin native call.
+ */
+export type SnapshotThermalState = "nominal" | "fair" | "serious" | "critical" | "unknown";
+export interface DeviceResourceSnapshot {
+    platform: "ios" | "android" | null;
+    thermalState: SnapshotThermalState;
+    lowPowerMode: boolean | null;
+    /** Process resident footprint in MB (iOS phys_footprint / Android total PSS). */
+    residentMemoryMb: number | null;
+    /** Device-wide available RAM in MB before memory pressure. */
+    availableRamMb: number | null;
+    /** Cumulative process CPU time in ms. */
+    cpuTimeMs: number | null;
+    batteryLevelPct: number | null;
+    /** Cumulative charge counter in µAh (Android only). */
+    batteryChargeMicroAmpHours: number | null;
+    /** Instantaneous current draw in µA (Android only). */
+    batteryCurrentMicroAmps: number | null;
+    isCharging: boolean | null;
+    /** Sample timestamp in ms (epoch). */
+    capturedAtMs: number;
+}
+/**
+ * Normalise a raw native resource-snapshot payload into a typed snapshot.
+ * Pure — coerces every field and substitutes `null` for anything missing or
+ * non-finite. `capturedAtMs` falls back to the supplied `nowMs` when the native
+ * side did not stamp it.
+ */
+export declare function normalizeResourceSnapshot(raw: unknown, nowMs: number): DeviceResourceSnapshot;
+/**
+ * Read a live resource snapshot from the native probe, or `null` when no native
+ * probe is reachable (web / desktop / unregistered plugin). Never throws — a
+ * probe failure resolves to `null` so the caller treats it as "not available on
+ * this platform" rather than a hard error.
+ */
+export declare function getDeviceResourceSnapshot(nowMs?: number): Promise<DeviceResourceSnapshot | null>;
+//# sourceMappingURL=resource-snapshot-bridge.d.ts.map

package/services/local-inference/resource-snapshot-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-snapshot-bridge.d.ts","sourceRoot":"","sources":["../../../../../../src/services/local-inference/resource-snapshot-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,MAAM,MAAM,oBAAoB,GAC5B,SAAS,GACT,MAAM,GACN,SAAS,GACT,UAAU,GACV,SAAS,CAAC;AAUd,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,KAAK,GAAG,SAAS,GAAG,IAAI,CAAC;IACnC,YAAY,EAAE,oBAAoB,CAAC;IACnC,YAAY,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,iFAAiF;IACjF,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,8DAA8D;IAC9D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,yCAAyC;IACzC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,uDAAuD;IACvD,0BAA0B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,uDAAuD;IACvD,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,UAAU,EAAE,OAAO,GAAG,IAAI,CAAC;IAC3B,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC;CACtB;AAqBD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,MAAM,GACZ,sBAAsB,CAoBxB;AAUD;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,GAAE,MAAmB,GACzB,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAWxC"}