@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.11-beta.7

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["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;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,GAAG,WAAW,CAAC;CAClC,CAAC,CA6BD"}

package/src/services/registry.ts

@@ -0,0 +1,151 @@
+/**
+ * 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";
+import { isWithinElizaRoot, localInferenceRoot, registryPath } from "./paths";
+import type { InstalledModel } from "./types";
+
+interface RegistryFile {
+	version: 1;
+	models: InstalledModel[];
+}
+
+async function ensureRootDir(): Promise<void> {
+	await fs.mkdir(localInferenceRoot(), { recursive: true });
+}
+
+async function readElizaOwned(): Promise<InstalledModel[]> {
+	try {
+		const raw = await fs.readFile(registryPath(), "utf8");
+		const parsed = JSON.parse(raw) as RegistryFile;
+		if (parsed?.version !== 1 || !Array.isArray(parsed.models)) {
+			return [];
+		}
+		return parsed.models.filter(
+			(m): m is InstalledModel =>
+				m && typeof m === "object" && m.source === "eliza-download",
+		);
+	} catch {
+		return [];
+	}
+}
+
+async function writeElizaOwned(models: InstalledModel[]): Promise<void> {
+	await ensureRootDir();
+	const tmp = `${registryPath()}.tmp`;
+	const payload: RegistryFile = { 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(): Promise<InstalledModel[]> {
+	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: InstalledModel): Promise<void> {
+	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: string): Promise<void> {
+	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: string): Promise<{
+	removed: boolean;
+	reason?: "external" | "not-found";
+}> {
+	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/src/services/router-handler.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 } from "@elizaos/core";
+import type { HandlerRegistration } from "./handler-registry";
+import { type AgentModelSlot } from "./types";
+export declare const ROUTER_PROVIDER = "eliza-router";
+declare function modelTypeToSlot(modelType: string): AgentModelSlot | null;
+export declare function filterUnavailableLocalInferenceCandidates(candidates: HandlerRegistration[], localInferenceAvailable: boolean, forceLocalInference: boolean): HandlerRegistration[];
+export declare function filterUnavailableLocalInference(slot: AgentModelSlot, policy: string, preferredProvider: string | null, candidates: HandlerRegistration[]): Promise<HandlerRegistration[]>;
+/**
+ * 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 declare function installRouterHandler(runtime: AgentRuntime, options?: RouterInstallOptions): void;
+/** Public helper — useful for diagnostics endpoints. */
+export declare function describeCurrentRouting(): Array<{
+    slot: AgentModelSlot;
+    modelType: string;
+    candidates: Array<{
+        provider: string;
+        priority: number;
+    }>;
+}>;
+export { modelTypeToSlot };
+//# sourceMappingURL=router-handler.d.ts.map

package/src/services/router-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-handler.d.ts","sourceRoot":"","sources":["router-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,eAAe,CAAC;AAQjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAO9D,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAEjE,eAAO,MAAM,eAAe,iBAAiB,CAAC;AA0C9C,iBAAS,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAKjE;AA0CD,wBAAgB,yCAAyC,CACxD,UAAU,EAAE,mBAAmB,EAAE,EACjC,uBAAuB,EAAE,OAAO,EAChC,mBAAmB,EAAE,OAAO,GAC1B,mBAAmB,EAAE,CAQvB;AAED,wBAAsB,+BAA+B,CACpD,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,MAAM,EACd,iBAAiB,EAAE,MAAM,GAAG,IAAI,EAChC,UAAU,EAAE,mBAAmB,EAAE,GAC/B,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAsBhC;AAsGD;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACpC,SAAS,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACtC;AAED,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,YAAY,EACrB,OAAO,GAAE,oBAAyB,GAChC,IAAI,CAuBN;AAED,wDAAwD;AACxD,wBAAgB,sBAAsB,IAAI,KAAK,CAAC;IAC/C,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,KAAK,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACH,CAAC,CAWD;AAID,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/src/services/router-handler.test.ts

@@ -0,0 +1,45 @@
+import { type AgentRuntime, ModelType } from "@elizaos/core";
+import { describe, expect, it, vi } from "vitest";
+import { installRouterHandler, ROUTER_PROVIDER } from "./router-handler";
+
+describe("installRouterHandler", () => {
+	it("does not register router handlers for skipped slots", () => {
+		const registrations: Array<{
+			modelType: string;
+			provider: string;
+			priority?: number;
+		}> = [];
+		const runtime = {
+			registerModel: vi.fn(
+				(
+					modelType: string,
+					_handler: unknown,
+					provider: string,
+					priority?: number,
+				) => {
+					registrations.push({ modelType, provider, priority });
+				},
+			),
+		} as unknown as AgentRuntime;
+
+		installRouterHandler(runtime, { skipSlots: ["TEXT_EMBEDDING"] });
+
+		expect(registrations).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({
+					modelType: ModelType.TEXT_SMALL,
+					provider: ROUTER_PROVIDER,
+				}),
+				expect.objectContaining({
+					modelType: ModelType.TEXT_LARGE,
+					provider: ROUTER_PROVIDER,
+				}),
+			]),
+		);
+		expect(
+			registrations.some(
+				(registration) => registration.modelType === ModelType.TEXT_EMBEDDING,
+			),
+		).toBe(false);
+	});
+});

package/src/services/router-handler.ts

@@ -0,0 +1,376 @@
+/**
+ * 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 { localInferenceEngine } from "./engine";
+import type { HandlerRegistration } from "./handler-registry";
+import { handlerRegistry } from "./handler-registry";
+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;
+
+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),
+		);
+		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,
+			});
+
+			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 };