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

package/dist/services/engine.d.ts

@@ -0,0 +1,579 @@
+/**
+ * Standalone llama.cpp engine.
+ *
+ * Fronts the in-process FFI backend (fused `libelizainference`, or the
+ * libllama + eliza-llama-shim fallback) via the `BackendDispatcher`. At most
+ * one model is loaded at a time — model swap is unload-then-load so we never
+ * double-allocate VRAM.
+ *
+ * Two consumption paths:
+ *   1. The Model Hub UI calls `load()` / `unload()` to make "Activate" work.
+ *   2. The agent runtime calls `generate()` via the registered
+ *      `ModelType.TEXT_SMALL` / `TEXT_LARGE` handlers (see
+ *      `ensure-local-inference-handler.ts`).
+ */
+import type { LocalInferenceLoadArgs } from "./active-model";
+import type { GenerateArgs as BackendGenerateArgs, LocalRuntimeLoadConfig } from "./backend";
+import { type ConversationHandle } from "./conversation-registry";
+import { MemoryMonitor } from "./memory-monitor";
+import type { CoordinatorRuntime } from "./voice/cancellation-coordinator";
+import { EngineVoiceBridge, type EngineVoiceBridgeOptions } from "./voice/engine-bridge";
+import type { AsrWordTiming } from "./voice/ffi-bindings";
+import type { VoicePipelineEvents } from "./voice/pipeline";
+import { type MtpTextRunner } from "./voice/pipeline-impls";
+import { SharedResourceRegistry } from "./voice/shared-resources";
+import type { TextToken, TranscriptionAudio, VerifierStreamEvent } from "./voice/types";
+export interface LocalUsageBlock {
+    [key: string]: unknown;
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens: number;
+    cache_read_input_tokens: number;
+    mtp_drafted_tokens?: number;
+    mtp_accepted_tokens?: number;
+    mtp_acceptance_rate?: number;
+    cache_hit_rate?: number;
+}
+export declare function resolveIdleUnloadMs(): number;
+/**
+ * Cap on how many speculative voice responses the turn-controller (W9) may
+ * have in flight at once — derived from the running server's slot count
+ * (each speculative response needs a slot's KV) but never more than half of
+ * them (the other half stays available for confirmed turns + tool calls).
+ * Floors at 1. Override via `ELIZA_LOCAL_MAX_SPECULATIVE_RESPONSES`.
+ */
+export declare function resolveMaxConcurrentSpeculativeResponses(parallelSlots: number): number;
+export type GenerateArgs = BackendGenerateArgs;
+/**
+ * Public engine facade.
+ *
+ * Pre-existing API: `load(modelPath)`, `unload()`, `generate(args)`,
+ * plus the activity probes used by router/handler/active-model code. The
+ * implementation now sits behind the backend dispatcher; the
+ * shape is preserved so callers (active-model, router-handler, the agent
+ * runtime handler) keep working unchanged.
+ *
+ * MTP now lives in the normal optimized llama.cpp backend path. The
+ * dispatcher's decision tree picks `llama-cpp` when a kernel is required
+ * or when the catalog prefers optimized llama.cpp.
+ */
+export declare class LocalInferenceEngine {
+    /**
+     * In-process FFI backend — the sole text runtime, served by the FUSED
+     * `libelizainference` (`desktop-fused-ffi-backend-runtime.ts`). Text gen,
+     * MTP speculative decoding, KV-cache quant, native tokenization,
+     * and vision-describe all run through the one fused lib the voice subsystem
+     * already loads (ABI v9). libllama has been retired: a fused lib that is
+     * absent or lacks the v9 capabilities is a loud `LocalInferenceUnavailable`
+     * error, never a silent fallback. There is no server fallback for Eliza-1.
+     */
+    private readonly ffiBackend;
+    private readonly dispatcher;
+    /**
+     * Active voice-streaming bridge (`EngineVoiceBridge`). Only set when an
+     * Eliza-1 bundle has been activated AND `startVoice()` has succeeded —
+     * see `packages/inference/AGENTS.md` §3 + §4. The engine never lazily
+     * stands up a voice session: callers either start it explicitly or get
+     * a hard error.
+     */
+    private voiceBridge;
+    private voiceReadyPromise;
+    private asrReadyPromise;
+    /**
+     * The general onload/offload coordinator (W10 / J5). One registry per
+     * engine: text + voice both ref-count their shared resources against it,
+     * and every resident model role registers an `EvictableModelRole` here so
+     * the `MemoryMonitor` can walk them ascending-priority under RAM pressure.
+     * The voice bridge gets this passed in (see `startVoice`) so it doesn't
+     * spin up a private one.
+     */
+    private readonly sharedResources;
+    /**
+     * RAM-pressure monitor (J2). Started when a model loads, stopped when the
+     * engine unloads. Evicts the lowest-priority resident role when free RAM
+     * crosses the low-water line.
+     */
+    private readonly memoryMonitor;
+    /** Wall-clock ms of the last `useModel`-style activity. */
+    private lastActivityMs;
+    /** Idle-unload timer (J3); null when disabled or no model loaded. */
+    private idleUnloadTimer;
+    /** Evictable text-target role id registered on `sharedResources`, or null. */
+    private textTargetRoleId;
+    /**
+     * Ids of evictable roles THIS engine registered on `sharedResources`
+     * (text-target today). `getResidentFootprintMb()` sums only these so the
+     * arbiter never double-counts its own vision/image-gen registry roles.
+     */
+    private readonly ownedEvictableRoleIds;
+    /** Best-effort resident footprint for the active text bundle, in MiB. */
+    private textTargetEstimatedMb;
+    /** Evictable drafter role id registered on `sharedResources`, or null. */
+    /**
+     * The active Eliza-1 bundle (root dir + tier id), resolved at `load()`
+     * from the InstalledModel path/id. `null` when the loaded model is not an
+     * Eliza-1 bundle (a user-installed custom). Drives bundle-relative voice
+     * resolution — the Kokoro TTS root and the per-tier EOT turn-detector
+     * revision.
+     */
+    private activeEliza1Bundle;
+    /**
+     * The general onload/offload coordinator for this engine. Exposed so the
+     * voice lifecycle, the embedding route, and any other resident model role
+     * can register an `EvictableModelRole` against the same registry the
+     * `MemoryMonitor` walks under pressure.
+     */
+    getSharedResources(): SharedResourceRegistry;
+    /**
+     * Resident RAM footprint (MB) of the model weights this engine owns on the
+     * shared registry — the active text/embedding bundle today, plus any future
+     * engine-registered role (drafter, voice). This is the term `service.ts`
+     * feeds into the `MemoryArbiter` as `externalFootprintMb` so the arbiter's
+     * proactive `evictToFit` path accounts for the dominant resident consumer
+     * (the text target) instead of seeing only its own vision/image-gen handles
+     * and never tripping (#8809 AC#1). Summed by role id so it never
+     * double-counts the arbiter's own registry roles (vision/image-gen), which
+     * the arbiter already counts in its resident map.
+     */
+    getResidentFootprintMb(): number;
+    /** The RAM-pressure monitor. Exposed for diagnostics / tests. */
+    getMemoryMonitor(): MemoryMonitor;
+    /** Record `useModel`-style activity so the idle-unload timer stays armed. */
+    private markActivity;
+    /**
+     * Once a model is resident: register the text target as an evictable role,
+     * start the memory monitor, and arm the idle-unload timer. Idempotent.
+     */
+    private startBackgroundManagement;
+    /** Stop the memory monitor + idle timer and deregister evictable roles. */
+    private stopBackgroundManagement;
+    private registerResidentRoles;
+    private deregisterResidentRoles;
+    private armIdleUnloadTimer;
+    /**
+     * Cap on concurrent speculative voice responses (W9 / J4): derived from
+     * the running server's slot count (each speculative response needs a KV
+     * slot), never more than half of them, floored at 1. The voice
+     * turn-controller reads this before kicking a speculative response.
+     */
+    maxConcurrentSpeculativeResponses(): number;
+    /**
+     * Auto-tune the running server's `--parallel` (J4): when the conversation
+     * high-water mark has outgrown the configured slot count AND there's RAM
+     * headroom for the extra KV slots, resize/restart llama.cpp with the larger
+     * value so new conversations get their own slot instead of thrashing.
+     * Returns `true` when a resize was performed. No-op when the FFI backend
+     * isn't loaded. Best-effort: a failed restart leaves the old `--parallel`
+     * in place and logs.
+     */
+    maybeAutoResizeParallel(): Promise<boolean>;
+    available(): Promise<boolean>;
+    currentModelPath(): string | null;
+    hasLoadedModel(): boolean;
+    activeBackendId(): "llama-cpp" | null;
+    currentRuntimeLoadConfig(): LocalRuntimeLoadConfig | null;
+    private disposeVoiceBridge;
+    unload(): Promise<void>;
+    load(modelPath: string, resolved?: LocalInferenceLoadArgs): Promise<void>;
+    generate(args: GenerateArgs): Promise<string>;
+    /**
+     * Vision describe via the running llama.cpp mtmd path. Requires the FFI
+     * backend with an mmproj-loaded bundle. The mmproj GGUF must have been
+     * declared by the active catalog tier and present on disk under the
+     * bundle root; if not, the active backend throws.
+     *
+     * No fallback: Florence-2 / Transformers.js was the previous fallback
+     * and has been removed (see VISION_MIGRATION.md).
+     */
+    describeImage(args: {
+        bytes: Uint8Array;
+        mimeType?: string;
+        prompt?: string;
+        maxTokens?: number;
+        temperature?: number;
+        signal?: AbortSignal;
+        /** Per-token callback for streaming vision describe (ABI v13). */
+        onTextChunk?: (chunk: string) => void | Promise<void>;
+        maxTokensPerStep?: number;
+    }): Promise<{
+        text: string;
+        projectorMs?: number;
+        decodeMs?: number;
+    }>;
+    /** True when the active server can serve vision describe (mmproj loaded). */
+    canDescribeImages(): boolean;
+    /**
+     * Diagnostic snapshot of an in-process JS session pool. Always null on the
+     * FFI runtime — its KV slots live in the native backend (C), not in a JS
+     * session pool. Retained so the API cache-stats panel keeps a stable shape.
+     */
+    describeSessionPool(): {
+        size: number;
+        maxSize: number;
+        keys: string[];
+    } | null;
+    /**
+     * Reserve a slot for a long-lived conversation. Subsequent
+     * `generateInConversation` calls reuse the same slot, so the prefix
+     * KV survives across turns regardless of hash collisions with other
+     * concurrent conversations.
+     *
+     * Idempotent for the same (conversationId, modelId): repeated open
+     * calls return the same handle. The runtime side should call this
+     * lazily on the first turn of a conversation and `closeConversation`
+     * when the chat session ends.
+     */
+    openConversation(args: {
+        conversationId: string;
+        modelId: string;
+        ttlMs?: number;
+    }): ConversationHandle;
+    /**
+     * Run one generation pinned to a previously-opened conversation
+     * handle. Cache key, slot id, and (for optimized llama.cpp) kv-restore are
+     * all owned by the registry — callers don't need to thread them.
+     *
+     * Returns the Anthropic-shape `LocalUsageBlock` alongside the text so
+     * agentic callers can surface cache-hit telemetry without re-scraping
+     * `/metrics` themselves.
+     */
+    generateInConversation(handle: ConversationHandle, args: Omit<GenerateArgs, "cacheKey">): Promise<{
+        text: string;
+        usage: LocalUsageBlock;
+        slotId: number;
+    }>;
+    /**
+     * KV-prefill a conversation's pinned slot with a known prompt prefix
+     * (system prompt + provider context + tool/action schema block + the
+     * assistant-turn start), before the real request lands. This is item I1 /
+     * C1 of the voice swarm — fire it the moment a message arrives / STT
+     * starts so the response-handler prompt is already in the slot's KV when
+     * the user's tokens are appended.
+     *
+     * `conversationOrId` may be a `ConversationHandle` (preferred — pins to
+     * the handle's slot) or a raw conversation id (a handle is opened on the
+     * fly so the slot derivation matches the real request). Idempotent /
+     * cheap to call repeatedly: `cache_prompt: true` reuses the prefix so a
+     * second call is a no-op forward pass. Only meaningful once the FFI
+     * backend is loaded — returns false otherwise. Returns true when a
+     * pre-warm request was issued.
+     */
+    prewarmConversation(conversationOrId: ConversationHandle | string, promptPrefix: string, opts?: {
+        modelId?: string;
+    }): Promise<boolean>;
+    /**
+     * Close + drop a conversation handle. Persists the final KV state to
+     * disk so a later open with the same id can lazy-restore. Idempotent;
+     * closing an unknown id is a no-op.
+     */
+    closeConversation(handle: ConversationHandle): Promise<void>;
+    /**
+     * Read-side accessor for the conversation registry. The runtime handler
+     * uses this to look up an existing handle before opening a new one,
+     * avoiding the need to thread a handle through every layer.
+     */
+    conversation(conversationId: string, modelId: string): ConversationHandle | null;
+    /**
+     * Largest concurrent open-conversation count seen this process lifetime.
+     * The auto-tune-parallel path consults this and warns when it exceeds
+     * the running server's slot count.
+     */
+    conversationHighWaterMark(): number;
+    /**
+     * Recommended `--parallel` value given the current conversation
+     * high-water mark plus a small headroom (max(2, 25%)), never below the
+     * running slot count. Delegates to `ConversationRegistry.recommendedParallel`
+     * so the math lives in one place. When this exceeds `parallelSlots()` the
+     * engine can grow the running server (`maybeAutoResizeParallel`).
+     */
+    recommendedParallel(): number;
+    /**
+     * Emit a one-line warning when the running `--parallel` slot count is
+     * below the recommended value (high-water mark + headroom). Returns true
+     * when a warning was emitted. No-op when the FFI backend isn't loaded.
+     * The actual resize is `maybeAutoResizeParallel()`
+     * — kept separate from this hot-path check so a `useModel` call never
+     * blocks on (or is interrupted by) a server restart; the auto-resize is
+     * opted into via `ELIZA_LOCAL_AUTO_RESIZE_PARALLEL=1`, in which case this
+     * also kicks one off fire-and-forget.
+     */
+    warnIfParallelTooLow(logger?: {
+        warn: (msg: string) => void;
+    }): boolean;
+    /**
+     * Start the voice-streaming pipeline against an already-activated
+     * Eliza-1 bundle. Per AGENTS.md §3, voice is mandatory for Eliza-1
+     * tiers — every required artifact (speaker preset, fused FFI when
+     * `useFfiBackend`, bundle root) is checked up front and missing
+     * pieces surface as `VoiceStartupError`. There is no silent fallback
+     * to text-only, no log-and-continue.
+     *
+     * Idempotent guard: starting twice without `stopVoice()` between
+     * surfaces a hard error so callers do not double-allocate the
+     * scheduler.
+     */
+    startVoice(opts: EngineVoiceBridgeOptions): EngineVoiceBridge;
+    /**
+     * True when a voice session is currently active on the engine. Callers
+     * use this to decide whether to lazy-start one (e.g. the TTS model
+     * handler in `ensure-local-inference-handler.ts`, which auto-starts a
+     * Kokoro-only bridge on the first TEXT_TO_SPEECH invocation when the
+     * Kokoro artifacts are on disk and no Eliza-1 bundle has activated).
+     */
+    hasActiveVoiceBridge(): boolean;
+    /**
+     * Arm the voice lifecycle on the active bridge — lazily loads the TTS
+     * mmap region, optional ASR region when present, voice caches, and
+     * voice scheduler nodes via the shared resource registry. Throws
+     * `VoiceLifecycleError` if any
+     * required artifact is unavailable (RAM pressure, mmap fail, kernel
+     * missing) — see `voice/lifecycle.ts` for the structured codes.
+     *
+     * Required before sustained voice use; `startVoice()` only stands up
+     * the cold scheduler and bridge. Splitting setup from arming lets
+     * the engine keep the voice surface in voice-off (no heavy weights
+     * mapped) until the user actually toggles voice on.
+     */
+    armVoice(): Promise<void>;
+    /**
+     * Lazily start + arm voice for the active Eliza-1 bundle. Runtime model
+     * handlers use this when visible chat text needs local speech output; direct
+     * engine callers still use `startVoice()` / `armVoice()` explicitly when they
+     * need custom sinks or test backends.
+     */
+    ensureActiveBundleVoiceReady(): Promise<EngineVoiceBridge>;
+    private activateAssignedBundleForVoice;
+    private localAsrBlockersForBundle;
+    private assertLocalAsrEligible;
+    private assignedLocalAsrBundle;
+    canTranscribeLocally(): Promise<boolean>;
+    ensureActiveBundleAsrReady(): Promise<EngineVoiceBridge>;
+    private ensureActiveBundleAsrReadyOnce;
+    private ensureActiveBundleVoiceReadyOnce;
+    /**
+     * Assemble + run the full live voice loop on top of `startVoice()` /
+     * `armVoice()`: mic → (`pipeMicToRingBuffer` + `VadDetector.pushFrame`)
+     * per frame → `StreamingTranscriber.feed` (VAD-gated) → `VoiceTurnController`
+     * (speculative-on-pause, abort-on-resume, finalize/promote, barge-in) →
+     * `VoiceScheduler` → TTS → audio sink.
+     *
+     * Gated behind a complete real backend chain (AGENTS.md §3 — no silent
+     * backend-mode "voice"):
+     *   - a `MicSource` (caller-supplied, or `DesktopMicSource` under Electrobun),
+     *   - a Silero v5 GGML VAD (caller-supplied detector, or `createSileroVadDetector()` — runs through libelizainference's native VAD ABI),
+     *   - a working ASR (the bridge's `createStreamingTranscriber` throws
+     *     `AsrUnavailableError` when the fused decoder is unavailable — the
+     *     fused build is the sole on-device ASR runtime),
+     *   - a real OmniVoice TTS backend on the bridge (the `StubOmniVoiceBackend`
+     *     is rejected — it emits zeros).
+     * Any missing piece fails loudly with the specific component named.
+     *
+     * `prewarm` defaults to `this.prewarmConversation(roomId, "")` (best-effort
+     * KV-prefill); a caller with the response-handler stable prefix (W6) should
+     * pass its own. `generate` is required — it builds the message and runs the
+     * runtime turn (streaming `replyText` into TTS via this engine's
+     * `generate({ onTextChunk })`, which routes through the voice scheduler).
+     */
+    startVoiceSession(opts: {
+        roomId: string;
+        /** Mic source. Defaults to a `DesktopMicSource` (Electrobun). */
+        micSource?: import("./voice/types").MicSource;
+        /** VAD detector. Defaults to `createSileroVadDetector()`. */
+        vad?: import("./voice/vad").VadDetector;
+        /** Run one turn: build the message + stream `replyText` into TTS. Required. */
+        generate: (request: import("./voice/turn-controller").VoiceGenerateRequest) => Promise<import("./voice/turn-controller").VoiceTurnOutcome>;
+        /**
+         * Semantic turn detector layered with VAD/STT. Defaults to the local
+         * LiveKit ONNX model when installed, otherwise the deterministic heuristic.
+         * Pass `false` only for tests/manual troubleshooting.
+         */
+        turnDetector?: import("./voice/eot-classifier").EotClassifier | false;
+        /** Optional local LiveKit turn-detector directory override. */
+        turnDetectorModelDir?: string;
+        /**
+         * Use the already-loaded eliza-1 text model as the EOT classifier — see
+         * `voice/eliza1-eot-scorer.ts`. When set, the runtime skips the
+         * separate LiveKit/Turnsense ONNX and reads P(`<end_of_turn>`) directly
+         * off the live model.
+         *
+         * `"auto"` (default): use eliza-1 EOT when `ELIZA_VOICE_EOT_BACKEND=eliza-1`
+         * or when no bundled LiveKit ONNX is resolvable; otherwise fall
+         * through to the existing LiveKit path. `true` forces eliza-1 EOT
+         * (throws if the active backend is not in-process). `false` forces
+         * the historical LiveKit path.
+         */
+        useEliza1Eot?: boolean | "auto";
+        /**
+         * Optional path to a fine-tuned EOT LoRA adapter to layer on top of
+         * the drafter at scoring time. The training recipe lives in
+         * `packages/training/scripts/turn_detector/`.
+         */
+        eliza1EotLoraPath?: string;
+        /** KV-prefill / response-handler-prefix prewarm. Defaults to `prewarmConversation`. */
+        prewarm?: (roomId: string) => void | Promise<void>;
+        speculatePauseMs?: number;
+        events?: import("./voice/turn-controller").VoiceTurnControllerEvents;
+        /**
+         * Opt-in openWakeWord hotword gate (local mode only — the
+         * local-inference engine never runs in cloud mode, and the connector
+         * UI hides this surface there per AGENTS.md §5 hide-not-disable).
+         * Disabled by default: voice mode works push-to-talk / VAD-gated
+         * without it. When `enabled` and the bundle ships the openWakeWord
+         * graphs, mic frames are also fanned into an `OpenWakeWordDetector`;
+         * each fresh detection prewarms the conversation and calls `onWake`
+         * (the same place a push-to-talk press would arm a listening window).
+         * Silently inert when the bundle has no wake-word model.
+         */
+        wakeWord?: {
+            enabled: boolean;
+            /** Wake phrase head name (defaults to the bundle's `hey-eliza`). */
+            head?: string;
+            /** P(wake) firing threshold (openWakeWord default ~0.5). */
+            threshold?: number;
+            /** Called once per detected utterance (refractory-debounced). */
+            onWake?: () => void;
+        };
+        /**
+         * Runtime reference for cancellation coordination (W3-9 F1).
+         *
+         * @deprecated G5.d: pass `runtime` to `startVoice()` (the
+         * `EngineVoiceBridgeOptions`) instead. The bridge is the canonical
+         * owner of `VoiceCancellationCoordinator` + `OptimisticGenerationPolicy`,
+         * and `startVoiceSession()` now delegates to the bridge's coordinator.
+         * When this field is supplied here without a matching bridge-level
+         * runtime, `startVoiceSession()` logs once and ignores it — the
+         * canonical wiring lives on the bridge.
+         */
+        runtime?: CoordinatorRuntime;
+    }): Promise<import("./voice/turn-controller").VoiceTurnController>;
+    /**
+     * Disarm the voice lifecycle — drains the ring buffer, settles the
+     * scheduler, and drops TTS/ASR weights from RAM via `evictPages()`
+     * (madvise / VirtualUnlock equivalent — see voice/engine-bridge.ts).
+     * No-op when not armed.
+     */
+    disarmVoice(): Promise<void>;
+    /**
+     * Tear down the active voice bridge. Idempotent; calling when no
+     * voice session is active is a no-op. Disarms the lifecycle first
+     * (drops voice weights via `evictPages`), then settles any in-flight
+     * TTS so audio committed to the ring buffer surfaces to the sink
+     * before the bridge is dropped.
+     */
+    stopVoice(): Promise<void>;
+    synthesizeSpeech(text: string, signal?: AbortSignal): Promise<Uint8Array>;
+    prewarmVoicePhrases(texts: ReadonlyArray<string>, opts?: {
+        concurrency?: number;
+    }): Promise<{
+        warmed: number;
+        cached: number;
+    }>;
+    /**
+     * Idle-time auto-prewarm: synthesize the canonical common-phrase seed so
+     * the phrase cache is warm before the next turn. No-op unless a real TTS
+     * backend is present and voice is armed. Callers (the voice bridge /
+     * connector) invoke this when the loop is idle.
+     */
+    prewarmIdleVoicePhrases(opts?: {
+        concurrency?: number;
+    }): Promise<{
+        warmed: number;
+        cached: number;
+    }>;
+    /**
+     * Play the first-audio filler (a short cached acknowledgement) — the seam
+     * W9's turn controller calls the instant VAD fires `speech-start` to mask
+     * first-token latency. Returns the played filler text, or `null` if none
+     * was played. No-op without a real TTS backend / armed voice.
+     */
+    playFirstAudioFiller(): string | null;
+    transcribePcm(args: TranscriptionAudio, signal?: AbortSignal, onPartial?: (delta: string) => void): Promise<string>;
+    /** Transcribe + per-word timings (fused ASR v12) through the voice bridge. */
+    transcribePcmTimed(args: TranscriptionAudio, signal?: AbortSignal): Promise<{
+        text: string;
+        words: AsrWordTiming[];
+    }>;
+    /**
+     * Run one fused mic→speech voice turn through the overlapped
+     * `VoicePipeline`: ASR → {MTP drafts ∥ target verifies} → phrase
+     * chunker → OmniVoice → PCM ring buffer, with rollback-on-reject and
+     * barge-in cancel. Requires `startVoice()` + `armVoice()` first.
+     *
+     * `opts.textRunner` lets a host that runs its own text engine in-process
+     * (the iOS/Android FFI path or the desktop FFI runtime) supply its own
+     * {@link MtpTextRunner}. When omitted, the active local dispatcher is
+     * used.
+     *
+     * Production caller: the on-device device bridge, via `runDeviceVoiceTurn`
+     * (`adapters/capacitor-llama/voice-turn.ts`), which wraps the loaded
+     * `CapacitorLlamaContext` in an `MtpTextRunner` and passes it here so the
+     * draft/verify loop runs on the on-device text model. The native mic
+     * capture hands `runDeviceVoiceTurn` the PCM; everything downstream is
+     * in-process JS + the fused FFI (no HTTP, no second voice path).
+     *
+     * Resolves with the turn's exit reason (`done` / `token-cap` /
+     * `cancelled`). A missing ASR region in voice mode surfaces as a
+     * `VoiceStartupError` — no silent cloud fallback (AGENTS.md §3).
+     */
+    runVoiceTurn(audio: TranscriptionAudio, opts?: {
+        maxDraftTokens?: number;
+        maxGeneratedTokens?: number;
+        events?: VoicePipelineEvents;
+        /**
+         * In-process text runner for the mobile FFI path. Must implement the
+         * same `MtpTextRunner` contract (`hasDrafter()` +
+         * `generateWithVerifierEvents()`); the AOSP/Capacitor bridge wraps
+         * its libllama-context-backed speculative loop in one.
+         */
+        textRunner?: MtpTextRunner;
+    }): Promise<"done" | "token-cap" | "cancelled">;
+    /**
+     * Active voice bridge, or null when voice mode is not running.
+     * Callers (router, UI, agent runtime) read this to decide whether to
+     * forward verifier events. Voice is mandatory for Eliza-1 tiers but
+     * the bridge is still created lazily — `startVoice()` MUST be called
+     * before `voice()` returns non-null.
+     */
+    voice(): EngineVoiceBridge | null;
+    private requireVoiceBridge;
+    private voiceStreamingArgs;
+    /**
+     * Forward a verifier-stream event into the voice scheduler. Accepted tokens flow into the
+     * phrase chunker; rejected ranges trigger the rollback queue. No-op
+     * when voice is not active so callers can fan out events
+     * unconditionally.
+     *
+     * When MTP produces an accepted text token, the phrase chunker MUST hand
+     * the chunk to TTS within the same scheduler tick.
+     */
+    pushVerifierEvent(event: VerifierStreamEvent): Promise<void>;
+    /**
+     * Mic VAD → barge-in. Per AGENTS.md §4, the PCM ring buffer MUST
+     * drain immediately and any in-flight TTS forward pass MUST be
+     * cancelled at the next kernel boundary. The scheduler enforces both
+     * — this is a thin pass-through.
+     */
+    triggerBargeIn(): void;
+    /**
+     * Test surface: fan an accepted-token list into the bridge in one
+     * call. Production callers should prefer `pushVerifierEvent` so the
+     * accept/reject discriminator stays explicit; this exists so the
+     * voice integration test can drive the scheduler without
+     * reconstructing `VerifierStreamEvent` boilerplate.
+     */
+    pushAcceptedTokens(tokens: ReadonlyArray<TextToken>): Promise<void>;
+    /**
+     * Active llama.cpp parallel slot count from the running FFI backend, or
+     * the configured default pool size when no model is loaded yet.
+     */
+    private activeParallel;
+    /**
+     * The in-process `Eliza1EotClassifier` required a node-bound `LlamaModel`
+     * forward pass, which the FFI runtime does not expose. Always null now —
+     * callers fall through to the GGUF (FFI) turn-detector and then the
+     * heuristic chain.
+     */
+    private tryBuildEliza1EotClassifier;
+}
+export declare const localInferenceEngine: LocalInferenceEngine;
+//# sourceMappingURL=engine.d.ts.map

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

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

package/dist/services/ensure-local-artifacts.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Orchestrator for the on-device artifact bundle the local-only / local
+ * runtime needs to operate: embedding, TTS, STT, and (when the user is not
+ * signed into Eliza Cloud) the text model. Called from:
+ *
+ *   - `runtime/ensure-local-inference-handler.ts` — fire-and-forget at agent
+ *     boot whenever the resolved runtime mode is `local` or `local-only`.
+ *   - `ui/src/first-run/auto-download-recommended.ts` — when the user picks
+ *     "Local" in the first-run runtime setup, after the local agent's
+ *     `/api/health` reports ready.
+ *   - `POST /api/local-inference/ensure` — on-demand re-trigger from the
+ *     settings UI / a CLI.
+ *
+ * Today every Eliza-1 tier ships every component (text + voice + asr +
+ * embedding + embedded-draft-head MTP metadata + cache) as one HuggingFace bundle. The
+ * orchestrator picks a tier per artifact kind (always the same tier today —
+ * tier resolution is centralised on the recommender) and triggers parallel
+ * `service.startDownload(modelId)` calls per kind. The downloader is
+ * idempotent on the same `modelId`, so when the same tier covers multiple
+ * kinds we end up with one bundle download and a per-kind audit trail.
+ *
+ * When the architecture splits the bundle into separately addressable
+ * sub-archives, the per-kind selection in {@link modelIdForKind} is where the
+ * per-modality model id diverges — the rest of the orchestrator already wraps
+ * each artifact in its own `Promise.allSettled` slot.
+ *
+ * `signedInCloud === true` skips the `text` artifact: cloud-routed inference
+ * handles TEXT_LARGE / TEXT_SMALL, and we don't want a multi-gig text weight
+ * download imposed on a user who chose cloud routing. Embedding / TTS / STT
+ * always download — the local runtime serves those locally regardless of
+ * whether the text model is cloud-routed.
+ */
+import type { Eliza1Tier } from "./manifest";
+import type { LocalInferenceService } from "./service";
+type RuntimeMode = "local" | "local-only" | "cloud" | "remote";
+/**
+ * Artifact kinds the orchestrator can trigger. The label is consumer-facing
+ * (logs / API responses) and is intentionally distinct from the catalog's
+ * `ModelCategory` — the catalog labels a full chat tier as `"chat"`, while
+ * here we describe the on-device modality the artifact serves.
+ */
+export type EnsureLocalArtifactKind = "embedding" | "tts" | "stt" | "text";
+export type EnsureLocalArtifactStatus = "started" | "already-installed" | "skipped" | "failed";
+export interface EnsureLocalArtifactOutcome {
+    kind: EnsureLocalArtifactKind;
+    modelId: string;
+    status: EnsureLocalArtifactStatus;
+    /** Free-text disambiguation. Populated for skipped / failed outcomes. */
+    reason?: string;
+}
+export interface EnsureLocalArtifactsArgs {
+    /** Resolved runtime mode (local | local-only | cloud | remote). */
+    mode: RuntimeMode;
+    /** Optional tier override; if omitted, picked from the device hardware probe. */
+    tier?: Eliza1Tier;
+    /** True when the user is signed into Eliza Cloud. Suppresses the text artifact. */
+    signedInCloud: boolean;
+    /** Optional service facade override (tests). */
+    service?: LocalInferenceService;
+    /** Optional logger. */
+    logger?: {
+        info: (...a: unknown[]) => void;
+        warn: (...a: unknown[]) => void;
+    };
+}
+export interface EnsureLocalArtifactsResult {
+    artifacts: EnsureLocalArtifactOutcome[];
+    /**
+     * True iff every required artifact is now either installed or actively
+     * downloading. False when any artifact slot failed; the per-artifact
+     * outcome carries the reason.
+     */
+    complete: boolean;
+}
+/**
+ * Trigger the parallel downloads of every artifact the local runtime needs
+ * to operate on this device. See the module docstring for the per-mode /
+ * per-cloud-state contract.
+ */
+export declare function ensureLocalArtifacts(args: EnsureLocalArtifactsArgs): Promise<EnsureLocalArtifactsResult>;
+export {};
+//# sourceMappingURL=ensure-local-artifacts.d.ts.map