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

package/src/services/voice/engine-bridge.d.ts

@@ -0,0 +1,759 @@
+/**
+ * Engine ↔ voice scheduler bridge.
+ *
+ * Adapts the live `LocalInferenceEngine` (`engine.ts`) plus the MTP
+ * llama-server (`ffi-streaming-backend.ts`) onto the voice scaffold's
+ * `VoiceScheduler`. See `packages/inference/AGENTS.md` §4 for the
+ * streaming graph this implements:
+ *
+ *   ASR → text tokens → MTP drafter ↔ target verifier (text model)
+ *        → phrase chunker → speaker preset cache + phrase cache
+ *        → OmniVoice TTS → PCM ring buffer → audio out
+ *
+ * Plus rollback queue (MTP 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`: forwards through the fused
+ *     `libelizainference.{dylib,so,dll}` ABI. The bridge creates the
+ *     context lazily when voice is armed or first used, so voice-off
+ *     does not keep OmniVoice weights resident.
+ *
+ * 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 type { IAgentRuntime } from "@elizaos/core";
+import type { VoiceCancellationReason } from "@elizaos/shared";
+import { type CoordinatorRuntime, VoiceCancellationCoordinator } from "./cancellation-coordinator";
+import { VoiceStartupError } from "./errors";
+import type { AsrWordTiming, ElizaInferenceContextHandle, ElizaInferenceFfi, NativeVerifierEvent } from "./ffi-bindings";
+import { KokoroTtsBackend } from "./kokoro/kokoro-backend";
+import type { KokoroEngineDiscoveryResult } from "./kokoro/kokoro-engine-discovery";
+import { VoiceLifecycle, type VoiceLifecycleLoaders } from "./lifecycle";
+import { OptimisticGenerationPolicy, type OptimisticPolicyOptions } from "./optimistic-policy";
+import { type CachedPhraseAudio } from "./phrase-cache";
+import { VoicePipeline, type VoicePipelineConfig, type VoicePipelineEvents } from "./pipeline";
+import { type MtpTextRunner } from "./pipeline-impls";
+import type { VoiceProfileStore } from "./profile-store";
+import { type SchedulerEvents, VoiceScheduler } from "./scheduler";
+import { SharedResourceRegistry } from "./shared-resources";
+import { type VoiceAttributionOutput } from "./speaker/attribution-pipeline";
+import type { AudioChunk, AudioSink, OmniVoiceBackend, Phrase, RejectedTokenRange, SpeakerPreset, StreamingTranscriber, TextToken, TranscriptionAudio, VadEventSource } from "./types";
+/** Re-exported from `./errors` so existing `engine-bridge` importers don't churn. */
+export { VoiceStartupError };
+/**
+ * Native verifier callbacks report rejected token ranges as half-open
+ * `[from, to)` intervals. The scheduler rollback queue uses inclusive
+ * token indexes, so convert in exactly one place.
+ */
+export declare function nativeRejectedRangeToRollbackRange(event: Pick<NativeVerifierEvent, "rejectedFrom" | "rejectedTo">): RejectedTokenRange | null;
+/**
+ * One PCM segment delivered to a `StreamingTtsBackend.synthesizeStream`
+ * consumer (W9's scheduler) as TTS decodes it. `isFinal` marks the
+ * zero-length tail chunk that closes the phrase.
+ */
+export interface TtsPcmChunk {
+    pcm: Float32Array;
+    sampleRate: number;
+    isFinal: boolean;
+}
+/**
+ * Streaming-TTS seam between the fused `libelizainference` runtime and
+ * W9's voice scheduler. The scheduler calls `synthesizeStream(...)` for
+ * a phrase and writes each delivered `pcm` segment into the
+ * `PcmRingBuffer` on the same scheduler tick (AGENTS.md §4 —
+ * phrase-chunk → TTS within one scheduler tick); returning `true` from
+ * `onChunk` (or flipping `cancelSignal.cancelled`) hard-cancels the
+ * in-flight forward pass at the next kernel boundary (barge-in /
+ * MTP-rejected tail).
+ *
+ * Both `OmniVoiceBackend` implementations in this module satisfy it:
+ *   - `FfiOmniVoiceBackend` forwards to
+ *     `eliza_inference_tts_synthesize_stream` when the loaded build
+ *     advertises streaming TTS (`tts_stream_supported() == 1`), else it
+ *     synthesizes whole and emits the result as one body chunk + a final
+ *     tail (no silent "streaming" lie — the chunk count just collapses
+ *     to one when the build is non-streaming);
+ *   - `StubOmniVoiceBackend` emits deterministic synthetic PCM split
+ *     into a fixed number of chunks so scheduler tests can observe the
+ *     incremental handoff without a real model.
+ */
+export interface StreamingTtsBackend {
+    /**
+     * Synthesize `phrase` with `preset` and deliver PCM in chunks. The
+     * scheduler owns the ring-buffer write inside `onChunk`. Resolves with
+     * `cancelled: true` if `onChunk` requested a stop (or `cancelSignal`
+     * was set), `false` on a clean finish. The final `onChunk` call always
+     * has `isFinal: true` (possibly a zero-length `pcm`) so the consumer
+     * can settle per-phrase state.
+     */
+    synthesizeStream(args: {
+        phrase: Phrase;
+        preset: SpeakerPreset;
+        cancelSignal: {
+            cancelled: boolean;
+        };
+        onChunk: (chunk: TtsPcmChunk) => boolean | undefined;
+        onKernelTick?: () => void;
+    }): Promise<{
+        cancelled: boolean;
+    }>;
+}
+/** True when `backend` implements the `StreamingTtsBackend` seam. */
+export declare function isStreamingTtsBackend(backend: OmniVoiceBackend): backend is OmniVoiceBackend & StreamingTtsBackend;
+/**
+ * Deterministic test TTS backend. 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 declare class StubOmniVoiceBackend implements OmniVoiceBackend, StreamingTtsBackend {
+    readonly id: "stub";
+    private readonly sampleRate;
+    calls: number;
+    streamCalls: number;
+    constructor(sampleRate?: number);
+    synthesize(args: {
+        phrase: Phrase;
+        preset: SpeakerPreset;
+        cancelSignal: {
+            cancelled: boolean;
+        };
+        onKernelTick?: () => void;
+    }): Promise<AudioChunk>;
+    synthesizeStream(args: {
+        phrase: Phrase;
+        preset: SpeakerPreset;
+        cancelSignal: {
+            cancelled: boolean;
+        };
+        onChunk: (chunk: TtsPcmChunk) => boolean | undefined;
+        onKernelTick?: () => void;
+    }): Promise<{
+        cancelled: boolean;
+    }>;
+}
+/**
+ * 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 compatibility C library 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 declare class FfiOmniVoiceBackend implements OmniVoiceBackend, StreamingTtsBackend {
+    readonly id: "ffi";
+    private readonly ffi;
+    private readonly getContext;
+    private readonly sampleRate;
+    private readonly maxSecondsPerPhrase;
+    constructor(args: {
+        ffi: ElizaInferenceFfi;
+        ctx?: ElizaInferenceContextHandle;
+        getContext?: () => ElizaInferenceContextHandle;
+        sampleRate?: number;
+        maxSecondsPerPhrase?: number;
+    });
+    /** True when the loaded `libelizainference` advertises streaming TTS. */
+    supportsStreamingTts(): boolean;
+    /**
+     * One-shot synthesis returning the whole phrase as an `AudioChunk`.
+     * When the loaded build advertises streaming TTS this routes through
+     * `eliza_inference_tts_synthesize_stream` and concatenates the
+     * delivered chunks (so the chunk-aware native path is exercised even
+     * for whole-phrase callers); otherwise it uses the batch
+     * `eliza_inference_tts_synthesize` symbol. `cancelSignal` is honoured
+     * at chunk boundaries — a cancelled stream returns whatever was
+     * synthesized so far.
+     */
+    synthesize(args: {
+        phrase: Phrase;
+        preset: SpeakerPreset;
+        cancelSignal: {
+            cancelled: boolean;
+        };
+        onKernelTick?: () => void;
+    }): Promise<AudioChunk>;
+    /**
+     * Streaming synthesis: forwards to `eliza_inference_tts_synthesize_stream`
+     * when the build advertises a streaming decoder. When it does NOT
+     * (`tts_stream_supported() == 0`), this still satisfies the seam — but
+     * with exactly one body chunk + one final tail (the batch synthesis
+     * result), so the caller never mistakes a non-streaming build for a
+     * streaming one (no fallback sludge — the chunk count is the honest
+     * signal). The native side checks `ctx->tts_cancel` (set via
+     * `eliza_inference_cancel_tts`) on top of the `onChunk` return value.
+     * A non-streaming build cannot be interrupted while the native batch
+     * forward pass is inside `ttsSynthesize`; it only observes cancellation
+     * before emitting the body chunk. Barge-in-critical product paths should
+     * require `supportsStreamingTts()`.
+     */
+    synthesizeStream(args: {
+        phrase: Phrase;
+        preset: SpeakerPreset;
+        cancelSignal: {
+            cancelled: boolean;
+        };
+        onChunk: (chunk: TtsPcmChunk) => boolean | undefined;
+        onKernelTick?: () => void;
+    }): Promise<{
+        cancelled: boolean;
+    }>;
+    /** Hard-cancel any in-flight TTS forward pass on this backend's context. */
+    cancelTts(): void;
+    /**
+     * Batch transcription. One-shot callers should use the fused batch ABI
+     * directly so the native side receives the original sample-rate metadata
+     * and can apply its own audio preprocessing. Live mic streaming remains
+     * available through `EngineVoiceBridge.createStreamingTranscriber()`.
+     */
+    transcribe(args: TranscriptionAudio): Promise<string>;
+    /** Transcribe + per-word timings when the fused build is ABI v12+; otherwise
+     *  the text with empty `words` (the caller degrades to segment highlight). */
+    transcribeTimed(args: TranscriptionAudio): Promise<{
+        text: string;
+        words: AsrWordTiming[];
+    }>;
+}
+export interface EngineVoiceBridgeOptions {
+    /**
+     * Bundle root on disk. Must contain `cache/voice-preset-default.bin`
+     * and the FFI library (`lib/libelizainference.{dylib,so}`) when
+     * `useFfiBackend === true`.
+     */
+    bundleRoot: string;
+    /**
+     * When true, use `FfiOmniVoiceBackend`. When false, use the deterministic test backend
+     * only for lifecycle/unit tests; live sessions and direct synthesis reject
+     * the deterministic test backend before user-visible audio can be emitted.
+     */
+    useFfiBackend: boolean;
+    /** Override sample rate. Defaults to 24 kHz. */
+    sampleRate?: number;
+    /** Override ring buffer capacity (samples). Defaults to 4 s @ 24 kHz. */
+    ringBufferCapacity?: number;
+    /** Phrase chunker `maxTokensPerPhrase` (no-punctuation run-on cap). Defaults to
+     *  `ELIZA_VOICE_MAX_TOKENS_PER_PHRASE` or 8 (one MTP draft round). */
+    maxTokensPerPhrase?: number;
+    /** Max concurrent TTS phrase dispatches. Defaults to env or scheduler default. */
+    maxInFlightPhrases?: number;
+    /**
+     * Pre-warmed phrase cache entries. Per AGENTS.md §4, a precomputed
+     * phrase cache for common assistant utterances is mandatory for the
+     * first-byte-latency win. Empty by default — callers wire actual
+     * entries from the bundle when available.
+     */
+    prewarmedPhrases?: ReadonlyArray<CachedPhraseAudio>;
+    /**
+     * Optional sink override (e.g. for tests or for routing PCM to a
+     * platform-specific audio device). Defaults to the in-memory sink the
+     * scheduler creates.
+     */
+    sink?: AudioSink;
+    /** Optional scheduler event listeners (rollback, audio, cancel). */
+    events?: SchedulerEvents;
+    /**
+     * Optional override for the TTS backend. When set, supersedes
+     * `useFfiBackend`. Tests use this to inject a controllable backend
+     * (e.g. one that holds synthesis open until a deferred resolves) so
+     * rollback timing can be observed deterministically.
+     */
+    backendOverride?: OmniVoiceBackend;
+    /**
+     * Override only the TTS backend while keeping the fused bundle lifecycle
+     * and ASR FFI loaded. Used when a bundle falls back from OmniVoice speech
+     * to Kokoro speech but still needs bundled Qwen3-ASR for mic input.
+     */
+    ttsBackendOverride?: OmniVoiceBackend;
+    /** Optional speaker preset paired with `ttsBackendOverride`. */
+    speakerPresetOverride?: SpeakerPreset;
+    /**
+     * Optional shared resource registry. When the bridge is created
+     * inside an engine that already owns one (text + voice on the same
+     * tokenizer / mmap regions), the engine passes its registry in so
+     * voice ref-counts against the same canonical resources. Tests can
+     * leave this unset to get a private registry.
+     */
+    sharedResources?: SharedResourceRegistry;
+    /**
+     * Optional lifecycle loaders override. Production wires real
+     * `madvise`-backed mmap handles via the FFI; tests inject mocks so
+     * the disarm path can assert eviction without a real file mapping.
+     * When unset, default loaders are derived from the bundle root.
+     */
+    lifecycleLoaders?: VoiceLifecycleLoaders;
+    /**
+     * Construct a `KokoroTtsBackend` directly and skip the bundle-root +
+     * speaker-preset + FFI checks the fused omnivoice path requires.
+     * Kokoro voices are picked by id (`KOKORO_VOICE_PACKS`), so the bundle's
+     * per-user speaker preset is not used. Mutually exclusive with
+     * `useFfiBackend: true` and `backendOverride`. Lifecycle loaders
+     * default to empty lifecycle handles (ORT owns the model memory; nothing to
+     * mmap-evict).
+     */
+    kokoroOnly?: KokoroEngineDiscoveryResult;
+    /**
+     * Optional pre-loaded fused inference handle for the `kokoroOnly` path. When
+     * set, the Kokoro FFI runtime reuses it instead of dlopen-ing a second copy
+     * of `libelizainference` (tests inject a stub; production may share the
+     * engine's handle).
+     */
+    kokoroFfi?: ElizaInferenceFfi;
+    /**
+     * Optional voice-profile store for speaker-attribution. When set, the
+     * bridge constructs a `VoiceAttributionPipeline` and runs attribution
+     * in parallel with ASR on every turn via `runVoiceTurn`. Callers receive
+     * the resolved `VoiceAttributionOutput` via `onAttribution` in the turn
+     * events passed to `runVoiceTurn`.
+     *
+     * When absent, attribution is skipped and the pipeline operates exactly
+     * as before (no diarizer / encoder overhead).
+     */
+    profileStore?: VoiceProfileStore;
+    /**
+     * W3-9 / F1 — the agent runtime. When supplied, the bridge constructs a
+     * `VoiceCancellationCoordinator` and an `OptimisticGenerationPolicy`
+     * scoped to this voice session. The coordinator owns one cancellation
+     * token per `roomId` and fans abort out to:
+     *   1. `runtime.turnControllers.abortTurn(roomId, reason)` — the
+     *      planner-loop / action handlers / streaming `useModel` see the
+     *      abort within one tick.
+     *   2. The slot-abort callback (`slotAbort`) when the LM slot id is
+     *      registered with the turn.
+     *   3. The TTS hard-stop callback (`ttsStop`), which the bridge wires
+     *      to its existing `triggerBargeIn()` (audio sink drain + FFI/HTTP
+     *      synthesis cancel).
+     *   4. The standard `AbortSignal` every fetch / `useModel` / FFI call
+     *      that took `token.signal` honours.
+     *
+     * The reverse direction (runtime → voice) is wired symmetrically via
+     * the coordinator's `runtime.turnControllers.onEvent` subscription.
+     *
+     * Omit to keep the prior behaviour — the bridge then exposes no
+     * coordinator / policy and callers fall back to the legacy
+     * `BargeInController` + `triggerBargeIn()` surface.
+     *
+     * Structural type — `CoordinatorRuntime` is the minimum surface the
+     * coordinator needs (`turnControllers.{abortTurn, onEvent}`). Production
+     * passes a full `IAgentRuntime`; tests can pass a fake matching the
+     * structural shape.
+     */
+    runtime?: IAgentRuntime | CoordinatorRuntime;
+    /**
+     * W3-9 / F1 — optional `OptimisticGenerationPolicy` overrides. When
+     * `runtime` is set and `optimisticPolicyOptions` is omitted, the bridge
+     * constructs a default policy gated on the resolved power source
+     * (plugged-in / battery / unknown) and the canonical EOT threshold.
+     */
+    optimisticPolicyOptions?: OptimisticPolicyOptions;
+    /**
+     * W3-9 / F1 — optional LM slot-abort callback for the cancellation
+     * coordinator. Production wires this to `MtpLlamaServer.abortSlot`
+     * once a slot id is known per turn. The bridge passes this directly
+     * into the coordinator; the bridge itself does not own slot ids.
+     *
+     * Has no effect when `runtime` is unset (no coordinator is constructed).
+     */
+    slotAbort?: (slotId: number, reason: VoiceCancellationReason) => void;
+    /**
+     * Live speaker-attribution gating. When set alongside a `profileStore` AND
+     * a full `runtime` (with `emitEvent`), `runVoiceTurn` automatically:
+     *   1. emits `VOICE_TURN_OBSERVED` for every attributed turn, and
+     *   2. folds the diarization decision into the turn's `voiceTurnSignal`
+     *      (stamped onto `output.turn.metadata`) so the server gate
+     *      `core.voice_turn_signal` can suppress confident-bystander cross-talk.
+     *
+     * `knownSpeakerEntityIds` / `ownerEntityId` may be functions so the caller
+     * can resolve the enrolled-speaker set lazily per turn (the household roster
+     * changes as people are named). When omitted, attribution still emits
+     * `VOICE_TURN_OBSERVED` and produces a fail-open signal (no bystander
+     * suppression — every attribution is treated as potentially addressed to us).
+     */
+    liveAttribution?: LiveAttributionConfig;
+}
+/** Gating inputs for the automatic live-attribution → voiceTurnSignal seam. */
+export interface LiveAttributionConfig {
+    /** Owner / primary-enrolled entity id (always allowed to speak). */
+    ownerEntityId?: string | (() => string | null | undefined);
+    /** Entity ids the agent answers without a wake word (owner + enrolled). */
+    knownSpeakerEntityIds?: readonly string[] | (() => readonly string[] | undefined);
+    /** True when a wake word fired within the recent listen window. */
+    wakeWordActive?: boolean | (() => boolean);
+}
+export declare function createKokoroTtsBackend(kokoro: KokoroEngineDiscoveryResult, opts?: {
+    bundleRoot?: string;
+    ffi?: ElizaInferenceFfi;
+}): KokoroTtsBackend;
+export declare function createKokoroSpeakerPreset(kokoro: KokoroEngineDiscoveryResult): SpeakerPreset;
+/**
+ * Per-turn events that include the optional attribution result alongside
+ * the existing `VoicePipelineEvents`. The attribution runs in parallel
+ * with ASR; it resolves some time after `onAsrComplete` and before
+ * `onComplete`.
+ */
+export interface VoiceTurnEvents extends VoicePipelineEvents {
+    /**
+     * Called once per turn when the `VoiceAttributionPipeline` resolves
+     * (diarizer + encoder + profile-store match). Only fired when the
+     * bridge was constructed with a `profileStore`. May arrive after
+     * `onAsrComplete` but before `onComplete`. Fire-and-forget from the
+     * bridge's perspective — callers attach the metadata to the turn's
+     * transcript asynchronously.
+     */
+    onAttribution?(output: VoiceAttributionOutput): void;
+}
+/**
+ * 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 declare class EngineVoiceBridge {
+    readonly scheduler: VoiceScheduler;
+    readonly backend: OmniVoiceBackend;
+    readonly lifecycle: VoiceLifecycle;
+    /** Loaded FFI handle when running against the fused build (else null). */
+    readonly ffi: ElizaInferenceFfi | null;
+    /** Lazily-created FFI context this bridge owns; destroyed in `dispose()`. */
+    private readonly ffiContextRef;
+    readonly asrAvailable: boolean;
+    private readonly bundleRoot;
+    /** The phrase cache the scheduler dispatches against — held so the bridge
+     *  can answer "is phrase X cached" for the first-audio filler and seed the
+     *  idle-time auto-prewarm. */
+    private readonly phraseCache;
+    /** In-flight fused turn (`runVoiceTurn`), if any — cancelled on barge-in. */
+    private activePipeline;
+    /**
+     * Optional attribution pipeline. Populated when the bridge was created
+     * with a `profileStore` option. When present, `runVoiceTurn` fires
+     * attribution in parallel with ASR and delivers the result via
+     * `VoiceTurnEvents.onAttribution`.
+     */
+    private readonly attributionPipeline;
+    /**
+     * Full agent runtime, retained only when `opts.runtime` supports
+     * `emitEvent` (i.e. it is a real `IAgentRuntime`, not the structural
+     * `CoordinatorRuntime` a test may pass). Used by the automatic
+     * live-attribution seam in `runVoiceTurn` to emit `VOICE_TURN_OBSERVED`.
+     * Null when no event-capable runtime was supplied.
+     */
+    private readonly eventRuntime;
+    /** Gating inputs for the live-attribution → voiceTurnSignal seam. */
+    private readonly liveAttribution;
+    /**
+     * W3-9 / F1 — voice cancellation coordinator. Populated when the bridge
+     * was created with a `runtime` option. Owns one
+     * `VoiceCancellationToken` per active `roomId` and fans abort out to
+     * the runtime turn controller, the LM slot, the TTS pipeline, and the
+     * standard `AbortSignal`. See `cancellation-coordinator.ts` for the
+     * full contract.
+     */
+    private readonly cancellationCoordinator;
+    /**
+     * W3-9 / F1 — optimistic-generation policy. Constructed once per
+     * session when `runtime` is supplied. Gates the speculative LM prefill
+     * at the `firePrefill` site (see `voice-state-machine.ts`). Hot-swappable
+     * via `setPowerSource()` / `setOverride()` from Settings or a device-
+     * event listener.
+     */
+    private readonly optimisticGenerationPolicy;
+    /**
+     * W3-9 / F1 — per-room `BargeInController` bindings the bridge owns.
+     * Holds the unsubscribe handle returned by
+     * `coordinator.bindBargeInController` so `dispose()` can tear them down.
+     */
+    private readonly bargeInBindings;
+    private constructor();
+    get ffiCtx(): ElizaInferenceContextHandle | null;
+    /**
+     * 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(): void;
+    /**
+     * 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: EngineVoiceBridgeOptions): EngineVoiceBridge;
+    /**
+     * Kokoro-only path. Skips bundle-root / speaker-preset / FFI checks
+     * (Kokoro picks voices by id against `KOKORO_VOICE_PACKS`) and
+     * synthesizes a minimal `SpeakerPreset` keyed to the discovered voice
+     * id. Defaults lifecycle loaders to empty handles since ORT owns the
+     * model memory. `asrAvailable` is `false`: callers needing ASR
+     * construct `createStreamingTranscriber` directly.
+     */
+    private static startKokoroOnly;
+    /**
+     * True when this bridge runs against a TTS backend that produces real
+     * audio — i.e. anything but the `StubOmniVoiceBackend` (which yields
+     * zeros and is tests-only). The prewarm + first-audio-filler paths gate
+     * on this so the cache never holds silence (AGENTS.md §3 — no fake data).
+     */
+    hasRealTtsBackend(): boolean;
+    /**
+     * Lazy-load the TTS mmap region, optional ASR region, 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.
+     */
+    arm(): Promise<void>;
+    /**
+     * Drain in-flight TTS, settle the scheduler, then disarm the
+     * lifecycle. Disarm calls `evictPages()` (madvise / VirtualUnlock
+     * equivalent) on the TTS + optional 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).
+     */
+    disarm(): Promise<void>;
+    /**
+     * 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).
+     */
+    pushAcceptedToken(token: TextToken, acceptedAt?: number): Promise<void>;
+    /**
+     * MTP 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.
+     */
+    pushRejectedRange(range: RejectedTokenRange): Promise<void>;
+    /**
+     * 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(): void;
+    /**
+     * W3-9 / F1 — the canonical voice cancellation coordinator for this
+     * session, or `null` when the bridge was constructed without a
+     * `runtime` option. Callers (turn controller, mic VAD source, UI cancel
+     * route) use this to arm per-turn tokens, fire `bargeIn(roomId)` on
+     * VAD speech-start, fire `revokeEot(roomId)` when the turn detector
+     * revokes a tentative EOT, etc. See
+     * `plugins/plugin-local-inference/docs/voice-cancellation-contract.md`.
+     */
+    cancellationCoordinatorOrNull(): VoiceCancellationCoordinator | null;
+    /**
+     * W3-9 / F1 — the optimistic-generation policy for this session, or
+     * `null` when the bridge was constructed without a `runtime` option.
+     * The bridge primes it with the resolved power source at construction
+     * time; callers can mutate it via `setPowerSource()` / `setOverride()`
+     * to respond to Settings toggles or battery-state events.
+     */
+    optimisticPolicyOrNull(): OptimisticGenerationPolicy | null;
+    /**
+     * W3-9 / F1 — bind the scheduler's `BargeInController` into the
+     * cancellation coordinator for `roomId`. Subsequent
+     * `BargeInController.hardStop()` calls (typically fired by the
+     * ASR-confirmed barge-in words ladder) translate into
+     * `coordinator.bargeIn(roomId)` so the canonical token (and every
+     * downstream consumer: runtime turn abort, LM slot abort, TTS stop,
+     * AbortSignal) sees the abort.
+     *
+     * Idempotent per `roomId` — repeated calls for the same room return
+     * the same unsubscribe handle (the prior binding is torn down first).
+     *
+     * When the bridge was constructed without a `runtime` option, this returns
+     * an empty unsubscribe. Callers should still call it
+     * unconditionally — back-compat for the legacy path is automatic.
+     */
+    bindBargeInControllerForRoom(roomId: string): () => void;
+    /**
+     * 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.
+     */
+    settle(): Promise<void>;
+    synthesizeTextToWav(text: string, signal?: AbortSignal): Promise<Uint8Array>;
+    /**
+     * The streaming-TTS seam W9's scheduler drives: returns the active
+     * backend as a `StreamingTtsBackend` (`FfiOmniVoiceBackend` against the
+     * fused build, `StubOmniVoiceBackend` for tests). The scheduler calls
+     * `synthesizeStream(...)` for each phrase and writes the delivered PCM
+     * segments into its `PcmRingBuffer` on the same scheduler tick. Returns
+     * null when an injected `backendOverride` does not implement the seam.
+     */
+    streamingTtsBackend(): StreamingTtsBackend | null;
+    /**
+     * True when the loaded fused `libelizainference` runs the MTP
+     * speculative loop in-process and can emit native accept/reject
+     * verifier events. When true, callers (W9's turn controller /
+     * `ffi-streaming-backend.ts` wiring) should subscribe via
+     * `subscribeNativeVerifier()` and SKIP the `llama-server` SSE
+     * `{"verifier":{"rejected":[a,b]}}` side-channel — the SSE path stays
+     * only as the non-fused desktop text fallback. False whenever there is
+     * no FFI handle or the build pre-dates the verifier callback.
+     */
+    hasNativeVerifier(): boolean;
+    /**
+     * Register the native MTP verifier callback on the fused runtime
+     * and adapt each `NativeVerifierEvent` into the rollback-queue domain:
+     * accepted/corrected token-id ranges become `VerifierStreamEvent`s and
+     * rejected ranges become `RejectedTokenRange`s fed to `pushRejectedRange`.
+     * The returned handle MUST be `close()`d (clears the native callback +
+     * frees the bun:ffi `JSCallback`). Throws if no fused runtime is loaded.
+     *
+     * `onEvent` (optional) also receives the raw `NativeVerifierEvent` for
+     * callers that want the accepted-token stream (W9's phrase-chunker can
+     * commit accepted draft tokens directly off this instead of round-trip
+     * SSE deltas).
+     */
+    subscribeNativeVerifier(onEvent?: (event: NativeVerifierEvent) => void): {
+        close(): void;
+    };
+    prewarmPhrases(texts: ReadonlyArray<string>, opts?: {
+        concurrency?: number;
+    }): Promise<{
+        warmed: number;
+        cached: number;
+    }>;
+    /**
+     * Idle-time auto-prewarm hook: synthesize the canonical phrase-cache seed
+     * (`DEFAULT_PHRASE_CACHE_SEED`) so common openers/acks are cached before
+     * the next turn. The voice bridge / connector calls this when the loop is
+     * idle. No-op (returns `{ warmed: 0, cached: 0 }`) unless a real TTS
+     * backend is present and voice is armed — we never cache the test backend's zeros
+     * (AGENTS.md §3).
+     */
+    prewarmIdlePhrases(opts?: {
+        concurrency?: number;
+    }): Promise<{
+        warmed: number;
+        cached: number;
+    }>;
+    /**
+     * First-audio filler (AGENTS.md §4 / H4): the instant W1's VAD fires
+     * `speech-start`, play a short cached acknowledgement ("one sec", "okay",
+     * …) into the audio sink to mask first-token latency. W9's turn controller
+     * owns the call site (it gets the `speech-start` event and the cutover to
+     * real `replyText` audio); this method is the seam.
+     *
+     * It only ever plays audio that is *already in the phrase cache* — it does
+     * not synthesize. Returns the filler text that was played, or `null` if no
+     * filler was played (no real TTS backend, voice not armed, or none of the
+     * filler phrases are cached). When real reply audio is ready, W9 cuts over
+     * by writing it through the scheduler as usual (a `triggerBargeIn()` or a
+     * direct `ringBuffer.drain()` truncates any still-playing filler first).
+     */
+    playFirstAudioFiller(): string | null;
+    /**
+     * Construct a `StreamingTranscriber` for live ASR — the contract the
+     * voice turn controller (W9) feeds mic frames into and the barge-in
+     * word-confirm gate (W1) listens to. Resolves the adapter chain:
+     *   fused `libelizainference` streaming ASR (final path, gated on a
+     *   working decoder AND a bundled ASR model) → fused batch ASR over the
+     *   same bundled model → `AsrUnavailableError`. The Eliza-1 bridge runs
+     *   only the fused path; the whisper.cpp interim fallback has been removed.
+     *
+     * Pass W1's `vad` event stream to gate decoding to active speech
+     * windows. Caller owns the returned transcriber's lifecycle (`dispose()`).
+     */
+    createStreamingTranscriber(opts?: {
+        vad?: VadEventSource;
+    }): StreamingTranscriber;
+    /**
+     * Batch transcription: one-shot over a whole PCM buffer. When the active
+     * backend exposes the fused batch ASR ABI, use it directly so the native
+     * side receives the original sample rate and can apply its own resampling.
+     * Otherwise drive a `StreamingTranscriber` (fused streaming ASR →
+     * fused-batch interim) by feeding the buffer as a single frame and
+     * `flush()`ing. Throws `AsrUnavailableError` when no ASR backend is
+     * available — never a silent empty string.
+     */
+    /** Transcribe + per-word timings through the fused ASR (v12). Prefers the
+     *  backend's timed path; falls back to the plain transcript with empty
+     *  `words` when timing isn't available. */
+    transcribePcmTimed(args: TranscriptionAudio, signal?: AbortSignal): Promise<{
+        text: string;
+        words: AsrWordTiming[];
+    }>;
+    transcribePcm(args: TranscriptionAudio, signal?: AbortSignal): Promise<string>;
+    /**
+     * Run one fused mic→speech turn through the overlapped `VoicePipeline`
+     * (AGENTS.md §4): ASR streams; the instant its last token lands the
+     * MTP drafter and the target verifier kick off concurrently, accepted
+     * tokens flow into this bridge's phrase chunker → TTS → ring buffer on
+     * the same tick, rejected draft tails roll back not-yet-spoken audio, and
+     * a mic-VAD barge-in cancels everything at the next kernel boundary.
+     *
+     * The drafter + verifier are wired against the running MTP llama-server
+     * (`textRunner`); the transcriber is the fused ABI's ASR when this bridge
+     * was started with the FFI backend and the bundle ships an `asr/` region.
+     * In voice mode a missing ASR region is a hard `VoiceStartupError` — no
+     * silent cloud fallback (AGENTS.md §3 + §7).
+     *
+     * Resolves with the turn's exit reason. Throws if no turn is wired or one
+     * is already in flight. The created pipeline is held until the turn ends
+     * so `bargeIn()` can cancel it.
+     */
+    runVoiceTurn(audio: TranscriptionAudio, textRunner: MtpTextRunner, config: VoicePipelineConfig, events?: VoiceTurnEvents): Promise<"done" | "token-cap" | "cancelled">;
+    /** Construct the `VoicePipeline` for this bridge (no-run). Exposed for tests. */
+    buildPipeline(textRunner: MtpTextRunner, config: VoicePipelineConfig, events?: VoicePipelineEvents): VoicePipeline;
+    /**
+     * Resolve the pipeline's ASR backend: a live `StreamingTranscriber` —
+     * the fused `eliza_inference_asr_stream_*` decoder when the loaded build
+     * advertises one and the bundle ships an `asr/` region, else the fused
+     * batch ASR adapter. The `VoicePipeline` drives it as a batch
+     * (feed the whole utterance, `flush()`, split the transcript into
+     * tokens). When no ASR backend is available the failure is surfaced as a
+     * `MissingAsrTranscriber` that throws on first use — AGENTS.md §3, no
+     * silent cloud fallback.
+     */
+    private resolveTranscriber;
+    /** Diagnostic accessor — bundle root the bridge is wired against. */
+    bundlePath(): string;
+    private assertVoiceOn;
+}
+export declare function encodeMonoPcm16Wav(pcm: Float32Array, sampleRate: number): Uint8Array;
+export declare function decodeMonoPcm16Wav(bytes: Uint8Array): TranscriptionAudio;
+/**
+ * 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, arming calls
+ * `ffi.mmapAcquire(ctx, "tts" | "asr")` before the lifecycle can enter
+ * `voice-on`, and the returned handles' `evictPages()` calls forward
+ * to `ffi.mmapEvict(ctx, "tts" | "asr")`. The C ABI is declared in
+ * `scripts/omnivoice-fuse/ffi.h`. Production builds may implement this
+ * as page eviction or as a full voice-runtime unload for mobile RAM
+ * pressure; callers must reacquire before using the region again. The
+ * compatibility library returns `ELIZA_ERR_NOT_IMPLEMENTED`, which the binding raises as
+ * `VoiceLifecycleError({code:"kernel-missing"})`.
+ *
+ * When `ffi` is null, acquire/evict are documented empty transitions — used by the
+ * development TTS path in tests + dev (no real mmap exists). Directory and
+ * "contains at least one file" checks still run for both TTS and ASR.
+ * ASR never gets a virtual fallback: voice-on requires a real bundled ASR
+ * model file so the FFI path can acquire the `"asr"` region and surface
+ * the fused ABI's diagnostic if the runtime lacks the required region support.
+ */
+interface FfiContextRef {
+    current: ElizaInferenceContextHandle | null;
+    ensure(): ElizaInferenceContextHandle;
+}
+declare function defaultLifecycleLoaders(bundleRoot: string, ffi: ElizaInferenceFfi | null, ctx: ElizaInferenceContextHandle | FfiContextRef | null): VoiceLifecycleLoaders;
+/** Re-export for the engine and tests that want the default loader. */
+export { defaultLifecycleLoaders };
+export declare function isOmniVoiceBundleAvailable(bundleRoot: string): boolean;
+//# sourceMappingURL=engine-bridge.d.ts.map