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

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;AASjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAQ9D,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAEjE,eAAO,MAAM,eAAe,iBAAiB,CAAC;AA+D9C,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;AA8GD;;;;;;;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);
+	});
+});