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

package/src/services/engine-direct-bundle.test.ts

@@ -0,0 +1,58 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import type { BackendPlan } from "./backend";
+import { LocalInferenceEngine } from "./engine";
+
+const ORIGINAL_ENV = { ...process.env };
+
+afterEach(() => {
+	process.env = { ...ORIGINAL_ENV };
+});
+
+describe("LocalInferenceEngine direct Eliza-1 bundle loads", () => {
+	it("projects modelId into catalog and bundle overrides before registry install", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "eliza-engine-test-"));
+		process.env.ELIZA_STATE_DIR = root;
+		const engine = new LocalInferenceEngine();
+		const internals = engine as unknown as {
+			dispatcher: {
+				load(plan: BackendPlan): Promise<void>;
+			};
+		};
+		let captured: BackendPlan | undefined;
+		internals.dispatcher.load = async (plan) => {
+			captured = plan;
+		};
+
+		const bundleRoot = path.join(root, "eliza-1-0_8b.bundle");
+		const modelPath = path.join(bundleRoot, "text", "eliza-1-0_8b-128k.gguf");
+		await engine.load(modelPath, {
+			modelPath,
+			modelId: "eliza-1-0_8b",
+		});
+
+		expect(captured).toBeDefined();
+		expect(captured?.modelPath).toBe(modelPath);
+		expect(captured?.modelId).toBe("eliza-1-0_8b");
+		expect(captured?.catalog?.id).toBe("eliza-1-0_8b");
+		expect(captured?.overrides?.bundleRoot).toBe(bundleRoot);
+		expect(captured?.overrides?.manifestPath).toBe(
+			path.join(bundleRoot, "eliza-1.manifest.json"),
+		);
+		expect(
+			(
+				engine as unknown as {
+					activeEliza1Bundle: { root?: string; tierId?: string } | null;
+				}
+			).activeEliza1Bundle,
+		).toEqual(
+			expect.objectContaining({
+				root: bundleRoot,
+				tierId: "eliza-1-0_8b",
+			}),
+		);
+	});
+});

package/src/services/engine-streaming.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+
+import type { GenerateArgs } from "./backend";
+import { LocalInferenceEngine } from "./engine";
+
+/**
+ * Regression guard for local chat token streaming through the engine facade.
+ *
+ * The chat reply path forces a per-turn grammar (the Stage-1 HANDLE_RESPONSE
+ * envelope) and asks for `streamStructured`. The runtime wires
+ * `params.onStreamChunk` down to the engine's `onTextChunk`, and the
+ * `ResponseSkeletonStreamExtractor` slices the `replyText` field out of the
+ * streamed JSON. For that to surface incremental deltas, the per-token
+ * callback MUST fire once per chunk all the way through the dispatcher — not
+ * collapse into a single final chunk.
+ */
+
+const REPLY_TOKENS = [
+	'{"shouldRespond":"RESPOND",',
+	'"contexts":["simple"],',
+	'"replyText":"On ',
+	"it ",
+	'now.","facts":[]}',
+];
+
+// A minimal GBNF source — only its presence matters. This mirrors the Stage-1
+// reply path always carrying a grammar.
+const FORCED_GRAMMAR = 'root ::= "{" [^}]* "}"';
+
+describe("LocalInferenceEngine.generateInConversation streaming (chat path)", () => {
+	it("forwards onTextChunk per token through the dispatcher when voice is off", async () => {
+		// The production chat reply has a conversationId, so the local handler
+		// routes through `generateInConversation` (NOT `engine.generate`). With no
+		// voice bridge active, `voiceStreamingArgs` is a passthrough, so the
+		// dispatcher must receive — and the backend must fire — `onTextChunk`
+		// per token. This is the junction the FFI-backed unit tests don't cover.
+		const engine = new LocalInferenceEngine();
+		const seenChunks: string[] = [];
+
+		const internals = engine as unknown as {
+			dispatcher: {
+				generate: (args: GenerateArgs) => Promise<string>;
+				activeBackendId: () => string | null;
+			};
+			currentModelPath: () => string | null;
+		};
+		// Drive the non-"llama-cpp" branch of generateInConversation (the
+		// usage-block-synthesizing forward path) by reporting no active FFI
+		// backend while still stubbing dispatcher.generate.
+		internals.dispatcher.activeBackendId = () => null;
+		internals.currentModelPath = () => "fake-model";
+		internals.dispatcher.generate = async (args: GenerateArgs) => {
+			// Simulate the backend firing the per-token callback.
+			for (const token of REPLY_TOKENS) {
+				await args.onTextChunk?.(token);
+			}
+			return REPLY_TOKENS.join("");
+		};
+
+		const handle = engine.openConversation({
+			conversationId: "conv-stream-test",
+			modelId: "fake-model",
+		});
+
+		const result = await engine.generateInConversation(handle, {
+			prompt: "say hi",
+			grammar: FORCED_GRAMMAR,
+			streamStructured: true,
+			onTextChunk: (chunk) => {
+				seenChunks.push(chunk);
+			},
+		});
+
+		expect(seenChunks).toEqual(REPLY_TOKENS);
+		expect(seenChunks.length).toBeGreaterThan(1);
+		expect(result.text).toBe(REPLY_TOKENS.join(""));
+
+		await engine.closeConversation(handle);
+	});
+});

package/src/services/engine.d.ts

@@ -0,0 +1,540 @@
+/**
+ * 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,
+     * same-file 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;
+    /**
+     * 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;
+    /** 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;
+    /** 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(): "capacitor-llama" | "llama-cpp" | null;
+    currentRuntimeLoadConfig(): LocalRuntimeLoadConfig | null;
+    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;
+    }): 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 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(`<|im_end|>`) 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): 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.
+     *
+     * 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