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

package/services/local-inference/types.d.ts

@@ -0,0 +1,309 @@
+/**
+ * Local inference model-management types (server-side superset).
+ *
+ * Shared across the service layer, API routes, and renderer.
+ * The catalog is Eliza-curated; installed models are tracked locally in a
+ * JSON registry under the state dir.
+ *
+ * Foundational types that are byte-identical between the server and the
+ * UI client (`AgentModelSlot`, `InstalledModel`, `ModelAssignments`,
+ * `TextGenerationSlot`, `AGENT_MODEL_SLOTS`) live in
+ * `@elizaos/shared/local-inference` and are re-exported here so existing
+ * import paths keep working. The server-only DFlash kernel /
+ * optimization / loaded-cache types remain in this file because no UI
+ * consumer needs them.
+ */
+import { AGENT_MODEL_SLOTS, type AgentModelSlot, type InstalledModel, type ModelAssignments, type TextGenerationSlot } from "@elizaos/shared";
+export { AGENT_MODEL_SLOTS, type AgentModelSlot, type InstalledModel, type ModelAssignments, type TextGenerationSlot, };
+export type ModelBucket = "small" | "mid" | "large" | "xl";
+export type ModelCategory = "chat" | "code" | "tools" | "tiny" | "reasoning" | "drafter";
+export type LocalRuntimeBackend = "node-llama-cpp" | "llama-server";
+/**
+ * Specialised llama.cpp kernels shipped by the buun-llama-cpp / DFlash fork.
+ * Models that declare a `requiresKernel` advertise that they only run
+ * correctly under llama-server when the matching kernel is present.
+ *
+ * The set must stay in sync with `inference/AGENTS.md` §3 mandatory
+ * optimizations and with `DflashBinaryCapabilities.kernels` below — the
+ * capability probe is the runtime gate that refuses to start if a required
+ * kernel is missing.
+ */
+export type LocalRuntimeKernel = "dflash" | "turbo3" | "turbo4" | "turbo3_tcq" | "qjl_full" | "polarquant";
+/**
+ * llama.cpp optimization knobs that the dispatcher can wire into a
+ * `llama-server` spawn. Values come from catalog metadata (per-model) and
+ * environment overrides (per-process). The catalog is the source of truth
+ * for which knobs are *safe* on a given quant; env vars are the operator's
+ * escape hatch and override the catalog when set.
+ */
+export interface LocalRuntimeOptimizations {
+    /** Lookahead decoding window. Maps to `--lookahead N` on llama-server. */
+    lookahead?: number;
+    /**
+     * Built-in n-gram drafter (no separate drafter model). Maps to
+     * `--draft-min` / `--draft-max` / `--draft-min-prob`. Mutually exclusive
+     * with DFlash speculative decoding.
+     */
+    ngramDraft?: {
+        min: number;
+        max: number;
+        minProb: number;
+    };
+    /**
+     * `--parallel N` for continuous batching. The Cache Bridge agent may bump
+     * this default at runtime; the dispatcher reads but does not override.
+     */
+    parallel?: number;
+    /**
+     * Mixture-of-experts expert-tensor offload target. `"cpu"` maps to
+     * `-ot ".*=CPU"` so expert tensors stay in CPU memory and only the
+     * shared layers occupy VRAM.
+     */
+    moeOffload?: "cpu" | "none";
+    /** `--mlock` — pin model pages in RAM. */
+    mlock?: boolean;
+    /** Inverse of `--mmap`; maps to `--no-mmap`. */
+    noMmap?: boolean;
+    /** Multimodal projector path; maps to `--mmproj <path>`. */
+    mmproj?: string;
+    /** `--alias <name>` for the OpenAI-compatible model id. */
+    alias?: string;
+    /** `-fa on` (flash attention). Always on for DFlash. */
+    flashAttention?: boolean;
+    /**
+     * Specialised kernels this model requires from the llama-server fork.
+     * The dispatcher uses this to pick `llama-server` over `node-llama-cpp`
+     * regardless of `preferredBackend`, since the in-process binding cannot
+     * provide these kernels.
+     */
+    requiresKernel?: LocalRuntimeKernel[];
+}
+export interface LocalRuntimeAcceleration {
+    /**
+     * Prefer out-of-process llama-server over the node binding when the
+     * required binary and companion files are available.
+     */
+    preferredBackend?: LocalRuntimeBackend;
+    /** Optimization knobs declared per-model. See `LocalRuntimeOptimizations`. */
+    optimizations?: LocalRuntimeOptimizations;
+    dflash?: {
+        /** Catalog id of the hidden drafter GGUF companion. */
+        drafterModelId: string;
+        specType: "dflash";
+        /** llama-server context for the target model. */
+        contextSize: number;
+        /** llama-server context for the drafter. */
+        draftContextSize: number;
+        /** Default draft range passed to llama-server. */
+        draftMin: number;
+        draftMax: number;
+        /** `--n-gpu-layers` and `--n-gpu-layers-draft` defaults. */
+        gpuLayers: number | "auto";
+        draftGpuLayers: number | "auto";
+        /** Some DFlash drafters are trained against non-thinking text. */
+        disableThinking: boolean;
+    };
+    kvCache?: {
+        /**
+         * llama.cpp KV cache type overrides. Stock builds support f16/q8_0;
+         * TurboQuant-capable forks add tbq3_0/tbq4_0.
+         */
+        typeK?: string;
+        typeV?: string;
+        requiresFork?: "apothic-turboquant" | "buun-llama-cpp";
+    };
+}
+/**
+ * Tokenizer family — names match the upstream model family the GGUF was
+ * trained against. Used by the DFlash drafter pair guard, by the catalog
+ * blurbs, and by any downstream code that needs to make tokenizer-aware
+ * decisions (e.g. spec-decode pairing requires drafter and target to share
+ * the exact vocabulary). Open string union so new families can be added
+ * without a code change in every consumer; the canonical members are
+ * enumerated for tooling.
+ */
+export type TokenizerFamily = "eliza1" | "sentencepiece" | (string & {});
+export interface CatalogModel {
+    /** Stable Eliza id — used as the primary key. */
+    id: string;
+    displayName: string;
+    /** HuggingFace repo slug, e.g. "elizalabs/eliza-1-mobile-1_7b". */
+    hfRepo: string;
+    /** Exact GGUF filename in the repo. */
+    ggufFile: string;
+    /**
+     * Optional Eliza-1 bundle manifest in the same HF repo. When present, the
+     * downloader installs every file listed in the manifest and uses
+     * `ggufFile` as the primary text GGUF inside that bundle.
+     */
+    bundleManifestFile?: string;
+    params: "360M" | "1B" | "1.7B" | "2B" | "3B" | "4B" | "7B" | "8B" | "9B" | "14B" | "16B" | "22B" | "24B" | "27B" | "32B";
+    quant: string;
+    sizeGb: number;
+    /** Minimum system RAM (GB) we recommend before offering this model. */
+    minRamGb: number;
+    category: ModelCategory;
+    bucket: ModelBucket;
+    blurb: string;
+    /**
+     * Hidden entries are installable by id and can be downloaded as companions,
+     * but are omitted from the visible Model Hub catalog.
+     */
+    hiddenFromCatalog?: boolean;
+    /** Models such as DFlash drafters are not valid standalone chat choices. */
+    runtimeRole?: "chat" | "dflash-drafter";
+    /** Parent chat model id when this entry is a hidden companion. */
+    companionForModelId?: string;
+    /** Extra catalog model ids to download alongside this model. */
+    companionModelIds?: string[];
+    /**
+     * Maximum context length supported by the underlying GGUF, in tokens.
+     * This is the GGUF ceiling — actual load-time `contextSize` may be
+     * smaller (capped by the loader's runtime budget). When unset, callers
+     * should treat the model as opting into the loader's default
+     * (`"auto"` for `node-llama-cpp`, model file's reported `n_ctx_train`).
+     *
+     * Long-context models (>= 65k) get a small ranking boost on hosts with
+     * enough RAM/VRAM in `selectRecommendedModelForSlot`; see
+     * `recommendation.ts`.
+     */
+    contextLength?: number;
+    /**
+     * Default GPU offload strategy for this model. `"auto"` lets the loader
+     * decide based on VRAM probing; a number forces that many layers to
+     * VRAM. Per-load overrides (`LocalInferenceLoadArgs.gpuLayers`) win
+     * over this default.
+     */
+    gpuLayers?: "auto" | number;
+    /**
+     * Tokenizer family the GGUF was trained against. Used by the DFlash
+     * drafter pair guard (drafter and target MUST share the same family
+     * for spec-decode to work) and by recommendation/UI code that needs
+     * to surface family-aware messaging.
+     */
+    tokenizerFamily?: TokenizerFamily;
+    /** Runtime-specific acceleration metadata. */
+    runtime?: LocalRuntimeAcceleration;
+}
+export type HardwareFitLevel = "fits" | "tight" | "wontfit";
+export interface MobileHardwareProbe {
+    platform: "ios" | "android" | "web";
+    deviceModel?: string;
+    machineId?: string;
+    osVersion?: string;
+    isSimulator?: boolean;
+    availableRamGb?: number | null;
+    freeStorageGb?: number | null;
+    lowPowerMode?: boolean;
+    thermalState?: "nominal" | "fair" | "serious" | "critical" | "unknown";
+    gpuSupported?: boolean;
+    dflashSupported?: boolean;
+    dflashReason?: string;
+    source?: "native" | "adapter-fallback";
+}
+export interface HardwareProbe {
+    totalRamGb: number;
+    freeRamGb: number;
+    /** Null when no supported GPU is available (CPU-only). */
+    gpu: {
+        backend: "cuda" | "metal" | "vulkan";
+        totalVramGb: number;
+        freeVramGb: number;
+    } | null;
+    cpuCores: number;
+    platform: NodeJS.Platform;
+    arch: NodeJS.Architecture;
+    /** True on Apple Silicon (shared memory — large models are viable on 16GB+). */
+    appleSilicon: boolean;
+    /** Recommended default bucket based on available memory. */
+    recommendedBucket: ModelBucket;
+    /** Source of the probe; "node-llama-cpp" when GPU values come from the binding. */
+    source: "node-llama-cpp" | "os-fallback";
+    /** Mobile-only details used for minspec, storage, and native DFlash gating. */
+    mobile?: MobileHardwareProbe;
+}
+export type DownloadState = "queued" | "downloading" | "completed" | "failed" | "cancelled";
+export interface DownloadJob {
+    jobId: string;
+    modelId: string;
+    state: DownloadState;
+    /** Bytes transferred so far. */
+    received: number;
+    /** Total bytes expected (from Content-Length or HEAD). */
+    total: number;
+    /** Moving-average bytes/sec over the last few seconds. */
+    bytesPerSec: number;
+    /** Milliseconds remaining based on current rate. Null when unknown. */
+    etaMs: number | null;
+    startedAt: string;
+    updatedAt: string;
+    /** Set when state === "failed". */
+    error?: string;
+}
+export interface LocalInferenceDownloadStatus {
+    state: DownloadState | "missing";
+    receivedBytes: number;
+    totalBytes: number;
+    percent: number | null;
+    bytesPerSec: number;
+    etaMs: number | null;
+    updatedAt: string | null;
+    errors: string[];
+}
+export interface ActiveModelState {
+    modelId: string | null;
+    loadedAt: string | null;
+    /**
+     * Human-readable load status. "idle" means nothing loaded.
+     * "loading" is set while we're swapping models.
+     */
+    status: "idle" | "loading" | "ready" | "error";
+    error?: string;
+    /**
+     * Effective KV-cache configuration the loader applied. Populated on
+     * `status === "ready"`; null while loading or on error. The benchmark
+     * harness relies on these to verify per-load overrides actually took
+     * effect (a 128k contextSize request that silently fell back to 8k is
+     * exactly the bug the per-load override path exists to prevent).
+     */
+    loadedContextSize?: number | null;
+    loadedCacheTypeK?: string | null;
+    loadedCacheTypeV?: string | null;
+    loadedGpuLayers?: number | null;
+}
+export interface DownloadEvent {
+    type: "progress" | "completed" | "failed" | "cancelled";
+    job: DownloadJob;
+}
+export declare const TEXT_GENERATION_SLOTS: TextGenerationSlot[];
+export interface LocalInferenceSlotReadiness {
+    slot: TextGenerationSlot;
+    assigned: boolean;
+    assignedModelId: string | null;
+    displayName: string | null;
+    primaryDownloaded: boolean;
+    downloaded: boolean;
+    active: boolean;
+    ready: boolean;
+    state: "unassigned" | "missing" | "downloading" | "downloaded" | "active" | "failed" | "cancelled";
+    requiredModelIds: string[];
+    missingModelIds: string[];
+    installedBytes: number;
+    expectedBytes: number;
+    download: LocalInferenceDownloadStatus;
+    errors: string[];
+}
+export interface LocalInferenceReadiness {
+    updatedAt: string;
+    slots: Record<TextGenerationSlot, LocalInferenceSlotReadiness>;
+}
+export interface ModelHubSnapshot {
+    catalog: CatalogModel[];
+    installed: InstalledModel[];
+    active: ActiveModelState;
+    downloads: DownloadJob[];
+    hardware: HardwareProbe;
+    assignments: ModelAssignments;
+    textReadiness: LocalInferenceReadiness;
+}
+//# sourceMappingURL=types.d.ts.map

package/services/local-inference/types.d.ts.map

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

package/services/local-inference/types.js

@@ -0,0 +1,23 @@
+/**
+ * Local inference model-management types (server-side superset).
+ *
+ * Shared across the service layer, API routes, and renderer.
+ * The catalog is Eliza-curated; installed models are tracked locally in a
+ * JSON registry under the state dir.
+ *
+ * Foundational types that are byte-identical between the server and the
+ * UI client (`AgentModelSlot`, `InstalledModel`, `ModelAssignments`,
+ * `TextGenerationSlot`, `AGENT_MODEL_SLOTS`) live in
+ * `@elizaos/shared/local-inference` and are re-exported here so existing
+ * import paths keep working. The server-only DFlash kernel /
+ * optimization / loaded-cache types remain in this file because no UI
+ * consumer needs them.
+ */
+import { AGENT_MODEL_SLOTS, } from "@elizaos/shared";
+export { AGENT_MODEL_SLOTS, };
+// AgentModelSlot, TextGenerationSlot, AGENT_MODEL_SLOTS, ModelAssignments
+// are re-exported above from @elizaos/shared.
+export const TEXT_GENERATION_SLOTS = [
+    "TEXT_SMALL",
+    "TEXT_LARGE",
+];

package/services/local-inference/verify.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-export of the shared model-file verification module. The canonical
+ * implementation lives in `@elizaos/shared/local-inference` because both
+ * the server (`@elizaos/app-core`) and the UI client (`@elizaos/ui`)
+ * compute the same SHA256 / GGUF-magic checks against on-disk models.
+ */
+export { __registryPathForTests, hashFile, type VerifyResult, type VerifyState, verifyInstalledModel, } from "@elizaos/shared";
+//# sourceMappingURL=verify.d.ts.map

package/services/local-inference/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../../../../src/services/local-inference/verify.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,sBAAsB,EACtB,QAAQ,EACR,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC"}

package/services/local-inference/verify.js

@@ -0,0 +1,7 @@
+/**
+ * Re-export of the shared model-file verification module. The canonical
+ * implementation lives in `@elizaos/shared/local-inference` because both
+ * the server (`@elizaos/app-core`) and the UI client (`@elizaos/ui`)
+ * compute the same SHA256 / GGUF-magic checks against on-disk models.
+ */
+export { __registryPathForTests, hashFile, verifyInstalledModel, } from "@elizaos/shared";

package/services/local-inference/voice/barge-in.d.ts

@@ -0,0 +1,15 @@
+export interface BargeInListener {
+    onCancel(): void;
+}
+export interface CancelSignal {
+    cancelled: boolean;
+}
+export declare class BargeInController {
+    private readonly listeners;
+    private signal;
+    cancelSignal(): CancelSignal;
+    attach(listener: BargeInListener): () => void;
+    onMicActive(): void;
+    reset(): void;
+}
+//# sourceMappingURL=barge-in.d.ts.map

package/services/local-inference/voice/barge-in.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"barge-in.d.ts","sourceRoot":"","sources":["../../../../../../../src/services/local-inference/voice/barge-in.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IACxD,OAAO,CAAC,MAAM,CAAsC;IAEpD,YAAY,IAAI,YAAY;IAI5B,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,IAAI;IAK7C,WAAW,IAAI,IAAI;IAOnB,KAAK,IAAI,IAAI;CAGd"}

package/services/local-inference/voice/barge-in.js

@@ -0,0 +1,20 @@
+export class BargeInController {
+    listeners = new Set();
+    signal = { cancelled: false };
+    cancelSignal() {
+        return this.signal;
+    }
+    attach(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    onMicActive() {
+        this.signal.cancelled = true;
+        for (const l of this.listeners) {
+            l.onCancel();
+        }
+    }
+    reset() {
+        this.signal = { cancelled: false };
+    }
+}

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

@@ -0,0 +1,256 @@
+/**
+ * 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 type { ElizaInferenceContextHandle, ElizaInferenceFfi } from "./ffi-bindings";
+import { VoiceLifecycle, type VoiceLifecycleLoaders } from "./lifecycle";
+import { type CachedPhraseAudio } from "./phrase-cache";
+import { SharedResourceRegistry } from "./shared-resources";
+import { VoiceScheduler, type SchedulerEvents } from "./scheduler";
+import type { AudioChunk, AudioSink, OmniVoiceBackend, Phrase, RejectedTokenRange, SpeakerPreset, TextToken } from "./types";
+/**
+ * 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 declare class VoiceStartupError extends Error {
+    readonly code: "missing-ffi" | "missing-speaker-preset" | "missing-bundle-root" | "missing-fused-build" | "already-started" | "not-started";
+    constructor(code: VoiceStartupError["code"], message: string);
+}
+/**
+ * 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 declare class StubOmniVoiceBackend implements OmniVoiceBackend {
+    readonly id: "stub";
+    private readonly sampleRate;
+    calls: number;
+    constructor(sampleRate?: number);
+    synthesize(args: {
+        phrase: Phrase;
+        preset: SpeakerPreset;
+        cancelSignal: {
+            cancelled: boolean;
+        };
+        onKernelTick?: () => void;
+    }): Promise<AudioChunk>;
+}
+/**
+ * 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 declare class FfiOmniVoiceBackend implements OmniVoiceBackend {
+    readonly id: "ffi";
+    private readonly ffi;
+    private readonly ctx;
+    private readonly sampleRate;
+    private readonly maxSecondsPerPhrase;
+    constructor(args: {
+        ffi: ElizaInferenceFfi;
+        ctx: ElizaInferenceContextHandle;
+        sampleRate?: number;
+        maxSecondsPerPhrase?: number;
+    });
+    synthesize(args: {
+        phrase: Phrase;
+        preset: SpeakerPreset;
+        cancelSignal: {
+            cancelled: boolean;
+        };
+        onKernelTick?: () => void;
+    }): Promise<AudioChunk>;
+}
+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` (will hard-fail at synthesize
+     * time until the fused build lands). When false, use the stub backend
+     * so tests and the streaming-graph integration can run end-to-end
+     * with synthetic PCM.
+     */
+    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`. Defaults to 12. */
+    maxTokensPerPhrase?: 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;
+    /**
+     * 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;
+}
+/**
+ * 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;
+    /** FFI context this bridge owns; destroyed in `dispose()`. */
+    readonly ffiCtx: ElizaInferenceContextHandle | null;
+    private readonly bundleRoot;
+    private constructor();
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    arm(): Promise<void>;
+    /**
+     * 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).
+     */
+    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>;
+    /**
+     * 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.
+     */
+    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;
+    /**
+     * 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>;
+    /** Diagnostic accessor — bundle root the bridge is wired against. */
+    bundlePath(): string;
+}
+/**
+ * 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).
+ */
+declare function defaultLifecycleLoaders(bundleRoot: string, ffi: ElizaInferenceFfi | null, ctx: ElizaInferenceContextHandle | null): VoiceLifecycleLoaders;
+/** Re-export for the engine and tests that want the default loader. */
+export { defaultLifecycleLoaders };
+//# sourceMappingURL=engine-bridge.d.ts.map