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

package/dist/services/ram-budget.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Resolve a model's RAM budget and decide whether it fits the host.
+ *
+ * For installed Eliza-1 tiers WITH a published `eliza-1.manifest.json`
+ * on disk we prefer the manifest's `ramBudgetMb.{min, recommended}`
+ * block — that's what packages/inference/AGENTS.md §3 + §6 designate
+ * as the source of truth for per-bundle memory expectations. For every
+ * other model (non-Eliza-1, uninstalled tiers, or Eliza-1 bundles that
+ * predate the manifest publish) we fall back to the catalog scalar
+ * `model.minRamGb` for the floor and synthesize a `recommendedMb` from
+ * the floor plus the bundle's per-token KV-cache footprint at its default
+ * context window — the same `KvGeometry` figure `kv-spill.ts` uses. That
+ * fixes the degenerate `minMb == recommendedMb` catalog case: a long
+ * session grows into the KV cache, so "boots" and "runs comfortably" are
+ * genuinely different lines.
+ *
+ * The manifest read is best-effort: a missing or malformed manifest
+ * never throws — recommendation runs at runtime and a broken manifest
+ * must not crash the dashboard. Build-time gates live in the publish
+ * script (packages/training/scripts/manifest/eliza1_manifest.py) and
+ * the validator (`./manifest/validator.ts`).
+ *
+ * This module is the single source of truth for the "does model X fit a
+ * host with N MB usable RAM" decision (`assessRamFit`). Both the Model
+ * Hub recommender (`recommendation.ts`) and the model-load admission gate
+ * (`active-model.ts`) call it — neither re-derives the math.
+ */
+import { type Eliza1Manifest } from "./manifest";
+import type { CatalogModel, InstalledModel, RamBudget } from "./types";
+export declare function ramHeadroomReserveMb(): number;
+export type { RamBudget } from "./types.js";
+/**
+ * Loader contract — keeps the helper testable without touching disk.
+ * Production callers pass `defaultManifestLoader`; tests inject a fake loader.
+ */
+export type ManifestLoader = (modelId: string, installed: InstalledModel | undefined) => Eliza1Manifest | null;
+/** Test-only: drop memoized manifests so fixtures with reused SHAs don't leak. */
+export declare function __resetManifestCacheForTests(): void;
+/**
+ * Production manifest loader — reads `eliza-1.manifest.json` from the
+ * installed bundle's directory. Two candidate paths are probed:
+ *
+ *   1. `dirname(dirname(model.path))` — the canonical bundle root when
+ *      the GGUF lives in a `text/` subdir per AGENTS.md §2.
+ *   2. `dirname(model.path)` — flat layout used by some test fixtures
+ *      and pre-bundle installs.
+ *
+ * Returns `null` for any failure: missing file, JSON parse error,
+ * manifest validation error, or tier mismatch.
+ */
+export declare function defaultManifestLoader(modelId: string, installed: InstalledModel | undefined): Eliza1Manifest | null;
+/**
+ * Resolve a `RamBudget` for `model`, optionally consulting the on-disk
+ * manifest of an installed Eliza-1 bundle.
+ *
+ * `installed` and `manifestLoader` are both optional — passing neither
+ * always returns the catalog-scalar fallback. The recommendation engine
+ * passes both at call sites where it has the installed-models list.
+ */
+export declare function resolveRamBudget(model: CatalogModel, installed?: InstalledModel, manifestLoader?: ManifestLoader): RamBudget;
+export interface RamFitOptions {
+    installed?: InstalledModel;
+    manifestLoader?: ManifestLoader;
+    /**
+     * Override the headroom reserved for the OS/runtime. Defaults to
+     * `ramHeadroomReserveMb()`. Pass 0 to assess against raw memory (the
+     * recommender does this — it works in "effective memory available to
+     * the model" terms, where the OS reserve is already discounted).
+     */
+    reserveMb?: number;
+}
+export type RamFitLevel = "fits" | "tight" | "wontfit";
+export interface RamFitDecision {
+    level: RamFitLevel;
+    /** True for `fits` and `tight`; false only for `wontfit`. */
+    fits: boolean;
+    budget: RamBudget;
+    /** Memory after subtracting the headroom reserve, in MB. */
+    usableMb: number;
+    /** Headroom reserve applied, in MB. */
+    reserveMb: number;
+}
+/**
+ * The one fit decision. `hostRamMb` is the memory being assessed against,
+ * in megabytes (`os.totalmem() / 2**20`, or the probe's `totalRamGb * 1024`,
+ * or — for the recommender on a GPU host — the effective model-available
+ * memory in MB).
+ *
+ *   - `wontfit` : usable RAM (host minus headroom) is below the bundle's
+ *                 boot floor (`budget.minMb`). A load MUST be refused.
+ *   - `tight`   : boots, but usable RAM is below the recommended budget —
+ *                 a long session will swap or stutter under load.
+ *   - `fits`    : comfortable headroom.
+ */
+export declare function assessRamFit(model: CatalogModel, hostRamMb: number, options?: RamFitOptions): RamFitDecision;
+/**
+ * Given a catalog entry, pick the variant of the same model "line" (same
+ * param count and display-name stem — e.g. `eliza-1-27b` / `eliza-1-27b-256k`)
+ * with the largest context window that still fits a
+ * host with `hostRamMb` of RAM. Returns `model` itself when it's already
+ * the best fit (or the only variant), or `null` when not even `model` fits
+ * — callers turn that into a refusal.
+ *
+ * Variants are matched by `(params, displayNameStem)` where the stem is the
+ * display name with any trailing `-<ctx>` suffix (`-256k`, `-1m`, `-128k`)
+ * stripped. This keeps `eliza-1-27b*` together without conflating `9b` and
+ * `27b`.
+ */
+export declare function pickFittingContextVariant(model: CatalogModel, hostRamMb: number, options?: RamFitOptions, catalog?: ReadonlyArray<CatalogModel>): CatalogModel | null;
+//# sourceMappingURL=ram-budget.d.ts.map

package/dist/services/ram-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ram-budget.d.ts","sourceRoot":"","sources":["../../src/services/ram-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,OAAO,EAAE,KAAK,cAAc,EAAoB,MAAM,YAAY,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAoBvE,wBAAgB,oBAAoB,IAAI,MAAM,CAO7C;AAED,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAC5B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,cAAc,GAAG,SAAS,KACjC,cAAc,GAAG,IAAI,CAAC;AAmB3B,kFAAkF;AAClF,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD;AAOD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,cAAc,GAAG,SAAS,GACnC,cAAc,GAAG,IAAI,CAyCvB;AAkBD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,YAAY,EACnB,SAAS,CAAC,EAAE,cAAc,EAC1B,cAAc,GAAE,cAAsC,GACpD,SAAS,CAiBX;AAED,MAAM,WAAW,aAAa;IAC7B,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvD,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,WAAW,CAAC;IACnB,6DAA6D;IAC7D,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,SAAS,CAAC;IAClB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC3B,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,aAAkB,GACzB,cAAc,CAmBhB;AAOD;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACxC,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,aAAkB,EAC3B,OAAO,GAAE,aAAa,CAAC,YAAY,CAAiB,GAClD,YAAY,GAAG,IAAI,CAkBrB"}

package/dist/services/readiness.d.ts

@@ -0,0 +1,9 @@
+import type { ActiveModelState, CatalogModel, DownloadJob, InstalledModel, LocalInferenceReadiness, ModelAssignments } from "./types";
+export declare function buildTextGenerationReadiness(input: {
+    assignments: ModelAssignments;
+    installed: InstalledModel[];
+    active: ActiveModelState;
+    downloads: DownloadJob[];
+    catalog?: CatalogModel[];
+}): LocalInferenceReadiness;
+//# sourceMappingURL=readiness.d.ts.map

package/dist/services/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../../src/services/readiness.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,gBAAgB,EAChB,YAAY,EACZ,WAAW,EAEX,cAAc,EAEd,uBAAuB,EAEvB,gBAAgB,EAEhB,MAAM,SAAS,CAAC;AA8LjB,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IACnD,WAAW,EAAE,gBAAgB,CAAC;IAC9B,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;CACzB,GAAG,uBAAuB,CA4B1B"}

package/dist/services/recommendation.d.ts

@@ -0,0 +1,111 @@
+import { type Eliza1DeviceCaps } from "./manifest";
+import { type ManifestLoader } from "./ram-budget";
+import type { CatalogModel, CatalogQuantizationVariant, HardwareFitLevel, HardwareProbe, InstalledModel, 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 selectBestQuantizationVariant(model: CatalogModel): CatalogQuantizationVariant | null;
+export declare function assessCatalogModelFit(hardware: HardwareProbe, model: CatalogModel, catalog?: CatalogModel[], options?: {
+    installed?: InstalledModel;
+    manifestLoader?: ManifestLoader;
+}): 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;
+    /**
+     * Models the user has already installed. When an Eliza-1 tier in this
+     * list has a published `eliza-1.manifest.json` next to its bundle,
+     * the recommender consults `manifest.ramBudgetMb` instead of the
+     * catalog's coarse `minRamGb` scalar. See `./ram-budget.ts`.
+     */
+    installed?: ReadonlyArray<InstalledModel>;
+    /**
+     * Test-only override for the manifest reader. Production callers leave
+     * this unset and the helper reads `eliza-1.manifest.json` from disk.
+     */
+    manifestLoader?: ManifestLoader;
+}
+export declare function selectRecommendedModelForSlot(slot: TextGenerationSlot, hardware: HardwareProbe, catalog?: CatalogModel[], options?: RecommendationOptions): RecommendedModelSelection;
+/**
+ * Project a `HardwareProbe` onto the `Eliza1DeviceCaps` shape the manifest
+ * validator's `canSetAsDefault` consumes. CPU is always available; a probed
+ * GPU contributes exactly its one backend (`cuda` / `metal` / `vulkan`). RAM
+ * is the device total, in MB — `canSetAsDefault` compares against the
+ * manifest's `ramBudgetMb.min` floor, not the headroom-discounted figure the
+ * ladder uses, because the floor is "will it boot at all".
+ */
+export declare function deviceCapsFromProbe(hardware: HardwareProbe): Eliza1DeviceCaps;
+export type BundleDefaultEligibility = {
+    canBeDefault: true;
+} | {
+    canBeDefault: false;
+    reason: "no-manifest" | "not-default-eligible" | "ram-below-floor" | "kernels-unverified-on-device" | "not-verified-on-device";
+    detail: string;
+};
+/**
+ * True iff this installed Eliza-1 bundle may be offered as the recommended
+ * default on this device. The full set of conditions (any one failing →
+ * not default):
+ *
+ *  - the bundle ships a validated `eliza-1.manifest.json`,
+ *  - the manifest is contract-valid (every required kernel declared, every
+ *    required eval green for a strict release, lineage/files consistent —
+ *    enforced by `canSetAsDefault` → `collectContractErrors`),
+ *  - the device exposes at least one backend the manifest verified `pass` on
+ *    out of the tier's supported set,
+ *  - the device RAM meets the manifest's `ramBudgetMb.min` floor,
+ *  - the bundle has passed the one-time on-device verify pass
+ *    (`InstalledModel.bundleVerifiedAt` is set) — a materialized-but-unverified
+ *    bundle is never auto-selected, per AGENTS.md §7.
+ *
+ * `manifest.defaultEligible: true` is NOT required at the gate level — a
+ * `base-v1-candidate` bundle that passes every above condition is allowed
+ * to fill an empty default slot. The recommender prefers a strict release
+ * (`defaultEligible: true`) over a candidate when both are installed.
+ */
+export declare function canBundleBeDefaultOnDevice(installed: InstalledModel, hardware: HardwareProbe, options?: {
+    manifestLoader?: ManifestLoader;
+}): BundleDefaultEligibility;
+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:
+ *   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 is missing or its HF bundle
+ *      isn't published yet (elizaOS/eliza#7629). The fall-through walks
+ *      the catalog in order, so the maintainer can keep
+ *      `FIRST_RUN_DEFAULT_MODEL_ID` pointed at the *intended* default
+ *      while the publish pipeline catches up.
+ *   3. If every default-eligible tier is pending, last-resort to ANY
+ *      default-eligible tier — the device download path will fail
+ *      cleanly with a 404 rather than silently picking a private
+ *      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[], options?: RecommendationOptions): CatalogModel | null;
+//# sourceMappingURL=recommendation.d.ts.map

package/dist/services/recommendation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendation.d.ts","sourceRoot":"","sources":["../../src/services/recommendation.ts"],"names":[],"mappings":"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"}

package/dist/services/registry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * On-disk registry of installed models.
+ *
+ * The default registry contains only Eliza-owned downloads
+ * (source: "eliza-download") written on successful completion by the
+ * curated bundle downloader. External scans are developer-only diagnostics
+ * behind `ELIZA_LOCAL_INFERENCE_ENABLE_EXTERNAL_SCAN=1`; they never enter
+ * first-run, setup, or normal Settings surfaces.
+ */
+import { type InstalledModel } from "./types";
+/**
+ * Return models currently usable by the curated local-inference path.
+ *
+ * Normal product behavior is Eliza-1 only. The external scan remains available
+ * only to developers who explicitly opt into the old arbitrary-GGUF diagnostic
+ * path with `ELIZA_LOCAL_INFERENCE_ENABLE_EXTERNAL_SCAN=1`.
+ */
+export declare function listInstalledModels(): Promise<InstalledModel[]>;
+/** Add or update a Eliza-owned entry. External entries are rejected. */
+export declare function upsertElizaModel(model: InstalledModel): Promise<void>;
+/** Mark an existing Eliza-owned model as most-recently-used. */
+export declare function touchElizaModel(id: string): Promise<void>;
+/**
+ * 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 declare function removeElizaModel(id: string): Promise<{
+    removed: boolean;
+    reason?: "external" | "not-found";
+}>;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/services/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,EAAE,KAAK,cAAc,EAAoB,MAAM,SAAS,CAAC;AAyChE;;;;;;GAMG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAiBrE;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/dist/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
+ * the fused Gemma ASR path when the active bundle stages eligible ASR
+ * artifacts (no whisper.cpp fallback).
+ *
+ * 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/dist/services/router-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-handler.d.ts","sourceRoot":"","sources":["../../src/services/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;AAU9D,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAEjE,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAiE9C,iBAAS,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAKjE;AA8CD,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,CA4BhC;AAmHD;;;;;;;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/dist/services/routing-policy.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 AND
+ *                    the live device signals (thermal + decode throughput). Route
+ *                    local only when the device can comfortably run the slot's
+ *                    modality (text → `canRunLocalLm`, voice → `canRunLocalVoice`)
+ *                    AND it is not currently throttled / below the TPS budget.
+ *                    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 device that
+ *                    cannot run the slot's modality softly demotes the local
+ *                    pick so an unusable on-device path isn't forced.
+ *   - local-only   — always on-device: never returns a cloud provider. When no
+ *                    local handler is registered, returns `null` so the caller
+ *                    surfaces "no local provider" instead of silently routing
+ *                    to a paid API.
+ *   - cloud-only   — always off-device: never returns a local provider. Returns
+ *                    `null` when only local handlers exist.
+ *   - 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 { LiveDeviceSignals } from "./live-signals";
+import type { RoutingPolicy } from "./routing-preferences";
+import type { AgentModelSlot } from "./types";
+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;
+        /**
+         * The agent slot being routed. Drives the per-modality `auto` gate:
+         * voice slots (`TEXT_TO_SPEECH` / `TRANSCRIPTION`) check
+         * `canRunLocalVoice`; every other slot checks `canRunLocalLm`.
+         */
+        slot?: AgentModelSlot;
+        /**
+         * Static device-capability assessment from `classifyDeviceTier()`.
+         * Consulted by `auto` (per-modality gate) 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;
+        /**
+         * Live device signals (thermal + decode throughput). When the device is
+         * currently throttled or below the TPS budget, `auto` demotes a local
+         * pick to cloud even if the static tier favoured local. Null = no live
+         * demotion (the static decision stands).
+         */
+        liveSignals?: LiveDeviceSignals | 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/dist/services/routing-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-policy.d.ts","sourceRoot":"","sources":["../../src/services/routing-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAkI9C,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,IAAI,CAAC,EAAE,cAAc,CAAC;QACtB;;;;;WAKG;QACH,UAAU,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;QACzC;;;;;WAKG;QACH,WAAW,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;KACvC,GAAG,mBAAmB,GAAG,IAAI;IAsG9B,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/dist/services/routing-preferences.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-export of the shared routing-preferences module. The canonical
+ * implementation lives in `@elizaos/shared/local-inference` because both
+ * the server (`@elizaos/app-core`) and the UI client (`@elizaos/ui`)
+ * read/write the same routing.json with identical semantics.
+ */
+export { DEFAULT_ROUTING_POLICY, isRoutingPolicy, ROUTING_POLICIES, type RoutingPolicy, type RoutingPreferences, readRoutingPreferences, setPolicy, setPreferredProvider, writeRoutingPreferences, } from "@elizaos/shared/local-inference/routing-preferences";
+//# sourceMappingURL=routing-preferences.d.ts.map

package/dist/services/routing-preferences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-preferences.d.ts","sourceRoot":"","sources":["../../src/services/routing-preferences.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACN,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,sBAAsB,EACtB,SAAS,EACT,oBAAoB,EACpB,uBAAuB,GACvB,MAAM,qDAAqD,CAAC"}

package/dist/services/runtime-target.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Inference runtime-target detection.
+ *
+ * The local-inference subsystem has one shipping operational shape:
+ *
+ *   - `"ffi"`          — in-process bun:ffi streaming bindings against the
+ *                        `libelizainference` (fused omnivoice + llama.cpp)
+ *                        shared library. Lives in `voice/ffi-bindings.ts` and
+ *                        `ffi-streaming-runner.ts`. This is mandatory on
+ *                        desktop and mobile so all generation runs in the
+ *                        app's own address space.
+ *   - `"native-bridge"`— delegate to a Capacitor / JNI-side native runtime
+ *                        plugin (e.g. a Swift / Kotlin host wrapping
+ *                        llama.cpp directly). Reserved for builds where the
+ *                        FFI layer cannot be used (e.g. a build that disables
+ *                        `bun:ffi`); only the env-override path selects it.
+ *
+ * This module is the single source of truth for the platform → runtime
+ * mapping.
+ *
+ * Detection inputs (in priority order):
+ *   1. `ELIZA_INFERENCE_MODE` env var. Values: `ffi` / `native-bridge`.
+ *      Wins over every heuristic so operators can force a branch from a CI
+ *      shell or a debug build without recompiling.
+ *   2. Capacitor native marker — when `globalThis.Capacitor.isNativePlatform()`
+ *      returns `true`, we are inside a Capacitor shell on iOS or Android.
+ *      Force `"ffi"` regardless of Node's `process.platform`.
+ *   3. `process.platform` — all recognised and unknown platforms map to
+ *      `"ffi"` unless explicitly overridden to `"native-bridge"`.
+ *
+ * The function is pure: same inputs → same answer. All inputs are explicit
+ * arguments so tests can replay the decision offline without poking the live
+ * `process` / `globalThis`.
+ *
+ * NOTE: this module does NOT decide whether the FFI library is actually
+ * loaded or whether the FFI symbols are present. `backend-selector.ts`
+ * handles that (with a hard throw if the mobile build is missing the
+ * streaming-LLM symbols). The two work together:
+ *
+ *   inferenceRuntimeMode() === "ffi"          → use `ffi-streaming-runner.ts`
+ *   inferenceRuntimeMode() === "native-bridge"→ use the Capacitor plugin shim
+ */
+export type InferenceRuntimeMode = "ffi" | "native-bridge";
+/**
+ * Node's `process.platform` values, narrowed to the set we care about.
+ * `unknown` covers exotic platforms (aix, freebsd, …) without baking them
+ * into the public API of this module.
+ */
+export type SupportedHostPlatform = "darwin" | "linux" | "win32" | "ios" | "android" | "unknown";
+export interface InferenceRuntimeModeInput {
+    /**
+     * Raw `process.platform` value (or a synthetic one in tests). Optional —
+     * defaults to the live `process.platform`. Anything other than the
+     * recognised set is treated as `"unknown"` and routed to `"ffi"`
+     * unless an env override selects the native bridge.
+     */
+    platform?: SupportedHostPlatform | NodeJS.Platform;
+    /**
+     * Whether the JS runtime is currently embedded inside a Capacitor
+     * native shell. Defaults to inspecting `globalThis.Capacitor`. Tests
+     * pass `false` to keep the env-var / platform branches deterministic.
+     */
+    isCapacitorNative?: boolean;
+    /**
+     * Environment-variable bag. Defaults to `process.env`. The function
+     * reads `ELIZA_INFERENCE_MODE` for the override.
+     */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Read and normalise the `ELIZA_INFERENCE_MODE` env override. Returns `null`
+ * when unset or unrecognised.
+ */
+export declare function readRuntimeModeEnvOverride(env?: NodeJS.ProcessEnv): InferenceRuntimeMode | null;
+/**
+ * Synchronous Capacitor probe. Reads `globalThis.Capacitor.isNativePlatform()`
+ * defensively — neither the property nor the call site is guaranteed to
+ * exist in every build (desktop, plain Node tests, web-only Vite dev).
+ *
+ * Surfaces no errors: any failure means "not native". The throw-on-bad-build
+ * policy belongs to the backend-selector, not to platform detection.
+ */
+export declare function isCapacitorNativeRuntime(global?: typeof globalThis): boolean;
+/**
+ * Decide which inference runtime mode the host should use. Pure: caller
+ * controls every input. See file header for the decision rules.
+ */
+export declare function inferenceRuntimeMode(input?: InferenceRuntimeModeInput): InferenceRuntimeMode;
+/**
+ * Convenience wrapper for the `backend-selector.ts` boundary: maps the
+ * runtime mode onto the `"desktop" | "mobile"` slot the selector expects.
+ *
+ * `native-bridge` is treated as `"mobile"` because in every shipping
+ * configuration where we'd pick it the host has already classified itself
+ * as a mobile device (Capacitor shell that opted out of `bun:ffi`).
+ */
+export declare function inferencePlatformClass(mode?: InferenceRuntimeMode): "desktop" | "mobile";
+//# sourceMappingURL=runtime-target.d.ts.map

package/dist/services/runtime-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-target.d.ts","sourceRoot":"","sources":["../../src/services/runtime-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,MAAM,MAAM,oBAAoB,GAAG,KAAK,GAAG,eAAe,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC9B,QAAQ,GACR,OAAO,GACP,OAAO,GACP,KAAK,GACL,SAAS,GACT,SAAS,CAAC;AAEb,MAAM,WAAW,yBAAyB;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAAC,QAAQ,CAAC;IACnD;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACzC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAClC,oBAAoB,GAAG,IAAI,CAa7B;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACvC,MAAM,GAAE,OAAO,UAAuB,GACpC,OAAO,CAST;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CACnC,KAAK,GAAE,yBAA8B,GACnC,oBAAoB,CAYtB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,GAAE,oBAA6C,GACjD,SAAS,GAAG,QAAQ,CAEtB"}