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

package/dist/services/manifest/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/services/manifest/schema.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,CAAC,MAAM,KAAK,CAAC;AAEpB,eAAO,MAAM,+BAA+B,EAAG,GAAY,CAAC;AAC5D,eAAO,MAAM,2BAA2B,EACvC,qDAA8D,CAAC;AAKhE,eAAO,MAAM,wBAAwB,EAAG,QAAiB,CAAC;AAC1D,eAAO,MAAM,4BAA4B,EAAG,MAAgB,CAAC;AAM7D,eAAO,MAAM,iBAAiB,sDAGpB,CAAC;AACX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAI/D,eAAO,MAAM,aAAa,gDAAiD,CAAC;AAC5E,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAcxD,eAAO,MAAM,eAAe,gFAMlB,CAAC;AACX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAC5D,MAAM,MAAM,2BAA2B,GAAG,OAAO,CAChD,kBAAkB,EAClB,UAAU,CACV,CAAC;AAsBF,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAC9C,MAAM,CAAC,YAAY,EAAE,2BAA2B,CAAC,CAOjD,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAC9C,MAAM,CAAC,2BAA2B,EAAE,YAAY,CAAC,CAOjD,CAAC;AAEF,eAAO,MAAM,gBAAgB,qDAMnB,CAAC;AACX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAgB9D,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAC9C,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC,CAO/C,CAAC;AAKF,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAC9C,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC,CAO/C,CAAC;AAGF,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAChD,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC,CAOhD,CAAC;AAeF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+B9B,CAAC;AAWH,eAAO,MAAM,4BAA4B,qCAAsC,CAAC;AAChF,MAAM,MAAM,sBAAsB,GACjC,CAAC,OAAO,4BAA4B,CAAC,CAAC,MAAM,CAAC,CAAC;AAC/C,eAAO,MAAM,gCAAgC;;;EAE5C,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;iBAYhC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB;;;;;iBAKnC,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmE5B,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;EAA0B,CAAC;AAC9D,eAAO,MAAM,uBAAuB;;;;;;EAA2B,CAAC;AAChE,eAAO,MAAM,oBAAoB;;;;;;EAAwB,CAAC;AAE1D,eAAO,MAAM,iCAAiC;;;;;;;;;;iBAU5C,CAAC;AASH,eAAO,MAAM,4BAA4B;;;;iBAIvC,CAAC;AAOH,eAAO,MAAM,4BAA4B;;;;;;;iBAS1B,CAAC;AAEhB,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiB9B,CAAC;AAMH,eAAO,MAAM,0BAA0B,6CAI7B,CAAC;AACX,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAClD,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AACxE,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhF,eAAO,MAAM,iBAAiB;;;;;;;;;;;;iBAQ5B,CAAC;AA2CH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+F5B,CAAC;AAEH,uEAAuE;AACvE,eAAO,MAAM,0BAA0B,EAAG,IAAa,CAAC;AAExD,2EAA2E;AAC3E,eAAO,MAAM,mCAAmC,EAAG,EAAW,CAAC;AAE/D,oEAAoE;AACpE,eAAO,MAAM,oCAAoC,EAAG,IAAa,CAAC;AAElE,uEAAuE;AACvE,eAAO,MAAM,uCAAuC,EAAG,GAAY,CAAC;AAEpE,+EAA+E;AAC/E,eAAO,MAAM,wCAAwC,EAAG,EAAW,CAAC;AAEpE,eAAO,MAAM,qBAAqB;;;iBAO/B,CAAC;AAiBJ,eAAO,MAAM,sBAAsB,yGAOzB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAYzE,eAAO,MAAM,wBAAwB,qCAAsC,CAAC;AAC5E,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAK7E,eAAO,MAAM,wBAAwB,wFAS3B,CAAC;AACX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAkB7E,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;iBAOjC,CAAC;AAMH,eAAO,MAAM,qBAAqB;;;iBAGhC,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgF/B,CAAC"}

package/dist/services/manifest/types.d.ts

@@ -0,0 +1,32 @@
+import type { z } from "zod";
+import type { CpuFeatureProbe } from "../types";
+import type { ELIZA_1_PROVENANCE_SLOTS, ELIZA_1_RELEASE_CHANNELS, ELIZA_1_RELEASE_STATES, Eliza1BackendEnumSchema, Eliza1EvalsSchema, Eliza1FileEntrySchema, Eliza1FilesSchema, Eliza1KernelEnumSchema, Eliza1KernelsSchema, Eliza1LibFileEntrySchema, Eliza1LineageSchema, Eliza1ManifestSchema, Eliza1ProvenanceSchema, Eliza1RamBudgetSchema, Eliza1TextRuntimeClassEnumSchema, Eliza1TierEnumSchema, Eliza1VerifiedBackendStatusSchema, Eliza1VoiceSchema } from "./schema";
+export type Eliza1Tier = z.infer<typeof Eliza1TierEnumSchema>;
+export type Eliza1Kernel = z.infer<typeof Eliza1KernelEnumSchema>;
+export type Eliza1Backend = z.infer<typeof Eliza1BackendEnumSchema>;
+export type Eliza1TextRuntimeClass = z.infer<typeof Eliza1TextRuntimeClassEnumSchema>;
+export type Eliza1FileEntry = z.infer<typeof Eliza1FileEntrySchema>;
+export type Eliza1LibFileEntry = z.infer<typeof Eliza1LibFileEntrySchema>;
+export type Eliza1Files = z.infer<typeof Eliza1FilesSchema>;
+export type Eliza1Lineage = z.infer<typeof Eliza1LineageSchema>;
+export type Eliza1Kernels = z.infer<typeof Eliza1KernelsSchema>;
+export type Eliza1Evals = z.infer<typeof Eliza1EvalsSchema>;
+export type Eliza1RamBudget = z.infer<typeof Eliza1RamBudgetSchema>;
+export type Eliza1Voice = z.infer<typeof Eliza1VoiceSchema>;
+export type Eliza1Provenance = z.infer<typeof Eliza1ProvenanceSchema>;
+export type Eliza1ProvenanceSlot = (typeof ELIZA_1_PROVENANCE_SLOTS)[number];
+export type Eliza1ReleaseState = (typeof ELIZA_1_RELEASE_STATES)[number];
+export type Eliza1ReleaseChannel = (typeof ELIZA_1_RELEASE_CHANNELS)[number];
+export type Eliza1VerifiedBackendStatus = z.infer<typeof Eliza1VerifiedBackendStatusSchema>;
+export type Eliza1Manifest = z.infer<typeof Eliza1ManifestSchema>;
+/**
+ * Capability snapshot of a target device — whatever the runtime detected
+ * (Metal on Mac, Vulkan on Linux/Android, CUDA on NVIDIA, CPU as floor).
+ * `canSetAsDefault()` checks the manifest's verifiedBackends against this.
+ */
+export interface Eliza1DeviceCaps {
+    availableBackends: ReadonlyArray<Eliza1Backend>;
+    ramMb: number;
+    cpuFeatures?: CpuFeatureProbe;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/manifest/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/manifest/types.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,KAAK,EACX,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,EACtB,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,gCAAgC,EAChC,oBAAoB,EACpB,iCAAiC,EACjC,iBAAiB,EACjB,MAAM,UAAU,CAAC;AAElB,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAC9D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAClE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACpE,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAC3C,OAAO,gCAAgC,CACvC,CAAC;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC1E,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7E,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AACzE,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7E,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,iCAAiC,CACxC,CAAC;AACF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAChC,iBAAiB,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,eAAe,CAAC;CAC9B"}

package/dist/services/manifest/validator.d.ts

@@ -0,0 +1,66 @@
+import type { Eliza1DeviceCaps, Eliza1Kernel, Eliza1Manifest, Eliza1Tier } from "./types";
+export interface ValidationOk {
+    ok: true;
+    manifest: Eliza1Manifest;
+}
+export interface ValidationErr {
+    ok: false;
+    errors: ReadonlyArray<string>;
+}
+export type ValidationResult = ValidationOk | ValidationErr;
+/**
+ * Schema + contract validation. Returns a Result-shaped object so callers
+ * can inspect every error rather than catching the first thrown one.
+ *
+ * Throws nothing for invalid input — invalid manifests are reported via
+ * `{ ok: false, errors }`. Truly exceptional cases (non-object input)
+ * surface as Zod issues, not exceptions.
+ */
+export declare function validateManifest(input: unknown): ValidationResult;
+/**
+ * Throws on invalid input. Use this from boot paths where a structured
+ * error is already attached at the boundary. Internal use only — UI
+ * code should prefer `validateManifest`.
+ */
+export declare function parseManifestOrThrow(input: unknown): Eliza1Manifest;
+/**
+ * `canSetAsDefault` is the recommendation-engine gate. A manifest that
+ * passes this is allowed to fill an empty default slot for the device:
+ *
+ *   - the manifest is contract-valid (every required kernel declared, every
+ *     required eval green for a strict release, lineage/files consistent),
+ *   - the device RAM meets the manifest's `ramBudgetMb.min` floor,
+ *   - the device exposes at least one backend the manifest verified `pass`
+ *     on out of the tier's supported set.
+ *
+ * A `defaultEligible: true` manifest is the strict release: every supported
+ * backend kernel-verified `pass`, every required eval green. A
+ * `defaultEligible: false` manifest with an explicit candidate/staging
+ * `releaseState` (`base-v1-candidate`, `local-standin`, `upload-candidate`)
+ * is still permitted to fill an empty default slot **when this device can
+ * run it** — the recommender prefers a strict release over a candidate when
+ * both are installed (see `isStrictReleaseManifest`). Version-only staging
+ * stamps such as `1.0.0-weights-staged.2` are accepted by the install parser
+ * so QA bundles can be materialized, but they do not get this auto-default
+ * relaxation unless the manifest also carries an explicit staging
+ * `releaseState`.
+ *
+ * The device-caps check rejects "this device has Vulkan only but the
+ * manifest only verified Metal/CUDA" — a manifest may be contract-valid
+ * but not runnable on this device.
+ */
+export declare function canSetAsDefault(manifest: Eliza1Manifest, device: Eliza1DeviceCaps): boolean;
+/**
+ * Strict release identifier: a `defaultEligible: true` manifest. The
+ * recommender uses this to prefer a strict release over a candidate
+ * bundle when both are installed and contract-valid. Mirrors the
+ * publish-side `eliza1_gates.yaml` strict bar.
+ */
+export declare function isStrictReleaseManifest(manifest: Eliza1Manifest): boolean;
+/**
+ * Convenience: list missing required kernels for a tier without doing
+ * full validation. Used by the recommendation engine when surfacing
+ * "this bundle is broken" diagnostics.
+ */
+export declare function missingRequiredKernels(tier: Eliza1Tier, declaredRequired: ReadonlyArray<Eliza1Kernel>): ReadonlyArray<Eliza1Kernel>;
+//# sourceMappingURL=validator.d.ts.map

package/dist/services/manifest/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../../src/services/manifest/validator.ts"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EAEX,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,UAAU,EACV,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,IAAI,CAAC;IACT,QAAQ,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC9B;AAED,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,aAAa,CAAC;AAE5D;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAkBjE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAQnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,eAAe,CAC9B,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,gBAAgB,GACtB,OAAO,CAoBT;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAEzE;AA0cD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,UAAU,EAChB,gBAAgB,EAAE,aAAa,CAAC,YAAY,CAAC,GAC3C,aAAa,CAAC,YAAY,CAAC,CAG7B"}

package/dist/services/memory-arbiter.d.ts

@@ -0,0 +1,348 @@
+/**
+ * Memory Arbiter — single in-process owner of every model handle (text,
+ * embedding, vision-language, ASR, TTS, image generation) for the local
+ * inference stack. WS1 deliverable.
+ *
+ * Why this exists
+ * ---------------
+ * The current code has every plugin loading independently:
+ *
+ *   - `plugin-local-inference` owns the text + voice GGUFs through
+ *     `LocalInferenceEngine` + `SharedResourceRegistry`.
+ *   - `plugin-vision` loads its own TF.js / face-api models with no
+ *     shared budget.
+ *   - `plugin-aosp-local-inference` runs the bun:ffi llama.cpp binding
+ *     in its own world, also with no shared budget.
+ *
+ * On a 6 GB iPhone or an 8 GB low-tier Android, that means loading a
+ * vision model on top of a text model gets the app jetsam'd / lmkd-killed
+ * before the planner even runs.
+ *
+ * The arbiter is the single seam every consumer goes through to acquire
+ * a model. It owns the eviction policy across modalities (the existing
+ * `ResidentModelRole` priority table + memory-pressure signals from the
+ * platform), it owns the queue for capability swaps (a vision-describe
+ * arriving while the text model is generating waits its turn rather than
+ * triggering a parallel load that OOMs), and it owns the
+ * `vision-embedding-cache` so repeat frames don't re-pay the projector.
+ *
+ * What this module does NOT do
+ * ----------------------------
+ *   - It does not implement any model loader. Loaders are passed in via
+ *     `registerCapability(...)` by the plugins that own the binding
+ *     (plugin-local-inference for text/embedding, plugin-vision for
+ *     vision-describe, plugin-image-gen for diffusion, etc.).
+ *   - It does not download models, probe hardware, or render UI. Those
+ *     are the existing `Downloader`, `probeHardware`, and Settings UI
+ *     concerns.
+ *   - It does not run on a worker thread. One process, one event loop —
+ *     the arbiter coordinates async work via promises only.
+ *
+ * Consumer contract
+ * -----------------
+ * Capability handlers register themselves at boot:
+ *
+ *   ```ts
+ *   arbiter.registerCapability({
+ *     capability: "vision-describe",
+ *     residentRole: "vision",
+ *     load: async (modelKey) => loadVisionModel(modelKey),
+ *     unload: async (handle) => handle.dispose(),
+ *     run: async (handle, req) => handle.describe(req.imageBytes),
+ *   });
+ *   ```
+ *
+ * Then anyone can call:
+ *
+ *   ```ts
+ *   const result = await arbiter.requestVisionDescribe({
+ *     modelKey: "gemma-vl-4b",
+ *     imageBytes: pixels,
+ *   });
+ *   ```
+ *
+ * The arbiter handles:
+ *   1. Acquiring (or reusing) the handle for `gemma-vl-4b`.
+ *   2. If a different capability holds the active model and we need to
+ *      swap, evicting it first.
+ *   3. Running the request.
+ *   4. Releasing the handle (refcounted; the handle stays loaded until
+ *      pressure or idle eviction reclaims it).
+ *
+ * Telemetry
+ * ---------
+ * The arbiter emits typed events:
+ *   - `model_load`     — a handle came online (capability, modelKey, ms)
+ *   - `model_unload`   — a handle went offline (capability, modelKey, reason)
+ *   - `memory_pressure` — pressure level changed (level, source, freeMb?)
+ *   - `eviction`       — a role was evicted (capability, modelKey, reason)
+ *   - `capability_run` — a request completed (capability, modelKey, ms)
+ *
+ * The runtime observability layer subscribes via `onEvent(...)`.
+ */
+import type { MemoryPressureLevel, MemoryPressureSource } from "./memory-pressure";
+import { VisionEmbeddingCache, type VisionEmbeddingEntry } from "./vision-embedding-cache";
+import { type ResidentModelRole, type SharedResourceRegistry } from "./voice/shared-resources";
+/**
+ * Capability identifiers the arbiter routes between. One per consumer
+ * surface — keep this list short; new capabilities should be added
+ * deliberately, not on a whim.
+ */
+export type ArbiterCapability = "text" | "embedding" | "vision-describe" | "image-gen" | "transcribe";
+/** The opaque handle returned by `acquire`. Callers MUST `release` it. */
+export interface ArbiterHandle<TBackend = unknown> {
+    readonly capability: ArbiterCapability;
+    readonly modelKey: string;
+    readonly backend: TBackend;
+    /**
+     * Increment the refcount so the handle is shared. Returns the same
+     * underlying handle. Useful when one consumer hands the handle to
+     * another mid-flight.
+     */
+    retain(): void;
+    /** Decrement the refcount. When it hits zero the role becomes evictable. */
+    release(): Promise<void>;
+}
+/**
+ * What a capability handler tells the arbiter about itself. The arbiter
+ * uses these to load on demand, run requests, and unload under pressure.
+ */
+export interface CapabilityRegistration<TBackend, TRequest, TResult> {
+    capability: ArbiterCapability;
+    /**
+     * Optional override for the resident-role priority. Defaults to the
+     * `CAPABILITY_ROLE` map; pass when a specific binding has different
+     * eviction semantics than the default for its capability.
+     */
+    residentRole?: ResidentModelRole;
+    /**
+     * Best-effort estimate of bytes the model occupies in RAM/VRAM once
+     * loaded. Used by telemetry only — eviction picks by *priority*, not by
+     * size, so a wrong estimate doesn't change behaviour. 0 when unknown.
+     */
+    estimatedMb?: number;
+    /** Load the backend for a given model key. Called at most once per (capability, modelKey). */
+    load: (modelKey: string) => Promise<TBackend>;
+    /** Tear the backend down. The arbiter stops referencing it after this resolves. */
+    unload: (backend: TBackend) => Promise<void>;
+    /** Run one request through the backend. */
+    run: (backend: TBackend, request: TRequest) => Promise<TResult>;
+}
+/** Telemetry event the runtime observability layer can subscribe to. */
+export type ArbiterEvent = {
+    type: "model_load";
+    capability: ArbiterCapability;
+    modelKey: string;
+    loadMs: number;
+    atMs: number;
+} | {
+    type: "model_unload";
+    capability: ArbiterCapability;
+    modelKey: string;
+    reason: "release" | "swap" | "pressure" | "shutdown" | "fit";
+    atMs: number;
+} | {
+    type: "memory_pressure";
+    level: MemoryPressureLevel;
+    source: string;
+    freeMb?: number;
+    atMs: number;
+} | {
+    type: "eviction";
+    capability: ArbiterCapability;
+    modelKey: string;
+    reason: "pressure" | "swap" | "fit";
+    estimatedMb: number;
+    atMs: number;
+} | {
+    type: "capability_run";
+    capability: ArbiterCapability;
+    modelKey: string;
+    runMs: number;
+    atMs: number;
+};
+export type ArbiterEventListener = (event: ArbiterEvent) => void;
+export interface MemoryArbiterOptions {
+    registry: SharedResourceRegistry;
+    pressureSource?: MemoryPressureSource;
+    visionCache?: VisionEmbeddingCache;
+    logger?: {
+        info?: (m: string) => void;
+        warn?: (m: string) => void;
+        debug?: (m: string) => void;
+    };
+    now?: () => number;
+    /**
+     * Usable RAM budget (MB) for the proactive fit-to-budget LRU eviction
+     * path. Before loading a model whose `estimatedMb` would push the sum of
+     * resident footprints past this budget, the arbiter evicts the
+     * least-recently-used evictable entries (refcount 0, never the text
+     * target) until it fits. Return `null` to disable the fit path entirely —
+     * the default, since an arbiter with no host-RAM knowledge must not guess.
+     * Production wiring passes `os.totalmem()/MB - ramHeadroomReserveMb()`.
+     */
+    budgetMb?: () => number | null;
+    /**
+     * Resident footprint (MB) the arbiter does NOT own in its `resident` map
+     * but which still consumes the host budget — the text-target and embedding
+     * weights loaded by `LocalInferenceEngine` on its own
+     * `SharedResourceRegistry` (#8809 M10b). Without this hook the arbiter's
+     * `residentFootprintMb()` sees only vision/image-gen and the proactive
+     * `evictToFit` path never trips (the two dominant resident consumers are
+     * invisible to it). Production wiring (service.ts) reads the engine's
+     * `text-target` + `embedding` resident estimates. These weights are owned by
+     * the engine and are never the arbiter's eviction target — they are pure
+     * budget accounting, exactly like the pinned text-target in the resident map.
+     * Defaults to 0 (no external footprint known).
+     */
+    externalFootprintMb?: () => number;
+}
+/**
+ * The arbiter. One instance per process; the plugin owns the singleton
+ * (see `index.ts`), and any consumer calls `getMemoryArbiter()` rather
+ * than newing one up.
+ */
+export declare class MemoryArbiter {
+    private readonly registry;
+    private readonly pressureSource;
+    private readonly visionCache;
+    private readonly log?;
+    private readonly now;
+    private readonly budgetMb;
+    private readonly externalFootprintMb;
+    private readonly capabilities;
+    private readonly resident;
+    private readonly listeners;
+    private pressureUnsubscribe;
+    private currentPressure;
+    /**
+     * One serialized in-flight load per (capability, modelKey) so concurrent
+     * `requestX` calls share a single load promise instead of triggering
+     * duplicate weights into RAM.
+     */
+    private readonly inFlightLoads;
+    /**
+     * Per-capability run queue. The arbiter does NOT serialize across
+     * capabilities; what it serializes is the *swap*: when a request needs
+     * to evict another resident role first, the ongoing run on that role is
+     * allowed to finish, then the swap proceeds. Concurrent runs against the
+     * same loaded handle pass through directly.
+     */
+    private readonly queues;
+    private readonly running;
+    private shuttingDown;
+    constructor(opts: MemoryArbiterOptions);
+    /** Begin observing memory pressure. Idempotent. */
+    start(): void;
+    /** Stop observing pressure. Does NOT evict resident handles. */
+    stop(): void;
+    /** Tear down: stop pressure observation and unload every resident handle. */
+    shutdown(): Promise<void>;
+    /** Subscribe to telemetry events. Returns the unsubscribe fn. */
+    onEvent(listener: ArbiterEventListener): () => void;
+    private emit;
+    /** Register a capability handler. Throws on duplicate registration. */
+    registerCapability<TBackend, TRequest, TResult>(registration: CapabilityRegistration<TBackend, TRequest, TResult>): void;
+    /** Whether a capability has been registered. */
+    hasCapability(capability: ArbiterCapability): boolean;
+    /** Diagnostic snapshot of all resident handles. */
+    residentSnapshot(): ReadonlyArray<{
+        capability: ArbiterCapability;
+        modelKey: string;
+        residentRole: ResidentModelRole;
+        estimatedMb: number;
+        refCount: number;
+        loadedAtMs: number;
+        lastUsedAt: number;
+    }>;
+    currentPressureLevel(): MemoryPressureLevel;
+    /**
+     * Predictive warm-load. Unlike `acquire`, preload never creates pressure to
+     * make itself happen: it only loads when the system is nominal and the
+     * configured budget proves the incoming resident footprint fits without
+     * evicting anything. Returns `false` when the guard declines the preload.
+     */
+    preload(capability: ArbiterCapability, modelKey: string): Promise<boolean>;
+    /**
+     * Acquire a handle for `(capability, modelKey)`. If the model is already
+     * resident the refcount is bumped and we return immediately; otherwise we
+     * load it (sharing the in-flight promise across concurrent acquirers).
+     *
+     * Critical pressure causes acquire to throw for non-text capabilities so
+     * we don't load on top of a system the OS has already flagged as in
+     * trouble. Text always loads — without text the agent is a brick.
+     */
+    acquire<TBackend>(capability: ArbiterCapability, modelKey: string): Promise<ArbiterHandle<TBackend>>;
+    private handleFor;
+    private residentKey;
+    private loadOrReuse;
+    private findConflictingRole;
+    private waitForRefcountZero;
+    private makeEvictable;
+    private evictEntry;
+    /**
+     * Proactive fit-to-budget eviction. Before loading a model needing
+     * `incomingMb`, evict the least-recently-used evictable residents until
+     * the projected resident footprint fits `budgetMb()`.
+     *
+     * Policy:
+     *   - Disabled when no budget is configured (`budgetMb()` → null/≤0) or
+     *     the incoming footprint is unknown (`incomingMb` ≤ 0): we never guess.
+     *   - Pins: the text target is never evicted (losing it bricks the agent),
+     *     and any entry with a live refcount is left alone (in active use).
+     *   - Ordering is pure LRU (oldest `lastUsedAt` first); ties break toward
+     *     the lower-priority role, then the older load.
+     *   - Best-effort: if the pins can't be freed enough, the load still
+     *     proceeds — the OS-pressure path and the `active-model` admission gate
+     *     are the backstops; this path only avoids predictable overcommit.
+     */
+    private evictToFit;
+    /**
+     * Total resident footprint counted against the budget: the arbiter's own
+     * resident handles PLUS the engine-owned text-target + embedding weights
+     * reported via `externalFootprintMb` (#8809 M10b). The external term is what
+     * makes `evictToFit` actually fire — without it the two dominant resident
+     * consumers (text, embedding) are invisible and the fit path is dead.
+     */
+    private residentFootprintMb;
+    /**
+     * The next entry the fit path should drop: least-recently-used among
+     * evictable residents (refcount 0, not the text target). Returns null when
+     * nothing is evictable.
+     */
+    private lruEvictionCandidate;
+    private handlePressure;
+    requestText<TRequest, TResult>(req: {
+        modelKey: string;
+        payload: TRequest;
+    }): Promise<TResult>;
+    requestEmbedding<TRequest, TResult>(req: {
+        modelKey: string;
+        payload: TRequest;
+    }): Promise<TResult>;
+    requestVisionDescribe<TRequest, TResult>(req: {
+        modelKey: string;
+        payload: TRequest;
+    }): Promise<TResult>;
+    requestImageGen<TRequest, TResult>(req: {
+        modelKey: string;
+        payload: TRequest;
+    }): Promise<TResult>;
+    requestTranscribe<TRequest, TResult>(req: {
+        modelKey: string;
+        payload: TRequest;
+    }): Promise<TResult>;
+    private enqueueRequest;
+    private drainQueue;
+    getCachedVisionEmbedding(hash: string): VisionEmbeddingEntry | null;
+    setCachedVisionEmbedding(hash: string, entry: {
+        tokens: Float32Array;
+        tokenCount: number;
+        hiddenSize: number;
+    }, ttlMs?: number): void;
+}
+export declare function setMemoryArbiter(arbiter: MemoryArbiter | null): void;
+export declare function getMemoryArbiter(): MemoryArbiter;
+/** Test/diagnostic — returns the singleton without throwing. */
+export declare function tryGetMemoryArbiter(): MemoryArbiter | null;
+//# sourceMappingURL=memory-arbiter.d.ts.map

package/dist/services/memory-arbiter.d.ts.map

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

package/dist/services/memory-benchmark.d.ts

@@ -0,0 +1,76 @@
+import { ELIZA_1_KV_QUANT } from "@elizaos/shared/local-inference";
+import type { ArbiterEvent } from "./memory-arbiter";
+import type { CatalogModel, HardwareProbe, InstalledModel, ModelHubSnapshot } from "./types";
+export interface MemoryBenchmarkModelPlan {
+    modelId: string;
+    displayName: string;
+    installed: boolean;
+    path: string | null;
+    bundleRoot: string | null;
+    bundleSizeMb: number | null;
+    fileSizeMb: number | null;
+    estimatedResidentMb: number;
+    catalogMinRamMb: number | null;
+    catalogContextLength: number | null;
+    fit: "fits" | "tight" | "wontfit";
+    selectedByDeviceFit: boolean;
+    plannedContextLength: number | null;
+    plannedKvQuant: typeof ELIZA_1_KV_QUANT | null;
+}
+export interface MemoryBenchmarkLoadResult {
+    modelId: string;
+    ok: boolean;
+    loadMs: number | null;
+    generateMs: number | null;
+    generatedTokens: number | null;
+    generatedTokensPerSec: number | null;
+    rssBeforeMb: number;
+    rssAfterLoadMb: number | null;
+    rssAfterGenerateMb: number | null;
+    rssDeltaMb: number | null;
+    loadedContextSize: number | null;
+    loadedCacheTypeK: string | null;
+    loadedCacheTypeV: string | null;
+    error: string | null;
+}
+export interface MemoryBenchmarkReport {
+    generatedAt: string;
+    host: {
+        platform: NodeJS.Platform;
+        arch: NodeJS.Architecture;
+        totalRamGb: number;
+        freeRamGb: number;
+        cpuCores: number;
+    };
+    deviceFit: {
+        modelId: string | null;
+        contextLength: number | null;
+        kvQuant: typeof ELIZA_1_KV_QUANT | null;
+        contextDownscaled: boolean;
+        reason: string | null;
+    };
+    models: MemoryBenchmarkModelPlan[];
+    loads: MemoryBenchmarkLoadResult[];
+    telemetry: {
+        modelLoads: number;
+        modelUnloads: number;
+        evictions: number;
+        memoryPressureEvents: number;
+        events: ArbiterEvent[];
+    };
+}
+export interface MemoryBenchmarkOptions {
+    loadInstalled?: boolean;
+    prompt?: string;
+    maxTokens?: number;
+    outFile?: string;
+}
+export declare function buildMemoryBenchmarkPlan(snapshot: {
+    catalog: CatalogModel[];
+    installed: InstalledModel[];
+    hardware: HardwareProbe;
+}): MemoryBenchmarkModelPlan[];
+export declare function buildMemoryBenchmarkReport(snapshot: Pick<ModelHubSnapshot, "catalog" | "installed" | "hardware">, events?: ArbiterEvent[], loads?: MemoryBenchmarkLoadResult[]): Promise<MemoryBenchmarkReport>;
+export declare function runMemoryBenchmark(options?: MemoryBenchmarkOptions): Promise<MemoryBenchmarkReport>;
+export declare function summarizeMemoryBenchmark(report: MemoryBenchmarkReport): string;
+//# sourceMappingURL=memory-benchmark.d.ts.map

package/dist/services/memory-benchmark.d.ts.map

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