@elizaos/app-core 2.0.0-alpha.85 → 2.0.0-beta.2

package/services/local-inference/voice/engine-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-bridge.d.ts","sourceRoot":"","sources":["../../../../../../../src/services/local-inference/voice/engine-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,EACV,2BAA2B,EAC3B,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAEL,sBAAsB,EACvB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EACT,gBAAgB,EAChB,MAAM,EACN,kBAAkB,EAElB,aAAa,EACb,SAAS,EACV,MAAM,SAAS,CAAC;AAOjB;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EACT,aAAa,GACb,wBAAwB,GACxB,qBAAqB,GACrB,qBAAqB,GACrB,iBAAiB,GACjB,aAAa,CAAC;gBAGhB,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,EAC/B,OAAO,EAAE,MAAM;CAMlB;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,YAAW,gBAAgB;IAC3D,QAAQ,CAAC,EAAE,EAAG,MAAM,CAAU;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,KAAK,SAAK;gBAEE,UAAU,SAAsB;IAItC,UAAU,CAAC,IAAI,EAAE;QACrB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,aAAa,CAAC;QACtB,YAAY,EAAE;YAAE,SAAS,EAAE,OAAO,CAAA;SAAE,CAAC;QACrC,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;KAC3B,GAAG,OAAO,CAAC,UAAU,CAAC;CAexB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,mBAAoB,YAAW,gBAAgB;IAC1D,QAAQ,CAAC,EAAE,EAAG,KAAK,CAAU;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAoB;IACxC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA8B;IAClD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;gBAEjC,IAAI,EAAE;QAChB,GAAG,EAAE,iBAAiB,CAAC;QACvB,GAAG,EAAE,2BAA2B,CAAC;QACjC,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAC9B;IAOK,UAAU,CAAC,IAAI,EAAE;QACrB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,aAAa,CAAC;QACtB,YAAY,EAAE;YAAE,SAAS,EAAE,OAAO,CAAA;SAAE,CAAC;QACrC,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;KAC3B,GAAG,OAAO,CAAC,UAAU,CAAC;CAiBxB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;IACpD;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,oEAAoE;IACpE,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,gBAAgB,CAAC;IACnC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,sBAAsB,CAAC;IACzC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;CAC1C;AAED;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACvC,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,2BAA2B,GAAG,IAAI,CAAC;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,OAAO;IAgBP;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAOf;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,wBAAwB,GAAG,iBAAiB;IA0G/D;;;;;;OAMG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAK1B;;;;;;OAMG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAM7B;;;;OAIG;IACG,iBAAiB,CACrB,KAAK,EAAE,SAAS,EAChB,UAAU,SAAa,GACtB,OAAO,CAAC,IAAI,CAAC;IAIhB;;;;;;OAMG;IACG,iBAAiB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjE;;;;;;OAMG;IACH,cAAc,IAAI,IAAI;IAItB;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAK7B,qEAAqE;IACrE,UAAU,IAAI,MAAM;CAGrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,iBAAS,uBAAuB,CAC9B,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,iBAAiB,GAAG,IAAI,EAC7B,GAAG,EAAE,2BAA2B,GAAG,IAAI,GACtC,qBAAqB,CAuBvB;AAkDD,uEAAuE;AACvE,OAAO,EAAE,uBAAuB,EAAE,CAAC"}

package/services/local-inference/voice/engine-bridge.js

@@ -0,0 +1,398 @@
+/**
+ * Engine ↔ voice scheduler bridge.
+ *
+ * Adapts the live `LocalInferenceEngine` (`engine.ts`) plus the DFlash
+ * llama-server (`dflash-server.ts`) onto the voice scaffold's
+ * `VoiceScheduler`. See `packages/inference/AGENTS.md` §4 for the
+ * streaming graph this implements:
+ *
+ *   ASR → text tokens → DFlash drafter ↔ target verifier (text model)
+ *        → phrase chunker → speaker preset cache + phrase cache
+ *        → OmniVoice TTS → PCM ring buffer → audio out
+ *
+ * Plus rollback queue (DFlash rejection → cancel pending TTS chunks)
+ * and barge-in cancellation (mic VAD → drain ring buffer + cancel TTS).
+ *
+ * Two TTS backends are exposed:
+ *   - `StubOmniVoiceBackend`: deterministic synthetic PCM. Used by tests
+ *     and any path that wants the streaming graph without real audio.
+ *   - `FfiOmniVoiceBackend`: documents the planned FFI surface against
+ *     `libelizainference.{dylib,so}`. Throws a hard "not implemented"
+ *     error on every call until the fused omnivoice build target lands
+ *     (see `packages/app-core/scripts/build-llama-cpp-dflash.mjs` for
+ *     the fused-target build hook the other agent finished).
+ *
+ * Per AGENTS.md §3 + §9 (no defensive code, no log-and-continue), every
+ * startup precondition surfaces as a thrown `VoiceStartupError`. There
+ * is no silent fallback to text-only.
+ */
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
+import { loadElizaInferenceFfi } from "./ffi-bindings";
+import { VoiceLifecycle, } from "./lifecycle";
+import { PhraseCache, } from "./phrase-cache";
+import { SharedResourceRegistry, } from "./shared-resources";
+import { SpeakerPresetCache } from "./speaker-preset-cache";
+import { VoiceScheduler } from "./scheduler";
+const SAMPLE_RATE_DEFAULT = 24_000;
+const RING_BUFFER_CAPACITY_DEFAULT = SAMPLE_RATE_DEFAULT * 4; // 4s
+const PHRASE_MAX_TOKENS_DEFAULT = 12;
+const STUB_PCM_MS_PER_PHRASE = 100;
+/**
+ * Structured startup failure. The engine MUST throw one of these when
+ * voice mode is requested but cannot start (missing FFI, missing speaker
+ * preset, missing fused build, manifest mismatch). The runtime then
+ * refuses to activate the model — never silently degrades to text-only.
+ */
+export class VoiceStartupError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "VoiceStartupError";
+        this.code = code;
+    }
+}
+/**
+ * Stub TTS backend that returns deterministic synthetic PCM. Each phrase
+ * yields `STUB_PCM_MS_PER_PHRASE` ms of silence (zeros), with the
+ * cancel signal honoured at the kernel-tick boundary so barge-in tests
+ * observe cancellation without waiting on a real model.
+ */
+export class StubOmniVoiceBackend {
+    id = "stub";
+    sampleRate;
+    calls = 0;
+    constructor(sampleRate = SAMPLE_RATE_DEFAULT) {
+        this.sampleRate = sampleRate;
+    }
+    async synthesize(args) {
+        this.calls++;
+        args.onKernelTick?.();
+        const samples = Math.floor((this.sampleRate * STUB_PCM_MS_PER_PHRASE) / 1000);
+        const pcm = new Float32Array(samples);
+        return {
+            phraseId: args.phrase.id,
+            fromIndex: args.phrase.fromIndex,
+            toIndex: args.phrase.toIndex,
+            pcm,
+            sampleRate: this.sampleRate,
+        };
+    }
+}
+/**
+ * FFI-backed TTS backend. Forwards each `synthesize()` call through the
+ * fused `libelizainference` ABI declared in
+ * `packages/app-core/scripts/omnivoice-fuse/ffi.h`. The library handle
+ * + a per-engine context pointer are held by the bridge and passed in
+ * at construction so this backend stays a thin adapter.
+ *
+ * Until the real fused build ships, the binding is exercised against
+ * the C stub at `scripts/omnivoice-fuse/ffi-stub.c`, which returns
+ * `ELIZA_ERR_NOT_IMPLEMENTED` for `tts_synthesize` — the binding then
+ * raises `VoiceLifecycleError({code:"kernel-missing"})`. The adapter
+ * re-wraps that as `VoiceStartupError("missing-fused-build", ...)` so
+ * the engine layer's startup-error taxonomy stays unified. No silent
+ * fallback (AGENTS.md §3 + §9).
+ */
+export class FfiOmniVoiceBackend {
+    id = "ffi";
+    ffi;
+    ctx;
+    sampleRate;
+    maxSecondsPerPhrase;
+    constructor(args) {
+        this.ffi = args.ffi;
+        this.ctx = args.ctx;
+        this.sampleRate = args.sampleRate ?? SAMPLE_RATE_DEFAULT;
+        this.maxSecondsPerPhrase = args.maxSecondsPerPhrase ?? 6;
+    }
+    async synthesize(args) {
+        args.onKernelTick?.();
+        const out = new Float32Array(this.sampleRate * this.maxSecondsPerPhrase);
+        const samples = this.ffi.ttsSynthesize({
+            ctx: this.ctx,
+            text: args.phrase.text,
+            speakerPresetId: args.preset.voiceId,
+            out,
+        });
+        return {
+            phraseId: args.phrase.id,
+            fromIndex: args.phrase.fromIndex,
+            toIndex: args.phrase.toIndex,
+            pcm: out.subarray(0, samples),
+            sampleRate: this.sampleRate,
+        };
+    }
+}
+/**
+ * Wires the voice scaffold (`VoiceScheduler` + helpers) onto the engine.
+ * One bridge per active voice session — created in
+ * `LocalInferenceEngine.startVoice()` and disposed when the engine
+ * unloads or `stopVoice()` is called.
+ */
+export class EngineVoiceBridge {
+    scheduler;
+    backend;
+    lifecycle;
+    /** Loaded FFI handle when running against the fused build (else null). */
+    ffi;
+    /** FFI context this bridge owns; destroyed in `dispose()`. */
+    ffiCtx;
+    bundleRoot;
+    constructor(scheduler, backend, bundleRoot, lifecycle, ffi, ffiCtx) {
+        this.scheduler = scheduler;
+        this.backend = backend;
+        this.bundleRoot = bundleRoot;
+        this.lifecycle = lifecycle;
+        this.ffi = ffi;
+        this.ffiCtx = ffiCtx;
+    }
+    /**
+     * Tear down the FFI context the bridge owns. Idempotent; safe to call
+     * multiple times. Callers should `disarm()` first to drop voice
+     * resources, then `dispose()` to close the FFI handle.
+     */
+    dispose() {
+        if (this.ffi && this.ffiCtx !== null) {
+            this.ffi.destroy(this.ffiCtx);
+            this.ffi.close();
+        }
+    }
+    /**
+     * Start the voice session for a bundle. Validates the bundle layout
+     * up-front (per AGENTS.md §3 + §7 — required artifacts checked before
+     * activation) and throws `VoiceStartupError` for any missing piece.
+     * No partial activation: either the scheduler exists and is wired or
+     * the call throws.
+     */
+    static start(opts) {
+        if (!opts.bundleRoot || !existsSync(opts.bundleRoot)) {
+            throw new VoiceStartupError("missing-bundle-root", `[voice] Bundle root does not exist: ${opts.bundleRoot}`);
+        }
+        const presetPath = path.join(opts.bundleRoot, "cache", "voice-preset-default.bin");
+        if (!existsSync(presetPath)) {
+            throw new VoiceStartupError("missing-speaker-preset", `[voice] Bundle is missing required speaker preset at ${presetPath}. The default voice MUST ship as a precomputed embedding (AGENTS.md §4).`);
+        }
+        const sampleRate = opts.sampleRate ?? SAMPLE_RATE_DEFAULT;
+        const presetCache = new SpeakerPresetCache();
+        const { preset, phrases: seedPhrases } = presetCache.loadFromBundle({
+            bundleRoot: opts.bundleRoot,
+        });
+        const phraseCache = new PhraseCache();
+        phraseCache.seed(seedPhrases);
+        for (const entry of opts.prewarmedPhrases ?? []) {
+            phraseCache.put(entry);
+        }
+        // FFI binding + per-bridge context. When the bridge runs against
+        // the real fused build, the same `ffi`/`ctx` pair is shared by:
+        //   - the TTS backend (`FfiOmniVoiceBackend.synthesize`),
+        //   - the lifecycle loaders (`MmapRegionHandle.evictPages` calls
+        //     `ffi.mmapEvict(ctx, "tts" | "asr")`).
+        // Tests can opt out by either passing `lifecycleLoaders` (mocks
+        // `evictPages`) or `backendOverride` (mocks the backend) or
+        // setting `useFfiBackend: false` (stub TTS + no-op evict).
+        let ffiHandle = null;
+        let ffiCtx = null;
+        let backend;
+        if (opts.backendOverride) {
+            backend = opts.backendOverride;
+        }
+        else if (opts.useFfiBackend) {
+            const libPath = path.join(opts.bundleRoot, "lib", libraryFilename());
+            if (!existsSync(libPath)) {
+                throw new VoiceStartupError("missing-ffi", `[voice] Fused omnivoice library not found at ${libPath}. Build via packages/app-core/scripts/build-llama-cpp-dflash.mjs (omnivoice-fuse target).`);
+            }
+            ffiHandle = loadElizaInferenceFfi(libPath);
+            ffiCtx = ffiHandle.create(opts.bundleRoot);
+            backend = new FfiOmniVoiceBackend({
+                ffi: ffiHandle,
+                ctx: ffiCtx,
+                sampleRate,
+            });
+        }
+        else {
+            backend = new StubOmniVoiceBackend(sampleRate);
+        }
+        const config = {
+            chunkerConfig: {
+                maxTokensPerPhrase: opts.maxTokensPerPhrase ?? PHRASE_MAX_TOKENS_DEFAULT,
+            },
+            preset,
+            ringBufferCapacity: opts.ringBufferCapacity ?? RING_BUFFER_CAPACITY_DEFAULT,
+            sampleRate,
+        };
+        const sinkOverride = opts.sink;
+        const scheduler = new VoiceScheduler(config, sinkOverride
+            ? { backend, sink: sinkOverride, phraseCache }
+            : { backend, phraseCache }, opts.events ?? {});
+        // Wire the voice lifecycle. The lifecycle starts in `voice-off` —
+        // heavy resources (TTS + ASR mmap regions) are loaded only when
+        // `arm()` is called. The default loaders derive an mmap-style
+        // handle from the bundle's `tts/` and `asr/` directories so that
+        // production paths get real eviction calls; tests inject
+        // `lifecycleLoaders` to assert the disarm path.
+        const registry = opts.sharedResources ?? new SharedResourceRegistry();
+        const loaders = opts.lifecycleLoaders ??
+            defaultLifecycleLoaders(opts.bundleRoot, ffiHandle, ffiCtx);
+        const lifecycle = new VoiceLifecycle({ registry, loaders });
+        return new EngineVoiceBridge(scheduler, backend, opts.bundleRoot, lifecycle, ffiHandle, ffiCtx);
+    }
+    /**
+     * Lazy-load TTS + ASR mmap regions and the voice scheduler nodes via
+     * the lifecycle state machine. Idempotent for repeated calls in
+     * `voice-on` (returns the existing armed resources). Surfaces RAM
+     * pressure / mmap-fail / kernel-missing as `VoiceLifecycleError` —
+     * see `lifecycle.ts` for the full error taxonomy.
+     */
+    async arm() {
+        if (this.lifecycle.current().kind === "voice-on")
+            return;
+        await this.lifecycle.arm();
+    }
+    /**
+     * Drain in-flight TTS, settle the scheduler, then disarm the
+     * lifecycle. Disarm calls `evictPages()` (madvise / VirtualUnlock
+     * equivalent) on the TTS + ASR mmap regions and releases every
+     * voice-only ref. Speaker preset + phrase cache survive in the
+     * registry as small LRU entries (KB-scale; not worth evicting).
+     */
+    async disarm() {
+        if (this.lifecycle.current().kind !== "voice-on")
+            return;
+        await this.settle();
+        await this.lifecycle.disarm();
+    }
+    /**
+     * Forward an accepted text token from the verifier into the scheduler.
+     * Tokens that fill a phrase trigger TTS dispatch on the same scheduler
+     * tick (AGENTS.md §4 — no buffering past phrase boundaries).
+     */
+    async pushAcceptedToken(token, acceptedAt = Date.now()) {
+        await this.scheduler.accept(token, acceptedAt);
+    }
+    /**
+     * DFlash rejection → rollback queue. The scheduler cancels any
+     * in-flight TTS forward pass for phrases that overlap the rejected
+     * token range and emits an `onRollback` event for observability.
+     * Already-played audio cannot be unplayed; the chunker is sized so
+     * rollback is rare and cheap.
+     */
+    async pushRejectedRange(range) {
+        await this.scheduler.reject(range);
+    }
+    /**
+     * Voice activity detected on the mic input → cancel everything.
+     * Drains the ring buffer immediately, flushes the chunker queue, and
+     * marks every in-flight cancel signal so synthesise loops exit at the
+     * next kernel boundary (AGENTS.md §4 — barge-in cancellation MUST be
+     * within one kernel tick).
+     */
+    triggerBargeIn() {
+        this.scheduler.bargeIn.onMicActive();
+    }
+    /**
+     * Drain pending phrase data and wait for in-flight TTS to settle.
+     * Used at the end of a turn so callers can synchronise on a quiescent
+     * scheduler before they tear it down.
+     */
+    async settle() {
+        await this.scheduler.flushPending();
+        await this.scheduler.waitIdle();
+    }
+    /** Diagnostic accessor — bundle root the bridge is wired against. */
+    bundlePath() {
+        return this.bundleRoot;
+    }
+}
+/**
+ * Default lifecycle loaders derived from the bundle layout (per
+ * AGENTS.md §2: `tts/omnivoice-<size>.gguf` + `asr/...`).
+ *
+ * When a live `ffi`/`ctx` pair is passed in, the returned mmap handles'
+ * `evictPages()` calls forward to `ffi.mmapEvict(ctx, "tts" | "asr")` —
+ * the C ABI declared in `scripts/omnivoice-fuse/ffi.h`. The real fused
+ * build implements this against `madvise(MADV_DONTNEED)` on POSIX and
+ * `VirtualUnlock + OfferVirtualMemory` on Windows. The stub library
+ * returns `ELIZA_ERR_NOT_IMPLEMENTED`, which the binding raises as
+ * `VoiceLifecycleError({code:"kernel-missing"})`.
+ *
+ * When `ffi` is null, `evictPages()` is a documented no-op — used by
+ * the stub TTS path in tests + dev (no real mmap exists, nothing to
+ * evict). The lifecycle test still asserts the call shape via injected
+ * mocks (`lifecycleLoaders` opt).
+ */
+function defaultLifecycleLoaders(bundleRoot, ffi, ctx) {
+    return {
+        loadTtsRegion: async () => bundleMmapRegion(path.join(bundleRoot, "tts"), "tts", ffi, ctx),
+        loadAsrRegion: async () => bundleMmapRegion(path.join(bundleRoot, "asr"), "asr", ffi, ctx),
+        loadVoiceCaches: async () => ({
+            id: `voice-caches:${bundleRoot}`,
+            async release() {
+                // Caches stay live in the SpeakerPresetCache + PhraseCache
+                // singletons; the registry refcount is the only thing that
+                // drops on disarm.
+            },
+        }),
+        loadVoiceSchedulerNodes: async () => ({
+            id: `voice-scheduler-nodes:${bundleRoot}`,
+            async release() {
+                // Scheduler nodes (chunker, rollback, ring buffer, barge-in)
+                // are owned by the bridge's `scheduler` field — no extra
+                // teardown beyond the refcount drop.
+            },
+        }),
+    };
+}
+/**
+ * Build an `MmapRegionHandle` for a bundle subdirectory. Refuses to
+ * fabricate a region when the directory is missing — that surfaces as
+ * `VoiceLifecycleError` via the lifecycle's `arm-failed`/`mmap-fail`
+ * mapping (no silent fallback to a smaller voice model — AGENTS.md §3).
+ *
+ * `evictPages()` forwards to the FFI binding when one is supplied. With
+ * no FFI handle (stub mode), the call is a deliberate no-op — there is
+ * nothing to evict because no real mmap was made. The lifecycle test
+ * still asserts the call shape via injected mocks.
+ */
+function bundleMmapRegion(dir, kind, ffi, ctx) {
+    if (!existsSync(dir)) {
+        throw new Error(`[voice] mmap MAP_FAILED: ${kind} directory missing at ${dir}`);
+    }
+    // Stat the directory to get a stable inode for id derivation. Real
+    // FFI will mmap each weight file independently; this default loader
+    // collapses them into one region per kind for refcount purposes.
+    const st = statSync(dir);
+    return {
+        id: `mmap:${kind}:${st.ino}`,
+        path: dir,
+        sizeBytes: st.size,
+        async evictPages() {
+            if (ffi && ctx !== null) {
+                // Real fused build: madvise / VirtualUnlock through the C ABI.
+                // Throws VoiceLifecycleError on a negative return — the
+                // lifecycle catches and re-classifies via `disarm-failed`.
+                ffi.mmapEvict(ctx, kind);
+            }
+            // Else: no FFI handle (stub TTS / no fused build) — nothing to
+            // evict. Documented no-op.
+        },
+        async release() {
+            // The FFI owns the actual mmap; release is a refcount drop on
+            // the JS side. The fused build's destroy path flushes any
+            // remaining pages when the context is destroyed.
+        },
+    };
+}
+/** Re-export for the engine and tests that want the default loader. */
+export { defaultLifecycleLoaders };
+/**
+ * Platform-specific shared-library suffix for the fused omnivoice build.
+ * macOS dylib, Linux/Android so. Windows builds aren't on the device
+ * matrix yet (AGENTS.md §2 tier table) so we don't synthesise a `.dll`
+ * suffix here.
+ */
+function libraryFilename() {
+    return process.platform === "darwin"
+        ? "libelizainference.dylib"
+        : "libelizainference.so";
+}

package/services/local-inference/voice/ffi-bindings.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Node/Bun FFI binding to `libelizainference.{dylib,so,dll}`.
+ *
+ * The fused omnivoice + llama.cpp build (see
+ * `packages/app-core/scripts/omnivoice-fuse/`) produces ONE shared
+ * library that exports both `llama_*` and `omnivoice_*` symbols plus
+ * the C ABI declared in `scripts/omnivoice-fuse/ffi.h`. This module is
+ * the JS-side proxy for that ABI — it loads the library, binds every
+ * `eliza_inference_*` symbol declared in `ffi.h`, and exposes a typed
+ * handle (`ElizaInferenceFfi`) the voice lifecycle calls into.
+ *
+ * Runtime: production runs under Bun (Electrobun shell, Capacitor
+ * bridge), so the loader uses `bun:ffi`. Tests that need to actually
+ * load a `.dylib` against a stub library spawn a `bun` subprocess —
+ * see `ffi-bindings.test.ts`. Calling this loader from a non-Bun
+ * runtime (e.g. plain Node) throws `VoiceLifecycleError({code:
+ * "missing-ffi"})` with a diagnostic explaining why.
+ *
+ * No defensive try/catch on the success path. Any dlopen failure,
+ * symbol-resolution failure, or ABI mismatch is a structured throw
+ * (AGENTS.md §3 + §9). The caller — `voice/lifecycle.ts` and
+ * `voice/engine-bridge.ts` — surfaces it as a `VoiceLifecycleError` to
+ * the UI.
+ */
+/**
+ * ABI version the JS binding was authored against. Must match the value
+ * `eliza_inference_abi_version()` returns at runtime — a mismatch is a
+ * hard error (AGENTS.md §3, §9: no silent compatibility shims).
+ *
+ * Bump in lockstep with `ELIZA_INFERENCE_ABI_VERSION` in
+ * `scripts/omnivoice-fuse/ffi.h` whenever the C surface changes shape.
+ */
+export declare const ELIZA_INFERENCE_ABI_VERSION: 1;
+/** Status codes mirrored from `ffi.h`. Negative = failure. */
+export declare const ELIZA_OK = 0;
+export declare const ELIZA_ERR_NOT_IMPLEMENTED = -1;
+export declare const ELIZA_ERR_INVALID_ARG = -2;
+export declare const ELIZA_ERR_BUNDLE_INVALID = -3;
+export declare const ELIZA_ERR_FFI_FAULT = -4;
+export declare const ELIZA_ERR_OOM = -5;
+export declare const ELIZA_ERR_ABI_MISMATCH = -6;
+/**
+ * Region names the lifecycle hands to `mmap_acquire` / `mmap_evict`.
+ * Mirrors the set the C stub validates in `ffi-stub.c::valid_region`.
+ */
+export type ElizaInferenceRegion = "tts" | "asr" | "text" | "dflash";
+/**
+ * Opaque pointer to the C-side `EliInferenceContext`. Numeric on Bun
+ * (FFI returns the raw pointer as `bigint`); never inspected on the JS
+ * side beyond passing it back through the binding.
+ */
+export type ElizaInferenceContextHandle = bigint;
+/**
+ * Typed handle returned by `loadElizaInferenceFfi`. Each method maps
+ * 1:1 to a symbol declared in `ffi.h`. Methods that allocate a context
+ * return the opaque pointer; methods that consume one take it as the
+ * first argument. Failures throw `VoiceLifecycleError` with the
+ * structured code derived from the C return value.
+ */
+export interface ElizaInferenceFfi {
+    /** Library path the binding was loaded from (for diagnostics). */
+    readonly libraryPath: string;
+    /** ABI version reported by the loaded library. */
+    readonly libraryAbiVersion: string;
+    /** Create a fresh context anchored at `bundleDir`. */
+    create(bundleDir: string): ElizaInferenceContextHandle;
+    /** Destroy a previously-created context. Idempotent on already-freed handles. */
+    destroy(ctx: ElizaInferenceContextHandle): void;
+    /** Map / re-page weights for a region. */
+    mmapAcquire(ctx: ElizaInferenceContextHandle, region: ElizaInferenceRegion): void;
+    /**
+     * Hint the kernel that a region's pages are no longer needed
+     * (madvise MADV_DONTNEED / VirtualUnlock). Does not close the file
+     * descriptor — a subsequent `mmapAcquire` re-pages without an open().
+     */
+    mmapEvict(ctx: ElizaInferenceContextHandle, region: ElizaInferenceRegion): void;
+    /**
+     * Synchronous TTS forward. Caller provides the output buffer; library
+     * fills up to its capacity and returns the number of samples written.
+     */
+    ttsSynthesize(args: {
+        ctx: ElizaInferenceContextHandle;
+        text: string;
+        speakerPresetId: string | null;
+        out: Float32Array;
+    }): number;
+    /**
+     * Synchronous ASR forward. Returns the decoded transcript as a UTF-8
+     * string (allocated by the JS side, sized to fit the library's max
+     * write).
+     */
+    asrTranscribe(args: {
+        ctx: ElizaInferenceContextHandle;
+        pcm: Float32Array;
+        sampleRateHz: number;
+        maxTextBytes?: number;
+    }): string;
+    /** Best-effort dispose for the binding itself (closes the dlopen handle). */
+    close(): void;
+}
+/**
+ * Load `libelizainference` at `dylibPath` and bind every symbol
+ * declared in `ffi.h`. The returned handle's methods delegate directly
+ * to the library; they throw `VoiceLifecycleError` on any negative
+ * return value or runtime fault.
+ *
+ * Throws synchronously (no Promise) when:
+ *   - the JS runtime is not Bun (no FFI primitive available),
+ *   - `dlopen` cannot find or open the library,
+ *   - the library's reported ABI version does not match
+ *     `ELIZA_INFERENCE_ABI_VERSION`.
+ */
+export declare function loadElizaInferenceFfi(dylibPath: string): ElizaInferenceFfi;
+//# sourceMappingURL=ffi-bindings.d.ts.map

package/services/local-inference/voice/ffi-bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffi-bindings.d.ts","sourceRoot":"","sources":["../../../../../../../src/services/local-inference/voice/ffi-bindings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,EAAG,CAAU,CAAC;AAEtD,8DAA8D;AAC9D,eAAO,MAAM,QAAQ,IAAI,CAAC;AAC1B,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAC5C,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAC3C,eAAO,MAAM,mBAAmB,KAAK,CAAC;AACtC,eAAO,MAAM,aAAa,KAAK,CAAC;AAChC,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;AAErE;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,sDAAsD;IACtD,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,2BAA2B,CAAC;IACvD,iFAAiF;IACjF,OAAO,CAAC,GAAG,EAAE,2BAA2B,GAAG,IAAI,CAAC;IAChD,0CAA0C;IAC1C,WAAW,CAAC,GAAG,EAAE,2BAA2B,EAAE,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAClF;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,2BAA2B,EAAE,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAChF;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE;QAClB,GAAG,EAAE,2BAA2B,CAAC;QACjC,IAAI,EAAE,MAAM,CAAC;QACb,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,GAAG,EAAE,YAAY,CAAC;KACnB,GAAG,MAAM,CAAC;IACX;;;;OAIG;IACH,aAAa,CAAC,IAAI,EAAE;QAClB,GAAG,EAAE,2BAA2B,CAAC;QACjC,GAAG,EAAE,YAAY,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,GAAG,MAAM,CAAC;IACX,6EAA6E;IAC7E,KAAK,IAAI,IAAI,CAAC;CACf;AAWD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,iBAAiB,CAgB1E"}