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

package/src/services/router-handler.ts

@@ -0,0 +1,407 @@
+/**
+ * Top-priority router handler.
+ *
+ * Registers a model handler for every `AgentModelSlot` at priority
+ * `Number.MAX_SAFE_INTEGER`, which guarantees the runtime dispatches to
+ * us first. At dispatch time we:
+ *
+ *   1. Read the user's per-slot policy + preferred-provider choice from
+ *      `routing-preferences.ts`.
+ *   2. Ask the `policyEngine` to pick a provider from the handler
+ *      registry's current set (excluding ourselves).
+ *   3. Invoke that provider's original handler directly — bypassing
+ *      `runtime.useModel` which would recurse into us.
+ *   4. Record the observed latency so later "fastest" picks have data.
+ *   5. On handler failure: retry the next eligible provider in priority
+ *      order until exhausted (except in `manual` mode with an explicit
+ *      preferred provider — that throws verbatim).
+ *
+ * If no other handler exists we throw a clear error rather than return
+ * garbage — the caller is meant to see "no provider configured" so they
+ * know to set one up.
+ *
+ * Because the router sits at the top of the priority stack, the user's
+ * preference is always authoritative regardless of what plugins register
+ * at lower priorities. This is the mechanism that unifies cloud + local
+ * + device-bridge routing from one settings panel.
+ *
+ * ## TTS routing precedence (`TEXT_TO_SPEECH` slot)
+ *
+ * The default per-slot policy is `prefer-local` (see
+ * `DEFAULT_ROUTING_POLICY` in `routing-preferences.ts`), which the
+ * policyEngine implements by short-circuiting to whichever candidate
+ * has provider `eliza-local-inference` / `capacitor-llama` /
+ * `eliza-device-bridge`. So even though `plugin-elizacloud` registers
+ * its TTS handler at plugin priority 50 (higher than the default 0 of
+ * direct providers like ElevenLabs / OpenAI / Groq / Edge-TTS), the
+ * router prefers local first when local is registered AND
+ * `local-inference` has a TTS-capable handler.
+ *
+ * Documented routing precedence for `TEXT_TO_SPEECH`:
+ *
+ *   1. **Local (`eliza-local-inference`)** — tier-aware Eliza-1 voice,
+ *      using the ordered `ELIZA_1_VOICE_BACKENDS` policy in
+ *      `@elizaos/shared/local-inference/catalog` (OmniVoice first where
+ *      bundled, Kokoro fallback where bundled). Always preferred when
+ *      available.
+ *   2. **Eliza Cloud (`elizacloud`)** — managed cloud proxy. Picked when
+ *      local is unavailable. Throws `CloudTtsUnavailableError` when
+ *      cloud isn't connected, which the loop above catches and falls
+ *      through to step 3.
+ *   3. **ElevenLabs (`elevenlabs`)** — direct API key path.
+ *   4. **OpenAI (`openai`)** — direct API key path.
+ *   5. **Groq (`groq`)** — direct API key path.
+ *   6. **Edge-TTS (`edge-tts`)** — free Microsoft Edge endpoint, no key.
+ *
+ * Same precedence applies to `TRANSCRIPTION`, with the local side using
+ * Qwen3-ASR via the fused libelizainference (no whisper.cpp; see
+ * `plugin-local-inference/native/AGENTS.md` §1).
+ *
+ * Users can override this per slot via the routing-preferences settings
+ * panel (`prefer-local` ↔ `manual` + explicit `preferredProvider`).
+ */
+
+import type { AgentRuntime, IAgentRuntime } from "@elizaos/core";
+import {
+	logger,
+	ModelType,
+	NoModelProviderConfiguredError,
+} from "@elizaos/core";
+import { readEffectiveAssignments } from "./assignments";
+import { classifyDeviceTier, type DeviceTierAssessment } from "./device-tier";
+import { localInferenceEngine } from "./engine";
+import type { HandlerRegistration } from "./handler-registry";
+import { handlerRegistry } from "./handler-registry";
+import { probeHardware } from "./hardware";
+import { policyEngine } from "./routing-policy";
+import {
+	DEFAULT_ROUTING_POLICY,
+	readRoutingPreferences,
+} from "./routing-preferences";
+import { AGENT_MODEL_SLOTS, type AgentModelSlot } from "./types";
+
+export const ROUTER_PROVIDER = "eliza-router";
+/**
+ * Max safe integer keeps us at the top even if a plugin registers with
+ * a very high priority. If someone deliberately wants to outrank us,
+ * they can register with Infinity — unlikely in practice.
+ */
+const ROUTER_PRIORITY = Number.MAX_SAFE_INTEGER;
+
+/**
+ * The device-tier assessment drives the `auto` policy (and softly hints
+ * `prefer-local`). Probing hardware is cheap but not free, so cache the
+ * assessment for a short window — long enough to avoid re-probing on every
+ * model call, short enough that free-RAM demotion stays roughly current.
+ */
+const DEVICE_TIER_TTL_MS = 30_000;
+let cachedDeviceTier: { at: number; assessment: DeviceTierAssessment } | null =
+	null;
+
+async function resolveDeviceTier(): Promise<DeviceTierAssessment | null> {
+	const now = Date.now();
+	if (cachedDeviceTier && now - cachedDeviceTier.at < DEVICE_TIER_TTL_MS) {
+		return cachedDeviceTier.assessment;
+	}
+	const probe = await probeHardware();
+	const assessment = classifyDeviceTier(probe);
+	cachedDeviceTier = { at: now, assessment };
+	return assessment;
+}
+
+function readBooleanEnv(name: string): boolean {
+	const value =
+		typeof process !== "undefined" ? process.env[name]?.trim() : undefined;
+	if (!value) {
+		return false;
+	}
+	return value === "1" || value.toLowerCase() === "true";
+}
+
+/**
+ * Runtime's registerModel type, narrowed for our use. The core signature
+ * lets the handler return any model type; for routing we only care that
+ * we can call it and await a result.
+ */
+type AnyHandler = (
+	runtime: IAgentRuntime,
+	params: Record<string, unknown>,
+) => Promise<unknown>;
+
+function slotToModelType(slot: AgentModelSlot): string | undefined {
+	switch (slot) {
+		case "TEXT_SMALL":
+			return ModelType.TEXT_SMALL;
+		case "TEXT_LARGE":
+			return ModelType.TEXT_LARGE;
+		case "TEXT_EMBEDDING":
+			return ModelType.TEXT_EMBEDDING;
+		case "TEXT_TO_SPEECH":
+			return ModelType.TEXT_TO_SPEECH;
+		case "TRANSCRIPTION":
+			return ModelType.TRANSCRIPTION;
+	}
+}
+
+function modelTypeToSlot(modelType: string): AgentModelSlot | null {
+	for (const slot of AGENT_MODEL_SLOTS) {
+		if (slotToModelType(slot) === modelType) return slot;
+	}
+	return null;
+}
+
+function shouldForceLocalInference(
+	policy: string,
+	preferredProvider: string | null,
+): boolean {
+	return policy === "manual" && preferredProvider === "eliza-local-inference";
+}
+
+function getRuntimeModelCandidates(
+	runtime: IAgentRuntime,
+	modelType: string,
+): HandlerRegistration[] {
+	const models = (runtime as { models?: unknown }).models;
+	if (!(models instanceof Map)) return [];
+	const registrations = models.get(modelType);
+	if (!Array.isArray(registrations)) return [];
+	return registrations
+		.filter(
+			(
+				entry,
+			): entry is {
+				provider: string;
+				priority?: number;
+				handler: HandlerRegistration["handler"];
+			} =>
+				entry &&
+				typeof entry === "object" &&
+				typeof (entry as { provider?: unknown }).provider === "string" &&
+				(entry as { provider: string }).provider !== ROUTER_PROVIDER &&
+				typeof (entry as { handler?: unknown }).handler === "function",
+		)
+		.map((entry) => ({
+			modelType,
+			provider: entry.provider,
+			priority: typeof entry.priority === "number" ? entry.priority : 0,
+			registeredAt: "runtime-introspection",
+			handler: entry.handler,
+		}))
+		.sort((a, b) => b.priority - a.priority);
+}
+
+export function filterUnavailableLocalInferenceCandidates(
+	candidates: HandlerRegistration[],
+	localInferenceAvailable: boolean,
+	forceLocalInference: boolean,
+): HandlerRegistration[] {
+	if (forceLocalInference || localInferenceAvailable) {
+		return candidates;
+	}
+
+	return candidates.filter(
+		(candidate) => candidate.provider !== "eliza-local-inference",
+	);
+}
+
+export async function filterUnavailableLocalInference(
+	slot: AgentModelSlot,
+	policy: string,
+	preferredProvider: string | null,
+	candidates: HandlerRegistration[],
+): Promise<HandlerRegistration[]> {
+	// Voice slots (TTS / STT) are self-sufficient — their handlers call
+	// ensureActiveBundleVoiceReady() internally which loads the voice model
+	// on-demand. Don't gate them behind text model availability; the text
+	// model assignment check only makes sense for text generation slots.
+	if (slot === "TEXT_TO_SPEECH" || slot === "TRANSCRIPTION") {
+		return candidates;
+	}
+
+	const hasLocalInference = candidates.some(
+		(candidate) => candidate.provider === "eliza-local-inference",
+	);
+	if (!hasLocalInference) {
+		return candidates;
+	}
+
+	const assignments = await readEffectiveAssignments();
+	return filterUnavailableLocalInferenceCandidates(
+		candidates,
+		Boolean(assignments[slot]) || localInferenceEngine.hasLoadedModel(),
+		shouldForceLocalInference(policy, preferredProvider),
+	);
+}
+
+function makeRouterHandler(slot: AgentModelSlot): AnyHandler {
+	return async (runtime, params) => {
+		const modelType = slotToModelType(slot);
+		if (!modelType) {
+			throw new Error(`[router] Unknown agent slot: ${slot}`);
+		}
+
+		// Global local-only override: ELIZA_LOCAL_ONLY=1 pins every slot to
+		// manual + eliza-local-inference, disabling cloud fallback entirely.
+		const globalLocalOnly = readBooleanEnv("ELIZA_LOCAL_ONLY");
+
+		// Read the user's policy for this slot. Absent = local-first fallback.
+		const prefs = await readRoutingPreferences();
+		const policy = globalLocalOnly
+			? "manual"
+			: (prefs.policy[slot] ?? DEFAULT_ROUTING_POLICY);
+		const preferred = globalLocalOnly
+			? "eliza-local-inference"
+			: (prefs.preferredProvider[slot] ?? null);
+
+		// Ask the policy engine which handler to dispatch to. For automatic
+		// policies, honor the documented fallback behaviour: if the selected
+		// provider throws, try the next eligible provider instead of surfacing a
+		// local/model-specific failure while cloud providers are available.
+		const registeredCandidates = handlerRegistry.getForTypeExcluding(
+			modelType,
+			ROUTER_PROVIDER,
+		);
+		const candidates = await filterUnavailableLocalInference(
+			slot,
+			policy,
+			preferred,
+			registeredCandidates.length > 0
+				? registeredCandidates
+				: getRuntimeModelCandidates(runtime, modelType),
+		);
+
+		// Only the capability-aware policies need a hardware assessment.
+		const deviceTier =
+			policy === "auto" || policy === "prefer-local"
+				? await resolveDeviceTier()
+				: null;
+
+		const failedProviders = new Set<string>();
+		let lastError: unknown = null;
+
+		while (true) {
+			const remaining = candidates.filter(
+				(candidate) => !failedProviders.has(candidate.provider),
+			);
+			const pick = policyEngine.pickProvider({
+				modelType,
+				policy,
+				preferredProvider: preferred,
+				candidates: remaining,
+				selfProvider: ROUTER_PROVIDER,
+				deviceTier,
+			});
+
+			if (!pick) {
+				if (lastError) {
+					throw lastError;
+				}
+				throw new NoModelProviderConfiguredError(
+					`[router] No provider registered for ${slot}. Configure a cloud provider, enable local inference, or pair a device.`,
+				);
+			}
+
+			policyEngine.recordPick(pick.provider, modelType);
+			const start = Date.now();
+			try {
+				const result = await pick.handler(runtime, params);
+				policyEngine.recordLatency(
+					pick.provider,
+					modelType,
+					Date.now() - start,
+				);
+				return result;
+			} catch (err) {
+				// Record the timing even on failure so "fastest" doesn't silently
+				// prefer providers that error out fast.
+				policyEngine.recordLatency(
+					pick.provider,
+					modelType,
+					Date.now() - start,
+				);
+
+				const manualPreferred =
+					policy === "manual" &&
+					preferred !== null &&
+					pick.provider === preferred;
+				const hasAlternative = remaining.some(
+					(candidate) => candidate.provider !== pick.provider,
+				);
+				if (manualPreferred || !hasAlternative) {
+					throw err;
+				}
+
+				failedProviders.add(pick.provider);
+				lastError = err;
+				logger.info(
+					`[router] Provider ${pick.provider} failed for ${slot}; trying fallback provider (${err instanceof Error ? err.message : String(err)})`,
+				);
+			}
+		}
+	};
+}
+
+/**
+ * Install the router as the top-priority handler for every slot.
+ *
+ * Idempotent per-runtime via the handler-registry's "last write wins"
+ * behaviour — re-registering our handlers just refreshes them in place.
+ * Called from `ensure-local-inference-handler.ts` after `handlerRegistry`
+ * has been installed on the runtime.
+ */
+export interface RouterInstallOptions {
+	skipSlots?: readonly AgentModelSlot[];
+}
+
+export function installRouterHandler(
+	runtime: AgentRuntime,
+	options: RouterInstallOptions = {},
+): void {
+	const rt = runtime as AgentRuntime & {
+		registerModel?: (
+			modelType: string,
+			handler: AnyHandler,
+			provider: string,
+			priority?: number,
+		) => void;
+	};
+	if (typeof rt.registerModel !== "function") return;
+
+	const skippedSlots = new Set(options.skipSlots ?? []);
+	for (const slot of AGENT_MODEL_SLOTS) {
+		if (skippedSlots.has(slot)) continue;
+		const modelType = slotToModelType(slot);
+		if (!modelType) continue;
+		rt.registerModel(
+			modelType,
+			makeRouterHandler(slot),
+			ROUTER_PROVIDER,
+			ROUTER_PRIORITY,
+		);
+	}
+}
+
+/** Public helper — useful for diagnostics endpoints. */
+export function describeCurrentRouting(): Array<{
+	slot: AgentModelSlot;
+	modelType: string;
+	candidates: Array<{
+		provider: string;
+		priority: number;
+	}>;
+}> {
+	const out: ReturnType<typeof describeCurrentRouting> = [];
+	for (const slot of AGENT_MODEL_SLOTS) {
+		const modelType = slotToModelType(slot);
+		if (!modelType) continue;
+		const candidates = handlerRegistry
+			.getForTypeExcluding(modelType, ROUTER_PROVIDER)
+			.map((c) => ({ provider: c.provider, priority: c.priority }));
+		out.push({ slot, modelType, candidates });
+	}
+	return out;
+}
+
+// Re-export so the handler registry can tell whether it's looking at a
+// recursive router registration when filtering.
+export { modelTypeToSlot };

package/src/services/routing-policy.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Policy engine + latency + cost tracking for cross-provider routing.
+ *
+ * The policy engine sits on top of the `handlerRegistry` and, given a
+ * model type and a user-selected policy, decides which provider's handler
+ * should serve the next request. The router-handler (registered at top
+ * priority) calls `pickProvider` to make that decision.
+ *
+ * Policies:
+ *   - manual       — honour `preferredProvider`; when no pref set, fall
+ *                    through to the runtime's native priority order
+ *                    (highest registered priority wins).
+ *   - auto         — capability-driven: consult the device-tier assessment.
+ *                    When the device can comfortably run local inference
+ *                    (recommended mode "local", or a MAX/GOOD tier) AND a
+ *                    local handler is registered for the slot, pick local.
+ *                    Otherwise pick the highest-priority cloud provider.
+ *   - cheapest     — pick the provider with the lowest per-token cost.
+ *   - fastest      — pick the provider with the lowest tracked p50 latency
+ *                    (needs at least a few samples; falls back to native).
+ *   - prefer-local — try local first; if it fails or has no handler,
+ *                    fall through to the next-best non-local. A POOR device
+ *                    tier (cannot run a local LM) softly demotes the local
+ *                    pick so an unusable on-device path isn't forced.
+ *   - round-robin  — distribute load evenly across eligible providers.
+ *
+ * Latency is tracked in a ring buffer per provider per model type. Cost
+ * is a static table of published per-million-token rates; local providers
+ * are $0. Neither is exact — the goal is "good enough to discriminate"
+ * rather than dollar-accurate billing.
+ */
+import type { DeviceTierAssessment } from "./device-tier";
+import type { HandlerRegistration } from "./handler-registry";
+import type { RoutingPolicy } from "./routing-preferences";
+declare class PolicyEngine {
+    private stats;
+    private statsFor;
+    recordLatency(provider: string, modelType: string, durationMs: number): void;
+    recordPick(provider: string, modelType: string): void;
+    p50(provider: string, modelType: string): number | null;
+    lastPicked(provider: string, modelType: string): number | null;
+    costOf(provider: string): number | null;
+    /**
+     * Pick a provider for this (modelType, policy) given the registry.
+     * Returns the HandlerRegistration whose handler the router-handler
+     * should dispatch to, or null if no eligible handler exists.
+     *
+     * `preferredProvider` is only honoured for policy === "manual".
+     */
+    pickProvider(args: {
+        modelType: string;
+        policy: RoutingPolicy;
+        preferredProvider: string | null;
+        candidates: HandlerRegistration[];
+        /** Provider ID of the router itself — always excluded from candidates. */
+        selfProvider: string;
+        /**
+         * Device-capability assessment from `classifyDeviceTier()`. Consulted by
+         * the `auto` policy and used as a soft hint by `prefer-local`. Null when
+         * the host hasn't probed hardware yet — `auto` then falls back to cloud.
+         */
+        deviceTier?: DeviceTierAssessment | null;
+    }): HandlerRegistration | null;
+    /** For tests and diagnostics. */
+    snapshot(): Record<string, Record<string, number | null>>;
+}
+export declare const policyEngine: PolicyEngine;
+export {};
+//# sourceMappingURL=routing-policy.d.ts.map

package/src/services/routing-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-policy.d.ts","sourceRoot":"","sources":["routing-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAyG3D,cAAM,YAAY;IACjB,OAAO,CAAC,KAAK,CAAmD;IAEhE,OAAO,CAAC,QAAQ;IAShB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAU5E,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAIrD,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIvD,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAI9D,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAQvC;;;;;;OAMG;IACH,YAAY,CAAC,IAAI,EAAE;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,aAAa,CAAC;QACtB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;QACjC,UAAU,EAAE,mBAAmB,EAAE,CAAC;QAClC,0EAA0E;QAC1E,YAAY,EAAE,MAAM,CAAC;QACrB;;;;WAIG;QACH,UAAU,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;KACzC,GAAG,mBAAmB,GAAG,IAAI;IAiF9B,iCAAiC;IACjC,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CAWzD;AAED,eAAO,MAAM,YAAY,cAAqB,CAAC"}

package/src/services/routing-policy.test.ts

@@ -0,0 +1,164 @@
+import type { IAgentRuntime } from "@elizaos/core";
+import { describe, expect, it } from "vitest";
+import { classifyDeviceTier, type DeviceTierAssessment } from "./device-tier";
+import type { HandlerRegistration } from "./handler-registry";
+import { policyEngine } from "./routing-policy";
+import type { HardwareProbe } from "./types";
+
+const noopHandler: HandlerRegistration["handler"] = async (
+	_runtime: IAgentRuntime,
+	_params: Record<string, unknown>,
+) => null;
+
+function registration(provider: string, priority: number): HandlerRegistration {
+	return {
+		modelType: "TEXT_LARGE",
+		provider,
+		priority,
+		registeredAt: "test",
+		handler: noopHandler,
+	};
+}
+
+const baseProbe: HardwareProbe = {
+	totalRamGb: 16,
+	freeRamGb: 8,
+	gpu: null,
+	cpuCores: 8,
+	platform: "linux",
+	arch: "x64",
+	appleSilicon: false,
+	recommendedBucket: "mid",
+	source: "os-fallback",
+};
+
+// A CUDA workstation: 24 GB VRAM, plenty of free RAM → MAX tier, mode "local".
+const strongDevice: DeviceTierAssessment = classifyDeviceTier({
+	...baseProbe,
+	totalRamGb: 64,
+	freeRamGb: 48,
+	gpu: { backend: "cuda", totalVramGb: 24, freeVramGb: 22 },
+	cpuCores: 16,
+});
+
+// A 4 GB Chromebook-class box → POOR tier, mode "cloud-only".
+const weakDevice: DeviceTierAssessment = classifyDeviceTier({
+	...baseProbe,
+	totalRamGb: 4,
+	freeRamGb: 1.5,
+	cpuCores: 2,
+});
+
+describe("PolicyEngine — auto policy", () => {
+	it("classifier sanity: strong device favours local, weak device does not", () => {
+		expect(strongDevice.tier).toBe("MAX");
+		expect(strongDevice.recommendedMode).toBe("local");
+		expect(strongDevice.canRunLocalLm).toBe(true);
+		expect(weakDevice.tier).toBe("POOR");
+		expect(weakDevice.canRunLocalLm).toBe(false);
+	});
+
+	it("routes a strong device to the local provider", () => {
+		const pick = policyEngine.pickProvider({
+			modelType: "TEXT_LARGE",
+			policy: "auto",
+			preferredProvider: null,
+			candidates: [
+				registration("eliza-local-inference", -100),
+				registration("anthropic", 0),
+			],
+			selfProvider: "eliza-router",
+			deviceTier: strongDevice,
+		});
+		expect(pick?.provider).toBe("eliza-local-inference");
+	});
+
+	it("routes a weak device to the highest-priority cloud provider", () => {
+		const pick = policyEngine.pickProvider({
+			modelType: "TEXT_LARGE",
+			policy: "auto",
+			preferredProvider: null,
+			candidates: [
+				registration("eliza-local-inference", -100),
+				registration("anthropic", 0),
+				registration("elizacloud", 50),
+			],
+			selfProvider: "eliza-router",
+			deviceTier: weakDevice,
+		});
+		expect(pick?.provider).toBe("elizacloud");
+	});
+
+	it("falls back to cloud when no device assessment is available", () => {
+		const pick = policyEngine.pickProvider({
+			modelType: "TEXT_LARGE",
+			policy: "auto",
+			preferredProvider: null,
+			candidates: [
+				registration("eliza-local-inference", -100),
+				registration("anthropic", 0),
+			],
+			selfProvider: "eliza-router",
+			deviceTier: null,
+		});
+		expect(pick?.provider).toBe("anthropic");
+	});
+
+	it("uses the only available provider even if it is local on a weak device", () => {
+		const pick = policyEngine.pickProvider({
+			modelType: "TEXT_LARGE",
+			policy: "auto",
+			preferredProvider: null,
+			candidates: [registration("eliza-local-inference", -100)],
+			selfProvider: "eliza-router",
+			deviceTier: weakDevice,
+		});
+		expect(pick?.provider).toBe("eliza-local-inference");
+	});
+});
+
+describe("PolicyEngine — prefer-local capability soft-hint", () => {
+	it("keeps local-first when no assessment is provided", () => {
+		const pick = policyEngine.pickProvider({
+			modelType: "TEXT_LARGE",
+			policy: "prefer-local",
+			preferredProvider: null,
+			candidates: [
+				registration("eliza-local-inference", -100),
+				registration("anthropic", 0),
+			],
+			selfProvider: "eliza-router",
+		});
+		expect(pick?.provider).toBe("eliza-local-inference");
+	});
+
+	it("demotes to cloud on a POOR device that cannot run a local LM", () => {
+		const pick = policyEngine.pickProvider({
+			modelType: "TEXT_LARGE",
+			policy: "prefer-local",
+			preferredProvider: null,
+			candidates: [
+				registration("eliza-local-inference", -100),
+				registration("anthropic", 0),
+			],
+			selfProvider: "eliza-router",
+			deviceTier: weakDevice,
+		});
+		expect(pick?.provider).toBe("anthropic");
+	});
+
+	it("still prefers local on a strong device", () => {
+		const pick = policyEngine.pickProvider({
+			modelType: "TEXT_LARGE",
+			policy: "prefer-local",
+			preferredProvider: null,
+			candidates: [
+				registration("eliza-local-inference", -100),
+				registration("anthropic", 0),
+			],
+			selfProvider: "eliza-router",
+			deviceTier: strongDevice,
+		});
+		expect(pick?.provider).toBe("eliza-local-inference");
+	});
+});