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

package/src/services/voice/ffi-bindings.d.ts

@@ -0,0 +1,674 @@
+/**
+ * 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.
+ *
+ * v4: the FFI bridge resolves `speaker_preset_id` against the bundle's
+ *     `cache/voice-preset-<id>.bin` (ELZ2 v2) and applies the
+ *     `(instruct, ref_audio_tokens, ref_T, ref_text)` triple to
+ *     `ov_tts_params` before calling `ov_synthesize`. Adds the
+ *     `eliza_inference_encode_reference` entrypoint that the freeze CLI
+ *     uses to pre-encode reference WAVs into the preset file. A v3 caller
+ *     remains source-compatible: every v3 entry point keeps its v3 shape.
+ *
+ * v5: the FFI bridge gains the native openWakeWord surface
+ *     (`eliza_inference_wakeword_supported/open/score/reset/close`). It
+ *     replaces the previous `onnxruntime-node`-backed wake-word path —
+ *     the JS binding routes wake-word detection exclusively through this
+ *     ABI with no ONNX fallback (AGENTS.md §3, §8). v4 callers that
+ *     never touched the wake-word entries are source-compatible.
+ *
+ * v6: the FFI bridge gains the native speaker-encoder + diarizer
+ *     surfaces (`eliza_inference_speaker_supported/open/embed/free/close`
+ *     and `eliza_inference_diariz_supported/open/segment/close`). These
+ *     fuse the remaining standalone `libvoice_classifier` voice
+ *     classifiers into the one `libelizainference` handle so the whole
+ *     voice pipeline runs through a single native lib. v5 callers that
+ *     never touched the speaker/diarizer entries are source-compatible.
+ *
+ * v9: the last text-adjacent modalities move onto the fused handle. Three
+ *     additive surfaces + probes: text embeddings (`embed` / `embedSupported`),
+ *     mmproj vision describe (`describeImage` / `visionSupported`), and the
+ *     tokenizer (`tokenize` / `detokenize` / `tokenizeSupported`). With these,
+ *     libllama is fully retired: text, embeddings, vision, and tokenization all
+ *     run through the fused handle. A pre-v9 library lacks these symbols, so the
+ *     probes report unsupported and the fused runtime refuses (there is no
+ *     libllama fallback). v8 callers that never touched the new entries remain
+ *     source-compatible (the new probes simply return false on a v8 lib).
+ *
+ * v10: Kokoro-82M TTS folded in-process. The fused handle gains
+ *     `eliza_inference_kokoro_supported/load/synthesize/sample_rate` so the
+ *     mobile Kokoro path synthesizes through the same dlopen()-ed
+ *     libelizainference as OmniVoice instead of POSTing to the local-TCP
+ *     `llama-server /v1/audio/speech` route (forbidden on iOS / Google Play).
+ *     The four symbols are additive — a v9 library lacks them, so the
+ *     `kokoroSupported()` probe reports false and the Kokoro FFI runtime
+ *     refuses (no TCP fallback on mobile). A v9 library is still accepted at
+ *     degraded capability: its voice/ASR/VAD/LLM/text surface is unchanged and
+ *     Kokoro just probes unsupported on it.
+ */
+export declare const ELIZA_INFERENCE_ABI_VERSION: 12;
+/** One transcribed word with playback-synced timing (ms from utterance start). */
+export interface AsrWordTiming {
+    text: string;
+    startMs: number;
+    endMs: number;
+}
+/**
+ * Recover per-word `{ text, startMs, endMs }` from a v12 timed-ASR result.
+ *
+ * The native `eliza_inference_asr_transcribe_timed` sizes the `startMs`/`endMs`
+ * arrays by splitting the transcript on ASCII whitespace — `std::isspace` in the
+ * C locale matches EXACTLY ` \t\n\v\f\r`. We must mirror that split byte-for-byte
+ * to recover the word strings: a broader Unicode `\s` split collapses NBSP /
+ * ideographic space (U+00A0, U+3000, …) that the native byte split keeps, which
+ * would make `tokens` shorter than `count` and silently zip each word's text
+ * against a DIFFERENT word's timing — a desync `validateAsrWordTimings` cannot
+ * see (it never compares text to count). `count` only falls below the true word
+ * count when the caller's `maxWords` cap is hit, in which case the trailing
+ * (untimed) words are dropped by `Math.min`.
+ */
+export declare function recoverAsrWords(text: string, count: number, startMs: Int32Array, endMs: Int32Array): AsrWordTiming[];
+/**
+ * Pooling strategies for `embed`. Mirror `enum llama_pooling_type` and the
+ * `ELIZA_POOLING_*` constants in `eliza-inference-ffi.h`.
+ */
+export declare const ELIZA_POOLING_MEAN = 1;
+export declare const ELIZA_POOLING_CLS = 2;
+export declare const ELIZA_POOLING_LAST = 3;
+/** 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;
+export declare const ELIZA_ERR_CANCELLED = -7;
+/**
+ * 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" | "mtp" | "vad" | "wakeword";
+/**
+ * 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;
+/** Opaque pointer to a native Silero VAD session. */
+export type NativeVadHandle = bigint;
+/** Opaque pointer to a native openWakeWord session. */
+export type NativeWakeWordHandle = bigint;
+/** Opaque pointer to a native WeSpeaker speaker-encoder session. */
+export type NativeSpeakerHandle = bigint;
+/** Opaque pointer to a native pyannote diarizer session. */
+export type NativeDiarizHandle = bigint;
+/** Opaque pointer to a streaming-LLM session. */
+export type LlmStreamHandle = bigint;
+/**
+ * Per-session config handed to `llmStreamOpen`. Mirrors
+ * `eliza_llm_stream_config_t` in
+ * `native/llama.cpp/tools/omnivoice/include/eliza-inference-ffi.h` (ABI v8).
+ */
+export interface LlmStreamConfig {
+    maxTokens: number;
+    temperature: number;
+    topP: number;
+    topK: number;
+    repeatPenalty: number;
+    /** Pinned slot id; -1 disables pinning. */
+    slotId: number;
+    /** Optional prompt cache key used to derive a slot when `slotId === -1`. */
+    promptCacheKey: string | null;
+    /** MTP drafter bounds; `0` for either disables speculative decoding. */
+    draftMin: number;
+    draftMax: number;
+    /** Absolute MTP drafter GGUF path; null disables drafter-backed MTP. */
+    draftModelPath: string | null;
+    /**
+     * GBNF grammar source. When set the native session installs a grammar
+     * sampler FIRST in the chain so every sampled token is constrained — this
+     * is how the structured-reply envelope is forced on the in-process FFI
+     * path. `null`/empty disables grammar constraint.
+     */
+    gbnfGrammar?: string | null;
+    /** Qwen3-style thinking-tag suppression passthrough (v1 no-op). */
+    disableThinking?: boolean;
+    /**
+     * Per-load GPU offload (ABI v8). Number of model layers to place on GPU.
+     * `undefined`/-1 selects the runtime default (all layers); 0 forces CPU.
+     * The model is loaded once per ctx, so the FIRST session's value wins.
+     */
+    gpuLayers?: number;
+    /**
+     * KV-cache K quant type name (ABI v8), e.g. "f16", "q8_0", "qjl1_256".
+     * `undefined`/null leaves the f16 default. Mapped to `ggml_type` by the
+     * fused lib's `eliza_llm_stream_config_t.cache_type_k`.
+     */
+    cacheTypeK?: string | null;
+    /** KV-cache V quant type name (ABI v8); see `cacheTypeK`. */
+    cacheTypeV?: string | null;
+}
+/**
+ * One step of streaming LLM output. `tokens` is the batch of accepted text
+ * model token ids the runtime committed this step (>= 1; > 1 only when the
+ * MTP drafter is active and the verifier accepted multiple drafts).
+ * `text` is the detokenized text for those tokens. `done` is `true` only
+ * on the final step (EOS reached). `drafterDrafted` and `drafterAccepted`
+ * are populated when the drafter is active.
+ */
+export interface LlmStreamStep {
+    tokens: number[];
+    text: string;
+    done: boolean;
+    drafterDrafted: number;
+    drafterAccepted: number;
+}
+/**
+ * One streaming-TTS chunk delivered to the `onChunk` callback passed to
+ * `ttsSynthesizeStream`. `pcm` is a *view* over the library's buffer —
+ * valid only for the duration of the callback; copy it before
+ * returning. `isFinal` marks the zero-length tail chunk that closes the
+ * utterance. The callback returning `true` requests cancellation at the
+ * next kernel boundary.
+ */
+export interface TtsStreamChunk {
+    pcm: Float32Array;
+    isFinal: boolean;
+}
+/**
+ * A native MTP speculative-step event from
+ * `eliza_inference_set_verifier_callback`. Token-index domain is the
+ * generated-output stream (token 0 = first generated token), matching
+ * `RejectedTokenRange`. `rejectedFrom`/`rejectedTo` are -1 when nothing
+ * was rejected this step.
+ */
+export interface NativeVerifierEvent {
+    acceptedTokenIds: number[];
+    rejectedFrom: number;
+    rejectedTo: number;
+    correctedTokenIds: number[];
+}
+/**
+ * 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;
+    /**
+     * Release or evict a voice-only region after the lifecycle leaves
+     * voice-on. Implementations may madvise mapped pages or unload the
+     * ASR/TTS runtime state entirely; callers must treat the region as
+     * unavailable until the next `mmapAcquire`.
+     */
+    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;
+    /** True when this build can emit per-word ASR timestamps (v12+). v11 and
+     *  older report false — callers fall back to the text-only `asrTranscribe`. */
+    timedAsrSupported(): boolean;
+    /** Transcribe like `asrTranscribe` AND return per-word `[startMs,endMs)`
+     *  spans (duration-proportional, char-weighted, monotonic — the honest
+     *  single-model signal; see the v12 ABI changelog). The word texts come from
+     *  a whitespace split of the transcript, zipped with the native timing. */
+    asrTranscribeTimed(args: {
+        ctx: ElizaInferenceContextHandle;
+        pcm: Float32Array;
+        sampleRateHz: number;
+        maxTextBytes?: number;
+        maxWords?: number;
+    }): {
+        text: string;
+        words: AsrWordTiming[];
+    };
+    /**
+     * True when this build implements streaming TTS (false for the stub /
+     * a TTS-disabled build). Callers pick the streaming path vs the batch
+     * `ttsSynthesize` off this flag — no probe-and-catch.
+     */
+    ttsStreamSupported(): boolean;
+    /**
+     * Chunked synthesis. `onChunk` is invoked for each decoded PCM segment
+     * as it arrives, then once more with `isFinal: true` (zero-length
+     * tail). Returning `true` from `onChunk` requests cancellation; the
+     * call then resolves with `cancelled: true` after the final-chunk
+     * callback. Any negative library return is a thrown `VoiceLifecycleError`.
+     */
+    ttsSynthesizeStream(args: {
+        ctx: ElizaInferenceContextHandle;
+        text: string;
+        speakerPresetId: string | null;
+        onChunk: (chunk: TtsStreamChunk) => boolean | undefined;
+    }): {
+        cancelled: boolean;
+    };
+    /**
+     * Hard-cancel any in-flight TTS forward pass on `ctx` (started on
+     * another thread by `ttsSynthesize` / `ttsSynthesizeStream`). The
+     * in-flight call returns `ELIZA_ERR_CANCELLED` at the next kernel
+     * boundary. Cancelling nothing is not an error.
+     */
+    cancelTts(ctx: ElizaInferenceContextHandle): void;
+    /**
+     * Register (or, with `cb: null`, clear) the native MTP verifier
+     * callback. The runtime fires `cb` for every speculative accept/reject
+     * step from the in-process drafter↔target loop. The returned
+     * `JSCallbackHandle` MUST be kept alive for as long as the callback is
+     * registered and `.close()`d when it's cleared (or on dispose) — Bun's
+     * `JSCallback` is GC'd otherwise and the native side dereferences a
+     * dead pointer.
+     */
+    setVerifierCallback(ctx: ElizaInferenceContextHandle, cb: ((event: NativeVerifierEvent) => void) | null): {
+        close(): void;
+    };
+    /**
+     * True when this build exports the OmniVoice reference-encode symbols
+     * (`eliza_inference_encode_reference`). The freeze CLI uses this to
+     * pre-encode same reference audio into the persisted voice preset;
+     * the runtime synthesis path never calls it (it reads pre-encoded
+     * tokens from the preset file).
+     */
+    encodeReferenceSupported?(): boolean;
+    /**
+     * Run the encode-only half of the TTS pipeline (HuBERT semantic + RVQ
+     * codec) on a 24 kHz mono fp32 PCM buffer and return the resulting
+     * reference-audio-token tensor `[K=8, ref_T]` as `Int32Array`
+     * row-major (`tokens[k*ref_T + t]`). The library allocates and the
+     * binding takes care of freeing the native buffer via
+     * `eliza_inference_free_tokens` before this returns.
+     *
+     * The TTS region must have been acquired (`mmapAcquire("tts")`)
+     * before the call. `sampleRateHz` must be 24000; the entrypoint does
+     * NOT resample, by design — the freeze artifact must be deterministic.
+     */
+    encodeReference?(args: {
+        ctx: ElizaInferenceContextHandle;
+        pcm: Float32Array;
+        sampleRateHz: number;
+    }): {
+        K: number;
+        refT: number;
+        tokens: Int32Array;
+    };
+    /** True when this build exports and enables the native Silero VAD backend. */
+    vadSupported?(): boolean;
+    /** Open a native VAD session. The ABI-compatible sample rate is 16 kHz. */
+    vadOpen?(args: {
+        ctx: ElizaInferenceContextHandle;
+        sampleRateHz: number;
+    }): NativeVadHandle;
+    /** Process one 512-sample fp32 mono window and return P(speech). */
+    vadProcess?(args: {
+        vad: NativeVadHandle;
+        pcm: Float32Array;
+    }): number;
+    /** Clear native VAD recurrent state at utterance boundaries. */
+    vadReset?(vad: NativeVadHandle): void;
+    /** Close + free a native VAD session. Idempotent on already-closed handles. */
+    vadClose?(vad: NativeVadHandle): void;
+    /**
+     * True when this build exports and enables the native openWakeWord
+     * backend. The JS binding routes wake-word detection exclusively
+     * through this surface; when this returns false, the wake-word path
+     * throws a structured "runtime not ready" error — no ONNX fallback
+     * (AGENTS.md §3, §8).
+     */
+    wakewordSupported?(): boolean;
+    /**
+     * Open a native wake-word session. `sampleRateHz` must be 16000;
+     * `headName` selects the classifier head inside the bundle's combined
+     * wake-word GGUF (e.g. "hey-eliza").
+     */
+    wakewordOpen?(args: {
+        ctx: ElizaInferenceContextHandle;
+        sampleRateHz: number;
+        headName: string;
+    }): NativeWakeWordHandle;
+    /**
+     * Score one 1280-sample (80 ms @ 16 kHz) fp32 mono frame and return
+     * the latest P(wake) in [0, 1]. Early calls before enough context
+     * accumulates return 0.
+     */
+    wakewordScore?(args: {
+        wake: NativeWakeWordHandle;
+        pcm: Float32Array;
+    }): number;
+    /** Clear all streaming state (audio tail, mel ring, embedding ring). */
+    wakewordReset?(wake: NativeWakeWordHandle): void;
+    /** Close + free a native wake-word session. Idempotent on already-closed handles. */
+    wakewordClose?(wake: NativeWakeWordHandle): void;
+    /** True when this build exports and enables the native WeSpeaker encoder. */
+    speakerSupported?(): boolean;
+    /**
+     * Open a native speaker-encoder session. `ggufPath` may be null to
+     * resolve the bundle's `speaker/` dir, or an absolute path to a
+     * WeSpeaker GGUF.
+     */
+    speakerOpen?(args: {
+        ctx: ElizaInferenceContextHandle;
+        ggufPath: string | null;
+    }): NativeSpeakerHandle;
+    /**
+     * Embed `pcm` (16 kHz mono fp32) into a 256-d L2-normalized speaker
+     * embedding. Returns a freshly-allocated `Float32Array` of length 256.
+     */
+    speakerEmbed?(args: {
+        speaker: NativeSpeakerHandle;
+        pcm: Float32Array;
+    }): Float32Array;
+    /** Close + free a native speaker-encoder session. Idempotent on already-closed handles. */
+    speakerClose?(speaker: NativeSpeakerHandle): void;
+    /** True when this build exports and enables the native pyannote diarizer. */
+    diarizSupported?(): boolean;
+    /**
+     * Open a native diarizer session. `ggufPath` may be null to resolve the
+     * bundle's `diariz/` dir, or an absolute path to a pyannote GGUF.
+     */
+    diarizOpen?(args: {
+        ctx: ElizaInferenceContextHandle;
+        ggufPath: string | null;
+    }): NativeDiarizHandle;
+    /**
+     * Segment one 80000-sample (5 s @ 16 kHz) mono fp32 window into a
+     * per-frame powerset-label sequence. Returns the `Int8Array` of frame
+     * labels (293 for pyannote-segmentation-3.0), each in `[0, 7)`.
+     */
+    diarizSegment?(args: {
+        diariz: NativeDiarizHandle;
+        pcm: Float32Array;
+    }): Int8Array;
+    /** Close + free a native diarizer session. Idempotent on already-closed handles. */
+    diarizClose?(diariz: NativeDiarizHandle): void;
+    /**
+     * True when this build has a working streaming ASR decoder (false for
+     * the stub / an ASR-disabled build). Callers pick the fused streaming
+     * path vs the fused batch interim adapter off this flag — they do not
+     * have to open a session and catch `ELIZA_ERR_NOT_IMPLEMENTED`.
+     */
+    asrStreamSupported(): boolean;
+    /** Open a streaming ASR session. The handle is closed via `asrStreamClose`. */
+    asrStreamOpen(args: {
+        ctx: ElizaInferenceContextHandle;
+        sampleRateHz: number;
+    }): bigint;
+    /** Feed one PCM frame at the session's sample rate. */
+    asrStreamFeed(args: {
+        stream: bigint;
+        pcm: Float32Array;
+    }): void;
+    /** Read the current running partial transcript (and token ids when available). */
+    asrStreamPartial(args: {
+        stream: bigint;
+        maxTextBytes?: number;
+        maxTokens?: number;
+    }): {
+        partial: string;
+        tokens?: number[];
+    };
+    /** Force-finalize: drain buffered audio, run a final decode, return the final transcript. */
+    asrStreamFinish(args: {
+        stream: bigint;
+        maxTextBytes?: number;
+        maxTokens?: number;
+    }): {
+        partial: string;
+        tokens?: number[];
+    };
+    /** Close + free a streaming ASR session. Idempotent on already-closed handles. */
+    asrStreamClose(stream: bigint): void;
+    /**
+     * True when this build exports the streaming LLM symbols
+     * (`eliza_inference_llm_stream_*`). Transitional builds may load
+     * without them; the runner uses this to pick between the FFI streaming
+     * path.
+     */
+    llmStreamSupported?(): boolean;
+    /**
+     * True when this build wires same-file / separate-drafter MTP
+     * speculative decoding into the streaming-LLM text path (ABI v8). A v7
+     * library returns `false` here (the symbol is absent), so the fused TEXT
+     * path can refuse to route through it without a speculative-decode
+     * regression. Anti-regression guard — see ABI v8 changelog.
+     */
+    llmMtpSupported?(): boolean;
+    /**
+     * True when this build maps + applies KV-cache quant types in the
+     * streaming-LLM text path (ABI v8). A v7 library returns `false` (symbol
+     * absent); the fused TEXT path refuses it to avoid a silent fallback to
+     * f16 KV when a quantized cache was requested.
+     */
+    llmKvQuantSupported?(): boolean;
+    /**
+     * Open a streaming-LLM session against `ctx`. Failure throws
+     * `VoiceLifecycleError`. Close exactly once via `llmStreamClose`.
+     */
+    llmStreamOpen?(args: {
+        ctx: ElizaInferenceContextHandle;
+        config: LlmStreamConfig;
+    }): LlmStreamHandle;
+    /** Feed a batch of pre-tokenized prompt tokens before the first `next`. */
+    llmStreamPrefill?(args: {
+        stream: LlmStreamHandle;
+        tokens: Int32Array;
+    }): void;
+    /**
+     * Pull the next streaming step. Returns `null` when the runtime declined
+     * to emit tokens this call (rare — drafter rejected everything and the
+     * verifier had nothing to commit); poll again. `step.done === true` is
+     * the final step.
+     */
+    llmStreamNext?(args: {
+        stream: LlmStreamHandle;
+        maxTokensPerStep?: number;
+        maxTextBytes?: number;
+    }): LlmStreamStep;
+    /** Cancel in-flight generation; the next `_next` returns CANCELLED. */
+    llmStreamCancel?(stream: LlmStreamHandle): void;
+    /** Persist the session's slot KV state to disk. */
+    llmStreamSaveSlot?(args: {
+        stream: LlmStreamHandle;
+        filename: string;
+    }): void;
+    /** Restore a previously-saved slot KV file. Call before the first prefill/next. */
+    llmStreamRestoreSlot?(args: {
+        stream: LlmStreamHandle;
+        filename: string;
+    }): void;
+    /** Close + free a streaming-LLM session. Idempotent on already-closed handles. */
+    llmStreamClose?(stream: LlmStreamHandle): void;
+    /**
+     * True when this build wires the fused text-embedding path
+     * (`eliza_inference_embed`). A v8 library returns false (symbol absent),
+     * so the default TEXT_EMBEDDING handler keeps the node-llama-cpp /
+     * libllama path.
+     */
+    embedSupported?(): boolean;
+    /**
+     * Compute a pooled, L2-normalized sentence embedding for `text` over the
+     * bundle's text model. `pooling` selects the strategy (default MEAN — the
+     * gte-small convention). Returns a `Float32Array` of length `n_embd`.
+     */
+    embed?(args: {
+        ctx: ElizaInferenceContextHandle;
+        text: string;
+        pooling?: number;
+    }): Float32Array;
+    /**
+     * True when this build was compiled with vision (`-DELIZA_ENABLE_VISION`)
+     * and exports `eliza_inference_describe_image`. A v8 / vision-off library
+     * returns false, so the IMAGE_DESCRIPTION handler keeps the libllama mtmd
+     * path.
+     */
+    visionSupported?(): boolean;
+    /**
+     * Describe `imageBytes` (raw PNG/JPEG/WebP) through the text model's
+     * mmproj projector at `mmprojPath`. `prompt` defaults to a generic
+     * caption request. Returns the description text.
+     */
+    describeImage?(args: {
+        ctx: ElizaInferenceContextHandle;
+        imageBytes: Uint8Array;
+        mmprojPath: string;
+        prompt?: string;
+        maxTextBytes?: number;
+    }): string;
+    /**
+     * True when this build exposes the tokenizer over the loaded text vocab
+     * (`eliza_inference_tokenize`). A pre-v9 library returns false, so the
+     * desktop fused runtime refuses (libllama is retired — no tokenizer sidecar).
+     */
+    tokenizeSupported?(): boolean;
+    /**
+     * Tokenize `text` against the loaded text model's vocab. `addSpecial`
+     * (default true) adds BOS/EOS; `parseSpecial` (default false) renders
+     * special tokens from the input. Returns the token ids as an `Int32Array`.
+     */
+    tokenize?(args: {
+        ctx: ElizaInferenceContextHandle;
+        text: string;
+        addSpecial?: boolean;
+        parseSpecial?: boolean;
+    }): Int32Array;
+    /**
+     * Detokenize `tokens` back to text against the loaded text model's vocab.
+     * `removeSpecial` (default false) strips BOS/EOS; `unparseSpecial`
+     * (default false) renders special tokens.
+     */
+    detokenize?(args: {
+        ctx: ElizaInferenceContextHandle;
+        tokens: Int32Array;
+        removeSpecial?: boolean;
+        unparseSpecial?: boolean;
+        maxTextBytes?: number;
+    }): string;
+    /**
+     * True when this build wires the fused end-of-turn scorer
+     * (`eliza_inference_llm_eot_score`). A v10 library returns false (symbol
+     * absent), so the composite EOT classifier uses the heuristic-only signal.
+     */
+    eotSupported?(): boolean;
+    /**
+     * Single causal forward pass over `tokens` (a tokenized partial transcript)
+     * returning the next-token softmax probability of `targetTokenId` (the
+     * end-of-turn marker, e.g. `<|im_end|>`), plus the argmax next token and its
+     * probability. Runs on a dedicated scoring context over the loaded text
+     * model; KV is cleared per call so scores are independent.
+     */
+    eotScore?(args: {
+        ctx: ElizaInferenceContextHandle;
+        tokens: Int32Array;
+        targetTokenId: number;
+    }): {
+        targetProb: number;
+        topToken: number;
+        topProb: number;
+    };
+    /**
+     * True when this build linked Eliza-1's in-process Kokoro engine
+     * (`eliza_inference_kokoro_*`). A v9 library returns false (symbols
+     * absent), so the Kokoro FFI runtime refuses rather than falling back to
+     * the local-TCP `llama-server` route (forbidden on iOS / Google Play).
+     */
+    kokoroSupported?(): boolean;
+    /**
+     * Load the Kokoro GGUF at `ggufPath` and the voice preset `.bin` at
+     * `voiceBinPath` (raw fp32 ref_s, `styleDim` inner dim — 256 for v1.0)
+     * into `ctx`. Replaces any previously-loaded Kokoro model on the ctx.
+     * Throws `VoiceLifecycleError` on a negative return with the C diagnostic.
+     */
+    kokoroLoad?(args: {
+        ctx: ElizaInferenceContextHandle;
+        ggufPath: string;
+        voiceBinPath: string;
+        styleDim?: number;
+    }): void;
+    /**
+     * Synthesize `text` through the loaded Kokoro model+voice at the model's
+     * native rate (24 kHz for v1.0). `speed` scales predicted durations
+     * (default 1.0). Allocates an output buffer of `maxSamples` fp32 samples,
+     * reads back the count the library wrote, and returns that slice.
+     */
+    kokoroSynthesize?(args: {
+        ctx: ElizaInferenceContextHandle;
+        text: string;
+        speed?: number;
+        maxSamples: number;
+    }): Float32Array;
+    /** The loaded Kokoro model's audio sample rate (24000 for v1.0). */
+    kokoroSampleRate?(ctx: ElizaInferenceContextHandle): number;
+    /** 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