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

package/dist/runtime/mobile-local-inference-gate.d.ts

@@ -0,0 +1,63 @@
+/**
+ * On a mobile platform (`ELIZA_PLATFORM=android` / `ios`) the runtime skips
+ * nearly every boot helper because they shell out to subprocesses,
+ * platform-specific binaries, or optional packages that aren't in the mobile
+ * bundle. Three mobile-safe inference paths need wiring:
+ *
+ *   - `ELIZA_DEVICE_BRIDGE_ENABLED=1`: the agent (this process) hosts the
+ *     device-bridge WSS and dials whichever paired device connects. On the
+ *     Capacitor APK the WebView's `@elizaos/capacitor-llama` is the intended
+ *     dialer over loopback. The Capacitor build always exports this env so
+ *     the bridge is ready as soon as first-run picks the local mode.
+ *
+ *   - `ELIZA_LOCAL_LLAMA=1`: AOSP path that loads `libllama.so` directly
+ *     inside the Android process via `bun:ffi`. Wired here so the gate is
+ *     in place ahead of sub-task 2 — the AOSP build flag flips this on.
+ *
+ *   - `process.arch === "riscv64"`: `capacitor-llama` has no riscv64 prebuild
+ *     and we can't NAPI-build it on-device, so the in-process FFI path
+ *     (same loader contract as the AOSP path) is the only viable option.
+ *     Auto-firing here keeps the riscv64 mobile boot path zero-config; an
+ *     operator can hard-disable via `ELIZA_DISABLE_FFI_LLAMA=1` to skip the
+ *     loader and route inference through Cloud instead. See
+ *     `plugin-aosp-local-inference/src/aosp-llama-adapter.ts:isAospEnabled`
+ *     and `plugin-local-inference/src/runtime/ensure-local-inference-handler.ts:shouldAttemptAospLlamaLoader`
+ *     — the three predicates agree on the trigger set.
+ *
+ * Kept dependency-free so it can be unit-tested without instantiating the
+ * full runtime.
+ */
+export declare function shouldEnableMobileLocalInference(env?: NodeJS.ProcessEnv, arch?: NodeJS.Architecture): boolean;
+/**
+ * Boot-time invariant check for the mobile voice backend selector.
+ *
+ * The voice engine passes `mobile: isMobilePlatform()` into `selectVoiceBackend`
+ * (`services/engine.ts`). That flag is what pins mobile to the Kokoro-exclusive
+ * TTS path — OmniVoice is never shipped on a phone. But `isMobilePlatform()`
+ * keys solely off `ELIZA_PLATFORM ∈ {ios, android}`, whereas
+ * {@link shouldEnableMobileLocalInference} also fires on the device-bridge /
+ * `ELIZA_LOCAL_LLAMA` / riscv64 triggers — none of which set `ELIZA_PLATFORM`.
+ * So a build that enables the mobile local-inference gate without exporting
+ * `ELIZA_PLATFORM` leaves `mobile` false in the selector and could pick
+ * OmniVoice on a phone, violating the Kokoro-exclusive mobile voice invariant.
+ *
+ * This emits exactly one boot-time warning when the gate is active but the
+ * platform flag is absent (the real mismatch). It is a diagnostic, not a
+ * behavior change: the fix is to export `ELIZA_PLATFORM` from the offending
+ * build, which this surfaces. The caller MUST evaluate it on a boot path where
+ * BOTH predicates are checked (i.e. outside any `if (isMobilePlatform())`
+ * branch) — passing the already-computed `mobilePlatform` makes that explicit.
+ *
+ * Kept dependency-free (injectable `warn` + the already-resolved
+ * `mobilePlatform` boolean) so it can be unit-tested without the runtime or a
+ * logger instance, matching the `engine.warnIfParallelTooLow({ warn })` pattern.
+ *
+ * @returns `true` when the warning fired (the mismatch is real), else `false`.
+ */
+export declare function warnIfMobileGateActiveWithoutPlatform(args: {
+    mobilePlatform: boolean;
+    warn: (message: string) => void;
+    env?: NodeJS.ProcessEnv;
+    arch?: NodeJS.Architecture;
+}): boolean;
+//# sourceMappingURL=mobile-local-inference-gate.d.ts.map

package/dist/runtime/mobile-local-inference-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mobile-local-inference-gate.d.ts","sourceRoot":"","sources":["../../src/runtime/mobile-local-inference-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gCAAgC,CAC/C,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,IAAI,GAAE,MAAM,CAAC,YAA2B,GACtC,OAAO,CAqBT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qCAAqC,CAAC,IAAI,EAAE;IAC3D,cAAc,EAAE,OAAO,CAAC;IACxB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC,YAAY,CAAC;CAC3B,GAAG,OAAO,CAYV"}

package/dist/runtime/voice-entity-binding.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Voice ⇄ entity binding seam (producer + round-trip consumer).
+ *
+ * Producer (`emitVoiceTurnObserved`): emit `VOICE_TURN_OBSERVED` so a
+ * merge-engine owner (plugin-lifeops) can fold the recognized voice turn
+ * into the entity/relationship graph. The voice-profile store is owned
+ * here; the entity graph is owned there; the only shared surface is the
+ * core event seam — neither plugin imports the other.
+ *
+ * Consumer (`handleVoiceEntityBound`): when the merge engine reports a
+ * binding via `VOICE_ENTITY_BOUND`, persist the resulting `entityId` onto
+ * every profile in that imprint cluster (`VoiceProfileStore.bindEntity`).
+ * This is the runtime path that was missing in issue #8234 — without it a
+ * profile's `entityId` stayed `null` and recognized speakers never reached
+ * the relationship graph.
+ */
+import { type IAgentRuntime, type VoiceEntityBoundPayload } from "@elizaos/core";
+import type { VoiceTurnSignal } from "../services/voice/eot-classifier.js";
+import { VoiceProfileStore } from "../services/voice/profile-store.js";
+import type { VoiceAttributionOutput } from "../services/voice/speaker/attribution-pipeline.js";
+export declare function setVoiceEntityBindingStore(store: VoiceProfileStore | null): void;
+export declare function getVoiceProfileStore(): Promise<VoiceProfileStore>;
+export interface EmitVoiceTurnObservedArgs {
+    /** Stable utterance id; a random one is minted when omitted. */
+    turnId?: string;
+    /** Recognized text (drives name/partner-claim extraction downstream). */
+    text: string;
+    /** Imprint cluster id from the voice-profile store. */
+    imprintClusterId: string;
+    /** Confidence of the imprint match (0..1). */
+    matchConfidence: number;
+    /** Entity the imprint already resolved to, or `null`/omitted when unbound. */
+    matchedEntityId?: string | null;
+    /** True when the OWNER spoke this turn. */
+    isOwner?: boolean;
+    /** ISO timestamp; defaults to now. */
+    observedAt?: string;
+}
+/**
+ * Emit `VOICE_TURN_OBSERVED`. No-op in effect when no merge-engine plugin
+ * is loaded (the event simply has no handler). `emitEvent` awaits every
+ * handler, so by the time this resolves the binding round-trip (including
+ * `VOICE_ENTITY_BOUND` → profile persist) has completed.
+ */
+export declare function emitVoiceTurnObserved(runtime: IAgentRuntime, args: EmitVoiceTurnObservedArgs): Promise<void>;
+export interface HandleLiveVoiceAttributionOptions {
+    /**
+     * Entity id the agent treats as the device owner / primary enrolled
+     * speaker. A turn attributed to this entity is always allowed to speak.
+     */
+    ownerEntityId?: string | null;
+    /**
+     * Entity ids the agent answers to without a wake word (owner + enrolled
+     * household members). A confident bystander is anyone attributed to an
+     * entity NOT in this set.
+     */
+    knownSpeakerEntityIds?: readonly string[];
+    /**
+     * The EOT-based turn signal the turn-controller already computed for this
+     * turn (from `eot-classifier` / `turn-controller`). The speaker decision is
+     * folded into it. When omitted, a neutral base is synthesized from
+     * `endOfTurnProbability` (default 0.5 — "unknown", fail open).
+     */
+    baseSignal?: VoiceTurnSignal;
+    /** P(turn complete) when no `baseSignal` is supplied (default 0.5). */
+    endOfTurnProbability?: number;
+    /** True when a wake word fired within the recent listen window. */
+    wakeWordActive?: boolean;
+    /**
+     * The ASR transcript for this turn, joined from the streaming-ASR path. When
+     * provided it rides on `VOICE_TURN_OBSERVED` (and the turn signal) so the
+     * merge engine's name/partner extraction (`VoiceObserver.ingestTurn`) runs
+     * from LIVE audio — previously this was hardcoded `""`, so live recognition
+     * could identify *who* spoke but never *what* they said (#8786). Diarization-
+     * only callers (audio-frame path) leave it unset; the in-process voice engine
+     * (which has both ASR + diarization) passes the real transcript.
+     */
+    transcript?: string;
+    /**
+     * Cosine similarity (0..1) between this turn's live WeSpeaker embedding and
+     * the agent's own TTS-voice centroid. High means the open mic is hearing the
+     * agent's playback, not a human user.
+     */
+    selfVoiceSimilarity?: number | null;
+    /** True while the agent is currently playing TTS. */
+    agentSpeaking?: boolean;
+    /** Age of the most recent agent-spoken reply in ms. */
+    replyAgeMs?: number;
+}
+/**
+ * Handle a live per-turn attribution result. This is the single automatic seam
+ * the engine bridge calls from its `onAttribution` path: any caller that wires a
+ * `profileStore` gets diarization-driven gating for free.
+ *
+ * 1. Emits `VOICE_TURN_OBSERVED` when the turn produced a profile observation
+ *    (so the merge engine can fold the recognized speaker into the entity
+ *    graph and round-trip the binding back onto the profile).
+ * 2. Composes the EOT-based turn signal with the speaker decision and stamps it
+ *    onto `output.turn.metadata.voiceTurnSignal`, which the chat-view producer
+ *    forwards to the server gate verbatim.
+ *
+ * Returns the composed signal (also written onto the turn metadata in place).
+ * Never throws on the emit path — observation emission is best-effort and is
+ * logged, never propagated, so an attribution turn never crashes a voice turn.
+ */
+export declare function handleLiveVoiceAttribution(runtime: IAgentRuntime, output: VoiceAttributionOutput, opts?: HandleLiveVoiceAttributionOptions): Promise<VoiceTurnSignal>;
+/**
+ * Handler for `VOICE_ENTITY_BOUND`. Persists `entityId` onto every profile
+ * in the cluster that is not already bound to it. Returns nothing (the
+ * `EventHandler` contract); the bound count is logged.
+ */
+export declare function handleVoiceEntityBound(payload: VoiceEntityBoundPayload): Promise<void>;
+//# sourceMappingURL=voice-entity-binding.d.ts.map

package/dist/runtime/voice-entity-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-entity-binding.d.ts","sourceRoot":"","sources":["../../src/runtime/voice-entity-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAEN,KAAK,aAAa,EAGlB,KAAK,uBAAuB,EAC5B,MAAM,eAAe,CAAC;AAKvB,OAAO,KAAK,EAEX,eAAe,EACf,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mDAAmD,CAAC;AAQhG,wBAAgB,0BAA0B,CACzC,KAAK,EAAE,iBAAiB,GAAG,IAAI,GAC7B,IAAI,CAEN;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAOvE;AAMD,MAAM,WAAW,yBAAyB;IACzC,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,gBAAgB,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,eAAe,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,2CAA2C;IAC3C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAC1C,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,yBAAyB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAWf;AAWD,MAAM,WAAW,iCAAiC;IACjD;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C;;;;;OAKG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,uEAAuE;IACvE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,mEAAmE;IACnE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,qDAAqD;IACrD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAuGD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,0BAA0B,CAC/C,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,sBAAsB,EAC9B,IAAI,GAAE,iCAAsC,GAC1C,OAAO,CAAC,eAAe,CAAC,CAmD1B;AAMD;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC3C,OAAO,EAAE,uBAAuB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA2Bf"}

package/dist/services/active-model.d.ts

@@ -0,0 +1,310 @@
+/**
+ * Coordinates which model is currently loaded into the plugin-local-ai
+ * runtime. Eliza runs one inference model at a time; switching models
+ * unloads the previous one first so we don't double-allocate VRAM.
+ *
+ * This module *does not* talk to `capacitor-llama` directly. The plugin
+ * owns the native binding; we ask it to swap via a small runtime service
+ * registered under the name "localInferenceLoader". When the plugin is not
+ * enabled, we still track the user's preferred active model so the
+ * preference survives enabling the plugin later.
+ */
+import type { AgentRuntime } from "@elizaos/core";
+import { ELIZA_1_PLACEHOLDER_IDS, FIRST_RUN_DEFAULT_MODEL_ID } from "./catalog";
+import { type Eliza1Kernel, type Eliza1Tier } from "./manifest";
+import { type ManifestLoader, type RamFitOptions } from "./ram-budget";
+import { recommendForFirstRun } from "./recommendation";
+import type { ActiveModelState, CatalogModel, HardwareProbe, InstalledModel } from "./types";
+export type { KvOffloadMode, LocalInferenceLoadArgs } from "./load-args.js";
+export { ELIZA_1_PLACEHOLDER_IDS, FIRST_RUN_DEFAULT_MODEL_ID, recommendForFirstRun, };
+import type { KvOffloadMode, LocalInferenceLoadArgs } from "./load-args.js";
+export declare function isForkOnlyKvCacheType(name: string | undefined): boolean;
+export declare function isStockKvCacheType(name: string | undefined): boolean;
+/**
+ * Validate per-load overrides against what the in-process backend can
+ * honour. The AOSP loader has its own (broader) acceptance set — pass
+ * `{ allowFork: true }` to skip the desktop-only restriction.
+ *
+ * Throws on the first illegal value so the caller (the API route) can
+ * surface a 400 with a useful message instead of letting the load slip
+ * through and silently degrade to fp16.
+ */
+export declare function validateLocalInferenceLoadArgs(args: Partial<LocalInferenceLoadArgs>, options?: {
+    allowFork?: boolean;
+}): void;
+export interface LocalInferenceLoader {
+    loadModel(args: LocalInferenceLoadArgs): Promise<void>;
+    unloadModel(): Promise<void>;
+    currentModelPath(): string | null;
+    /**
+     * Optional generation surface. When a loader implements this, the runtime
+     * handler (`ensure-local-inference-handler.ts`) routes TEXT_SMALL /
+     * TEXT_LARGE requests through it instead of the standalone engine. Mobile
+     * builds populate this via the Capacitor adapter; desktop omits it and falls
+     * back to the `LocalInferenceEngine`.
+     */
+    generate?(args: {
+        prompt: string;
+        stopSequences?: string[];
+        maxTokens?: number;
+        temperature?: number;
+        /**
+         * Optional `promptCacheKey` from the runtime cache plan. Loaders
+         * that implement prefix caching (the in-process llama.cpp FFI slot
+         * pool or node-llama-cpp session pool) use this to pin
+         * subsequent calls with the same key to the same KV cache slot.
+         * Loaders without prefix caching can ignore the field.
+         */
+        cacheKey?: string;
+    }): Promise<string>;
+    /**
+     * Optional embedding surface. When a loader implements this, the runtime
+     * handler routes `TEXT_EMBEDDING` requests through it. The AOSP bun:ffi
+     * loader populates this directly via `llama_get_embeddings_seq`; the
+     * device-bridge loader populates it by dispatching an `embed` frame to
+     * the connected device. Loaders that cannot embed leave this undefined,
+     * and the runtime falls back to its non-local embedding provider chain.
+     */
+    embed?(args: {
+        input: string;
+    }): Promise<{
+        embedding: number[];
+        tokens: number;
+    }>;
+}
+/**
+ * Per-load override fields the caller can set. Subset of `LocalInferenceLoadArgs`
+ * minus `modelPath` (which the coordinator owns) and minus speculative
+ * fields (which the catalog `runtime.mtp` block owns end-to-end). The
+ * route layer accepts this shape on `POST /api/local-inference/active`.
+ */
+export interface LocalInferenceLoadOverrides {
+    contextSize?: number;
+    cacheTypeK?: string;
+    cacheTypeV?: string;
+    gpuLayers?: number;
+    kvOffload?: KvOffloadMode;
+    flashAttention?: boolean;
+    mmap?: boolean;
+    mlock?: boolean;
+    useGpu?: boolean;
+    maxThreads?: number;
+}
+interface ResolveLocalInferenceLoadArgsOptions {
+    manifestLoader?: ManifestLoader;
+    hardware?: HardwareProbe;
+}
+/**
+ * Resolve the per-tier mmproj GGUF path for a given installed model when
+ * the catalog declares the tier ships a vision projector AND the file is
+ * actually on disk under the bundle root.
+ *
+ * Returns:
+ *   - the absolute path to the mmproj file when the tier has vision and
+ *     the file exists.
+ *   - undefined when the tier has no vision component (text-only bundle)
+ *     or when the file hasn't been downloaded yet. In the latter case
+ *     the coordinator emits a one-shot warning; vision capability is
+ *     unavailable for the session but the text load still succeeds.
+ *
+ * Path layout: the catalog's `sourceModel.components.vision.file` is the
+ * Hugging Face-relative path, e.g. `bundles/2b/vision/mmproj-2b.gguf`.
+ * Locally the bundleRoot already represents the per-tier "bundles/<tier>"
+ * subtree, so we strip the leading `bundles/<tier>/` segment before
+ * joining against the local bundleRoot. When that prefix isn't present
+ * (e.g. a custom bundle layout), we fall through to the original path
+ * unchanged. Manifest-validated bundles (`bundleRoot` set) are the only
+ * path that lands a vision component — external-scan models (LM Studio,
+ * Jan) don't.
+ */
+export declare function resolveMmprojPath(installed: InstalledModel, catalog: CatalogModel | undefined): string | undefined;
+export declare function resolveLocalInferenceLoadArgs(installed: InstalledModel, overrides?: LocalInferenceLoadOverrides, options?: ResolveLocalInferenceLoadArgsOptions): Promise<LocalInferenceLoadArgs>;
+export declare class ModelDoesNotFitError extends Error {
+    readonly modelId: string;
+    readonly requiredMb: number;
+    readonly usableMb: number;
+    readonly hostRamMb: number;
+    readonly fittingVariantId: string | null;
+    constructor(args: {
+        modelId: string;
+        requiredMb: number;
+        usableMb: number;
+        hostRamMb: number;
+        fittingVariantId: string | null;
+    });
+}
+/**
+ * Admission gate: refuse a model load when the host can't fit the bundle's
+ * boot floor. `hostRamMb` is the host's total RAM in megabytes. `installed`
+ * is forwarded to `assessRamFit` so a manifest-declared `ramBudgetMb` wins
+ * over the catalog scalar. Throws `ModelDoesNotFitError` on no-fit; returns
+ * the (advisory) fit decision otherwise so callers can log a `tight` warning.
+ *
+ * Models with no catalog entry (external HF blobs) are not gated — the
+ * catalog has no RAM budget for them, so we trust the operator's explicit
+ * pick (the dispatcher's load-time error surfaces if it genuinely OOMs).
+ */
+export declare function assertModelFitsHost(installed: InstalledModel, hostRamMb: number, options?: RamFitOptions): {
+    level: "fits" | "tight";
+    minMb: number;
+    recommendedMb: number;
+};
+/**
+ * Typed error for refused local-voice sessions. Mirrors
+ * `ModelDoesNotFitError` but at the bundle level — emitted by
+ * `assertVoiceBundleFitsHost` when the whole co-resident voice + text stack
+ * cannot fit a host's RAM (per R9 §2.3 / §3.2).
+ *
+ * Catch this at the runtime's voice-session-start boundary and surface the
+ * tier-warning copy (`TIER_WARNING_COPY[<tier>]`) — DO NOT load weights and
+ * watch `MemoryMonitor` evict mid-session.
+ */
+export declare class VoiceBundleDoesNotFitError extends Error {
+    readonly tierSlot: string;
+    readonly deviceTier: string;
+    readonly requiredPeakMb: number;
+    readonly requiredSteadyStateMb: number;
+    readonly usableMb: number;
+    readonly hostRamMb: number;
+    constructor(args: {
+        tierSlot: string;
+        deviceTier: string;
+        requiredPeakMb: number;
+        requiredSteadyStateMb: number;
+        usableMb: number;
+        hostRamMb: number;
+    });
+}
+/**
+ * Cross-model admission gate for the local-voice session. Sums the whole
+ * co-resident bundle (LM + ASR + TTS + embedding + VAD +
+ * wake-word + turn-detector + emotion + speaker-encoder + transient TTS
+ * peak) and refuses entry when the host can't fit it.
+ *
+ * Returns the decision on `fits`. Throws `VoiceBundleDoesNotFitError` when
+ * `wontfit` (when `strict=true`, the default), or just returns the
+ * `wontfit` decision when `strict=false` (the runtime then logs and
+ * degrades silently). Pair with `TIER_WARNING_COPY[deviceTier]` for
+ * user-facing UX.
+ *
+ * R9 §1.4 + §2.3 + §3.2 spec.
+ */
+export declare function assertVoiceBundleFitsHost(args: {
+    tierSlot: string;
+    deviceTier: string;
+    hostRamMb: number;
+    reserveMb?: number;
+    strict?: boolean;
+}): {
+    level: "fits" | "tight" | "wontfit";
+    steadyStateMb: number;
+    peakMb: number;
+    usableMb: number;
+    fits: boolean;
+};
+/**
+ * Refusal raised when activation is asked for a model whose own
+ * `eliza-1.manifest.json` says its text eval has not passed (`candidate.*` /
+ * `weights-staged.*` tiers). Carries the structured payload the route layer
+ * surfaces verbatim to the API consumer: `manifestVersion` so the UI can
+ * say "this tier isn't ready" with the actual version string, and
+ * `failedEvals` so the user sees which checks are still red.
+ *
+ * Why we gate here, not just at download:
+ * - the bundle may already be on disk (hand-staged, manually copied, or
+ *   downloaded before a fail-state was recorded), so the download gate
+ *   alone leaves a window where a candidate-only bundle can be flipped
+ *   into the active model slot and silently emit `[unused]` tokens.
+ *
+ * See issue #7679 for the original symptom: the runtime activated a
+ * candidate `1.0.0-candidate.1` bundle whose every `evals.*.passed`
+ * was `false`, then served BERT/WordPiece reserved tokens (`[unused0..99]`
+ * / `[PAD]`) as chat output with no actionable error.
+ */
+export declare class CandidateModelActivationError extends Error {
+    readonly modelId: string;
+    readonly manifestVersion: string;
+    readonly failedEvals: ReadonlyArray<string>;
+    constructor(args: {
+        modelId: string;
+        manifestVersion: string;
+        failedEvals: ReadonlyArray<string>;
+    });
+}
+/**
+ * Activation eval gate. Reads the installed bundle's manifest and refuses
+ * activation when `evals.textEval.passed` is not `true`. A bundle with no
+ * `eliza-1.manifest.json` on disk (third-party HF GGUFs, external scans,
+ * pre-bundle installs) is *not* gated — the gate only applies to bundles
+ * that ship a published manifest, which is the source of truth for the
+ * publish state.
+ *
+ * Throws `CandidateModelActivationError` on a failing manifest; returns
+ * silently otherwise.
+ */
+export declare function assertManifestEvalsPassed(installed: InstalledModel, manifestLoader?: ManifestLoader): void;
+/**
+ * Refusal raised when activation is asked for a manifest-shipping bundle whose
+ * declared `kernels.required` is missing one of the kernels its tier requires
+ * (`REQUIRED_KERNELS_BY_TIER`). native/CLAUDE.md §3#5 makes this a hard error:
+ * a bundle that doesn't declare its required quant/attention kernels would emit
+ * garbage (or silently fall back to an un-optimized path), so we refuse to
+ * activate it rather than run a broken model.
+ */
+export declare class MissingRequiredKernelsError extends Error {
+    readonly modelId: string;
+    readonly tier: Eliza1Tier;
+    readonly missing: ReadonlyArray<Eliza1Kernel>;
+    constructor(args: {
+        modelId: string;
+        tier: Eliza1Tier;
+        missing: ReadonlyArray<Eliza1Kernel>;
+    });
+}
+/**
+ * Activation kernel gate (native/CLAUDE.md §3#5). When the installed bundle
+ * ships a manifest, verify it declares every kernel its tier requires; throw
+ * `MissingRequiredKernelsError` otherwise. A bundle with no manifest (bare
+ * GGUF, external scan, dev path) is NOT gated — there is no kernel contract to
+ * check, so it is a no-op.
+ */
+export declare function assertRequiredKernelsPresent(installed: InstalledModel, manifestLoader?: ManifestLoader): void;
+export declare class ActiveModelCoordinator {
+    private state;
+    /**
+     * The last model that successfully reached `status: "ready"`, plus the
+     * inputs needed to re-load it. switchTo() tears the active model down
+     * before loading the new one (unload-then-load); if the new load fails we
+     * restore this so a failed switch never leaves the host with zero models
+     * loaded while a working one existed moments earlier. `null` until the
+     * first successful load (or after an unload).
+     */
+    private lastReady;
+    private readonly listeners;
+    snapshot(): ActiveModelState;
+    subscribe(listener: (state: ActiveModelState) => void): () => void;
+    private emit;
+    /**
+     * WS2: one-shot warning latch per (modelId) — when the tier declares
+     * vision but no mmproj GGUF was found on disk, log once so the
+     * operator sees that vision is degraded for this session. The
+     * arbiter's vision-describe capability stays unregistered for this
+     * session; plugin-vision falls back to its non-eliza-1 path.
+     */
+    private readonly warnedDegradedVisionFor;
+    private warnIfVisionDegraded;
+    /** Return the loader service from the current runtime, if registered. */
+    private getLoader;
+    switchTo(runtime: AgentRuntime | null, installed: InstalledModel, overrides?: LocalInferenceLoadOverrides, opts?: {
+        hardware?: HardwareProbe;
+        manifestLoader?: ManifestLoader;
+    }): Promise<ActiveModelState>;
+    /**
+     * Run the unload-then-load against the loader (or standalone engine) and
+     * build the `status: "ready"` state. Throws on any load failure; never
+     * mutates `this.state`/`this.lastReady` so callers control rollback.
+     */
+    private performLoad;
+    unload(runtime: AgentRuntime | null): Promise<ActiveModelState>;
+}
+//# sourceMappingURL=active-model.d.ts.map

package/dist/services/active-model.d.ts.map

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

package/dist/services/asr-provenance.d.ts

@@ -0,0 +1,5 @@
+export declare const QWEN_PROVENANCE_RE: RegExp;
+export declare function collectQwenAsrProvenanceBlockers(input: unknown): string[];
+export declare function readBundleAsrProvenanceBlockers(bundleRoot: string): string[];
+export declare function bundleHasAsrModelFiles(bundleRoot: string): boolean;
+//# sourceMappingURL=asr-provenance.d.ts.map

package/dist/services/asr-provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asr-provenance.d.ts","sourceRoot":"","sources":["../../src/services/asr-provenance.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,kBAAkB,QAAY,CAAC;AAc5C,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAoBzE;AAED,wBAAgB,+BAA+B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAS5E;AAWD,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAQlE"}

package/dist/services/assignments.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Per-ModelType model assignment store.
+ *
+ * Separate from the "active loaded model" concept in `ActiveModelCoordinator`.
+ * Assignments are a *policy* — the user's declared intent that
+ * `ModelType.TEXT_SMALL` should be served by model X and `TEXT_LARGE` by
+ * model Y. The runtime's model handlers lazy-load whichever assignment
+ * fires; the coordinator handles the actual swap in and out of memory.
+ *
+ * Stored in `$ELIZA_STATE_DIR/local-inference/assignments.json`. Cheap
+ * enough to rewrite on every change — we never mutate in place.
+ */
+import type { AgentModelSlot, InstalledModel, ModelAssignments } from "./types";
+/**
+ * Raised when a slot assignment is outside the curated Eliza-1 catalog. The
+ * local stack is Eliza-1 only, so the assignment policy rejects anything else.
+ */
+export declare class AssignmentRejectedError extends Error {
+    readonly code: "ASSIGNMENT_REJECTED";
+    readonly slot: AgentModelSlot;
+    readonly modelId: string;
+    constructor(args: {
+        slot: AgentModelSlot;
+        modelId: string;
+        message: string;
+    });
+}
+export declare function readAssignments(): Promise<ModelAssignments>;
+/**
+ * Build slot recommendations from currently-installed models.
+ *
+ * Only default-eligible Eliza-1 downloads are auto-recommended.
+ * External-scan blobs and ad-hoc Hugging Face downloads are never assigned to
+ * agent slots.
+ *
+ * Why: external blobs may use newer architectures or quant formats outside
+ * the bundled `capacitor-llama` binding's supported set. Auto-loading
+ * an external blob the user never selected silently breaks PROACTIVE_AGENT
+ * and other background tasks at boot. The user opted into the external
+ * tool, not into Eliza loading those weights through llama.cpp.
+ */
+export declare function buildRecommendedAssignments(installed: InstalledModel[]): ModelAssignments;
+export declare function readEffectiveAssignments(): Promise<ModelAssignments>;
+export declare function writeAssignments(assignments: ModelAssignments): Promise<void>;
+export declare function setAssignment(slot: AgentModelSlot, modelId: string | null): Promise<ModelAssignments>;
+/**
+ * Decide which slots a freshly-installed model is a sensible default for.
+ *
+ * Today the curated catalog tags models with `category` ∈
+ * `chat | code | tools | tiny | reasoning` and `bucket` ∈
+ * `small | mid | large | xl` — no explicit "embedding" tag, because the
+ * default catalog ships only generative models. The defensive check below
+ * still recognizes an "embedding" category/bucket for catalog additions and
+ * for external-scan models whose ids contain a recognizable
+ * embedding-family marker (`nomic-embed`, `bge`, `all-minilm`, `gte`,
+ * `e5-`). External GGUFs without a catalog entry default to generative.
+ */
+export declare function isEmbeddingModelId(modelId: string): boolean;
+/**
+ * Fill empty assignment slots with `modelId`. Idempotent: never overwrites
+ * an existing slot. Embedding models only fill `TEXT_EMBEDDING`; generative
+ * models only fill `TEXT_SMALL` and `TEXT_LARGE`. Returns the resulting
+ * assignment map (read state is `readAssignments()`, not effective +
+ * recommended).
+ *
+ * Wired from the downloader's success path and the runtime boot's
+ * "exactly one model installed, no assignments" branch so first-light
+ * users land in chat without a Settings detour. The hard error in
+ * `ensure-local-inference-handler.ts` only fires when the operator has
+ * actively cleared the assignment.
+ */
+export declare function ensureDefaultAssignment(modelId: string): Promise<ModelAssignments>;
+/**
+ * Boot-time helper. If exactly one default-eligible Eliza-1 model is
+ * installed and no assignment file exists yet, auto-fill its slots so
+ * the first session works without the user opening Settings. No-op when
+ * assignments are already present or when more than one default-eligible
+ * model is installed (we cannot guess intent).
+ *
+ * External-scan blobs and custom Hugging Face downloads are intentionally
+ * excluded - see `buildRecommendedAssignments` for the rationale.
+ */
+export declare function autoAssignAtBoot(installed: InstalledModel[]): Promise<ModelAssignments | null>;
+//# sourceMappingURL=assignments.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assignments.d.ts","sourceRoot":"","sources":["../../src/services/assignments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAIhF;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IACjD,QAAQ,CAAC,IAAI,EAAG,qBAAqB,CAAU;IAC/C,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBACb,IAAI,EAAE;QACjB,IAAI,EAAE,cAAc,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KAChB;CAMD;AAoCD,wBAAsB,eAAe,IAAI,OAAO,CAAC,gBAAgB,CAAC,CASjE;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,2BAA2B,CAC1C,SAAS,EAAE,cAAc,EAAE,GACzB,gBAAgB,CAmBlB;AAED,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAS1E;AAED,wBAAsB,gBAAgB,CACrC,WAAW,EAAE,gBAAgB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,wBAAsB,aAAa,CAClC,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,MAAM,GAAG,IAAI,GACpB,OAAO,CAAC,gBAAgB,CAAC,CAkB3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAe3D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,uBAAuB,CAC5C,OAAO,EAAE,MAAM,GACb,OAAO,CAAC,gBAAgB,CAAC,CA4B3B;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACrC,SAAS,EAAE,cAAc,EAAE,GACzB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAclC"}

package/dist/services/backend-selector.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Local-inference backend selector.
+ *
+ * One choice per host process: route generation through the in-process
+ * FFI streaming runner (`ffi-streaming-runner.ts`). The selection is
+ * deterministic so callers can mock it in tests and so no platform falls
+ * back to a server sidecar by accident.
+ *
+ * Rules:
+ *   - Mobile (Android / iOS) ALWAYS uses `ffi-streaming`. The
+ *     `llama-server` child-process path cannot ship on mobile (sandbox
+ *     restrictions, App Store review, ~10–30 ms HTTP round-trip per
+ *     token, no slot persistence on Android's APK private dir). When
+ *     the FFI symbols are absent on a mobile build we throw — there is
+ *     no second backend to fall back to.
+ *   - Desktop also uses `ffi-streaming`. Missing streaming-LLM symbols are
+ *     a bad build, not a reason to start a server backend.
+ *   - `ELIZA_INFERENCE_BACKEND=ffi` forces the streaming runner and
+ *     throws if the symbols are absent. `=auto` (or unset) follows the
+ *     rules above.
+ *
+ * The selector intentionally does NOT inspect the live process to detect
+ * mobile — callers pass that information in. The mobile bootstrap
+ * (`aosp-mtp-adapter.ts` / the iOS bridge) knows what it is; tests
+ * pass synthetic values. Keeping detection out of the selector matches
+ * AGENTS.md §7 (single source of truth for inputs) and lets the
+ * decision be replayed offline.
+ */
+export type LocalInferenceBackend = "ffi-streaming";
+export type LocalInferencePlatform = "desktop" | "mobile";
+export interface BackendSelectInput {
+    /** Where the host is running. */
+    platform: LocalInferencePlatform;
+    /**
+     * `llmStreamSupported()` from the loaded FFI binding. All builds MUST
+     * have this true; false means the runtime was built without the unified
+     * llama.cpp FFI path.
+     */
+    ffiSupported: boolean;
+    /**
+     * Optional env override (`ELIZA_INFERENCE_BACKEND`). `"ffi"` forces
+     * the FFI path, while `"auto"` or unset follows the default rule.
+     */
+    envOverride?: string | null;
+}
+/** Read the `ELIZA_INFERENCE_BACKEND` env var into a normalised value. */
+export declare function readBackendEnvOverride(env?: NodeJS.ProcessEnv): "ffi" | "auto" | null;
+/**
+ * Decide which local-inference backend should service text generation.
+ * See file header for the full rule set. Throws when the chosen
+ * combination is incoherent (no FFI support, explicit FFI with a bad
+ * runtime build, …).
+ */
+export declare function selectBackend(input: BackendSelectInput): LocalInferenceBackend;
+//# sourceMappingURL=backend-selector.d.ts.map