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

package/src/services/voice/wake-word-ggml.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Wake-word detection — native runtime binding.
+ *
+ * Loads the standalone `packages/native/plugins/wakeword-cpp/`
+ * library directly via `bun:ffi` and exposes the same `WakeWordModel`
+ * interface as the previous `onnxruntime-node`-backed implementation
+ * in `./wake-word.ts`, so the voice lifecycle can swap the two without
+ * changing anything upstream.
+ *
+ * Phase 2 status — this binding is now the default when the
+ * `libwakeword.{so,dylib,dll}` shared library and three converted
+ * GGUFs are present. The C runtime is a pure-fp32 reference
+ * implementation of the openWakeWord three-stage pipeline (melspec
+ * → embedding CNN → classifier head) — no ggml link, no SIMD; a
+ * laptop CPU runs it under 1 % of real time. ABI parity with the
+ * upstream openWakeWord ONNX graphs is gated by
+ * `packages/native/plugins/wakeword-cpp/test/wakeword_parity_test.py`.
+ *
+ * The ONNX path in `./wake-word.ts` stays as the fallback while the
+ * native binding shakes out. Once the migration is complete the ONNX
+ * path can be removed alongside the `onnxruntime-node` dependency.
+ *
+ * Three GGUFs back one session, mirroring openWakeWord's three ONNX
+ * graphs (the C library is the single source of truth on shapes —
+ * see `packages/native/plugins/wakeword-cpp/include/wakeword/wakeword.h`):
+ *
+ *   1. melspec    — 16 kHz PCM → 32-bin log-mel frames.
+ *   2. embedding  — 20-Conv2D CNN over a 76-mel-frame sliding window
+ *                   → 96-dim embedding.
+ *   3. classifier — 4-layer MLP over a 16-embedding window → P(wake)
+ *                   ∈ [0, 1].
+ */
+import type { WakeWordModel } from "./types";
+/** Three GGUF paths that back one session. */
+export interface WakeWordGgmlPaths {
+    /** Frozen Hann window + mel filter bank + STFT params metadata. */
+    melspec: string;
+    /** Embedding-CNN weights (fp16) + architecture metadata. */
+    embedding: string;
+    /** Classifier-head weights (fp16) + (1, 16, 96) input shape. */
+    classifier: string;
+}
+export interface WakeWordGgmlConfig {
+    /** Detection threshold ∈ [0, 1]. Default 0.5 (matches upstream openWakeWord). */
+    threshold?: number;
+}
+/**
+ * Thrown when the native ggml backend cannot be used. Distinct from
+ * `WakeWordUnavailableError` in `./wake-word.ts` so callers that fall
+ * back to the legacy ONNX path can tell the two failure modes apart
+ * during the migration.
+ */
+export declare class WakeWordGgmlUnavailableError extends Error {
+    readonly code: "not-bun" | "library-load-failed" | "model-load-failed" | "abi-error";
+    constructor(code: WakeWordGgmlUnavailableError["code"], message: string);
+}
+/**
+ * Streaming wake-word detector backed by `libwakeword`.
+ *
+ * Implements the same `WakeWordModel` interface as `OpenWakeWordModel`
+ * in `./wake-word.ts` so the voice lifecycle can swap implementations
+ * without changing anything upstream.
+ */
+export declare class OpenWakeWordGgmlModel implements WakeWordModel {
+    private readonly lib;
+    private readonly handle;
+    readonly frameSamples = 1280;
+    readonly sampleRate = 16000;
+    private constructor();
+    /**
+     * Load a wake-word model from its three GGUFs and the
+     * `libwakeword` shared library. Returns a ready-to-use detector
+     * with a fresh streaming session. Throws
+     * `WakeWordGgmlUnavailableError` on dlopen / ABI / GGUF failure.
+     */
+    static load(args: {
+        libraryPath: string;
+        paths: WakeWordGgmlPaths;
+        config?: WakeWordGgmlConfig;
+    }): Promise<OpenWakeWordGgmlModel>;
+    /**
+     * Score one 1280-sample (80 ms @ 16 kHz) fp32 mono frame and
+     * return the most recent classifier probability ∈ [0, 1]. Early
+     * frames (before enough mel + embedding context has accumulated)
+     * return 0.
+     */
+    scoreFrame(frame: Float32Array): Promise<number>;
+    /**
+     * Streaming state lives on the native side. The C ABI does not
+     * expose a separate `reset` entry point yet (Phase 2 will add one
+     * if the ggml-backed implementation needs it); for now, reset is
+     * a no-op on the JS side. Callers that need a hard state clear
+     * close + reopen the session.
+     */
+    reset(): void;
+    /** Release the native session and the dlopen handle. */
+    close(): void;
+    /** Diagnostics: `"native-cpu"` on this build (pure-fp32 reference). */
+    activeBackend(): string;
+}
+//# sourceMappingURL=wake-word-ggml.d.ts.map

package/src/services/voice/wake-word-ggml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wake-word-ggml.d.ts","sourceRoot":"","sources":["wake-word-ggml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAM7C,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IACjC,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IAClC,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACtD,QAAQ,CAAC,IAAI,EACV,SAAS,GACT,qBAAqB,GACrB,mBAAmB,GACnB,WAAW,CAAC;gBACH,IAAI,EAAE,4BAA4B,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM;CAKvE;AAkID;;;;;;GAMG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IAKzD,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IALxB,QAAQ,CAAC,YAAY,QAAiB;IACtC,QAAQ,CAAC,UAAU,SAAe;IAElC,OAAO;IAKP;;;;;OAKG;WACU,IAAI,CAAC,IAAI,EAAE;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,iBAAiB,CAAC;QACzB,MAAM,CAAC,EAAE,kBAAkB,CAAC;KAC5B,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAyClC;;;;;OAKG;IACG,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAuBtD;;;;;;OAMG;IACH,KAAK,IAAI,IAAI;IAIb,wDAAwD;IACxD,KAAK,IAAI,IAAI;IAKb,uEAAuE;IACvE,aAAa,IAAI,MAAM;CAIvB"}

package/src/services/voice/wake-word-ggml.ts

@@ -0,0 +1,320 @@
+/**
+ * Wake-word detection — native runtime binding.
+ *
+ * Loads the standalone `packages/native/plugins/wakeword-cpp/`
+ * library directly via `bun:ffi` and exposes the same `WakeWordModel`
+ * interface as the previous `onnxruntime-node`-backed implementation
+ * in `./wake-word.ts`, so the voice lifecycle can swap the two without
+ * changing anything upstream.
+ *
+ * Phase 2 status — this binding is now the default when the
+ * `libwakeword.{so,dylib,dll}` shared library and three converted
+ * GGUFs are present. The C runtime is a pure-fp32 reference
+ * implementation of the openWakeWord three-stage pipeline (melspec
+ * → embedding CNN → classifier head) — no ggml link, no SIMD; a
+ * laptop CPU runs it under 1 % of real time. ABI parity with the
+ * upstream openWakeWord ONNX graphs is gated by
+ * `packages/native/plugins/wakeword-cpp/test/wakeword_parity_test.py`.
+ *
+ * The ONNX path in `./wake-word.ts` stays as the fallback while the
+ * native binding shakes out. Once the migration is complete the ONNX
+ * path can be removed alongside the `onnxruntime-node` dependency.
+ *
+ * Three GGUFs back one session, mirroring openWakeWord's three ONNX
+ * graphs (the C library is the single source of truth on shapes —
+ * see `packages/native/plugins/wakeword-cpp/include/wakeword/wakeword.h`):
+ *
+ *   1. melspec    — 16 kHz PCM → 32-bin log-mel frames.
+ *   2. embedding  — 20-Conv2D CNN over a 76-mel-frame sliding window
+ *                   → 96-dim embedding.
+ *   3. classifier — 4-layer MLP over a 16-embedding window → P(wake)
+ *                   ∈ [0, 1].
+ */
+
+import type { WakeWordModel } from "./types";
+
+/** PCM frame size the streaming pipeline expects (80 ms @ 16 kHz). */
+const FRAME_SAMPLES = 1280;
+const SAMPLE_RATE = 16_000;
+
+/** Three GGUF paths that back one session. */
+export interface WakeWordGgmlPaths {
+	/** Frozen Hann window + mel filter bank + STFT params metadata. */
+	melspec: string;
+	/** Embedding-CNN weights (fp16) + architecture metadata. */
+	embedding: string;
+	/** Classifier-head weights (fp16) + (1, 16, 96) input shape. */
+	classifier: string;
+}
+
+export interface WakeWordGgmlConfig {
+	/** Detection threshold ∈ [0, 1]. Default 0.5 (matches upstream openWakeWord). */
+	threshold?: number;
+}
+
+/**
+ * Thrown when the native ggml backend cannot be used. Distinct from
+ * `WakeWordUnavailableError` in `./wake-word.ts` so callers that fall
+ * back to the legacy ONNX path can tell the two failure modes apart
+ * during the migration.
+ */
+export class WakeWordGgmlUnavailableError extends Error {
+	readonly code:
+		| "not-bun"
+		| "library-load-failed"
+		| "model-load-failed"
+		| "abi-error";
+	constructor(code: WakeWordGgmlUnavailableError["code"], message: string) {
+		super(message);
+		this.name = "WakeWordGgmlUnavailableError";
+		this.code = code;
+	}
+}
+
+/** Runtime detector — `bun:ffi` is Bun-only. */
+function isBunRuntime(): boolean {
+	return typeof (globalThis as { Bun?: unknown }).Bun !== "undefined";
+}
+
+/**
+ * Native session handle. The C side gives us a pointer (`bigint` under
+ * `bun:ffi`); we never inspect it on the JS side beyond passing it
+ * back through the binding.
+ */
+type NativeHandle = bigint;
+
+/** Bound symbols from `libwakeword`. Mirrors `wakeword.h` 1:1. */
+interface WakeWordBindings {
+	wakeword_open: (
+		melspec: unknown,
+		embedding: unknown,
+		classifier: unknown,
+		outHandle: unknown,
+	) => number;
+	wakeword_close: (handle: NativeHandle) => number;
+	wakeword_process: (
+		handle: NativeHandle,
+		pcm: unknown,
+		nSamples: bigint | number,
+		outScore: unknown,
+	) => number;
+	wakeword_set_threshold: (handle: NativeHandle, threshold: number) => number;
+	wakeword_active_backend: () => unknown;
+}
+
+interface BoundLibrary {
+	bindings: WakeWordBindings;
+	close(): void;
+	libraryPath: string;
+	/** `bun:ffi` helper: encode an ArrayBufferView as a native pointer. */
+	ptr(value: ArrayBufferView): unknown;
+}
+
+/** Minimal shape of the bun:ffi module we use here. */
+interface BunFfiModule {
+	dlopen(
+		path: string,
+		def: Record<string, { args: number[]; returns: number }>,
+	): {
+		symbols: Record<string, (...args: unknown[]) => unknown>;
+		close(): void;
+	};
+	ptr(value: ArrayBufferView): unknown;
+	FFIType: {
+		cstring: number;
+		ptr: number;
+		i32: number;
+		u64: number;
+		f32: number;
+	};
+}
+
+/**
+ * Resolve `bun:ffi` at runtime via the Bun-injected `require`. Mirrors
+ * the loader pattern in `./ffi-bindings.ts` (search for
+ * `loadBunFfiModule`) so plain Node test runs that import this file
+ * for type-only purposes do not blow up at the import site.
+ */
+function loadBunFfiModule(): BunFfiModule {
+	const req: ((id: string) => unknown) | undefined = (
+		globalThis as { Bun?: { __require?: (id: string) => unknown } }
+	).Bun?.__require;
+	if (typeof req === "function") {
+		return req("bun:ffi") as BunFfiModule;
+	}
+	const mod = require("node:module") as {
+		createRequire: (filename: string) => (id: string) => unknown;
+	};
+	const r = mod.createRequire(import.meta.url);
+	return r("bun:ffi") as BunFfiModule;
+}
+
+/**
+ * Load `libwakeword` and bind every symbol declared in `wakeword.h`.
+ * Throws `WakeWordGgmlUnavailableError({code: "library-load-failed"})`
+ * on `dlopen` failure.
+ */
+function loadLibrary(libraryPath: string): BoundLibrary {
+	if (!isBunRuntime()) {
+		throw new WakeWordGgmlUnavailableError(
+			"not-bun",
+			"[wake-word-ggml] bun:ffi is required; current runtime is not Bun",
+		);
+	}
+	if (!libraryPath || libraryPath.length === 0) {
+		throw new WakeWordGgmlUnavailableError(
+			"library-load-failed",
+			"[wake-word-ggml] libraryPath is required",
+		);
+	}
+	const bunFfi = loadBunFfiModule();
+	const T = bunFfi.FFIType;
+	const lib = bunFfi.dlopen(libraryPath, {
+		wakeword_open: {
+			args: [T.ptr, T.ptr, T.ptr, T.ptr],
+			returns: T.i32,
+		},
+		wakeword_close: {
+			args: [T.u64],
+			returns: T.i32,
+		},
+		wakeword_process: {
+			args: [T.u64, T.ptr, T.u64, T.ptr],
+			returns: T.i32,
+		},
+		wakeword_set_threshold: {
+			args: [T.u64, T.f32],
+			returns: T.i32,
+		},
+		wakeword_active_backend: {
+			args: [],
+			returns: T.cstring,
+		},
+	});
+	return {
+		bindings: lib.symbols as unknown as WakeWordBindings,
+		close: () => lib.close(),
+		libraryPath,
+		ptr: (v: ArrayBufferView) => bunFfi.ptr(v),
+	};
+}
+
+/**
+ * Streaming wake-word detector backed by `libwakeword`.
+ *
+ * Implements the same `WakeWordModel` interface as `OpenWakeWordModel`
+ * in `./wake-word.ts` so the voice lifecycle can swap implementations
+ * without changing anything upstream.
+ */
+export class OpenWakeWordGgmlModel implements WakeWordModel {
+	readonly frameSamples = FRAME_SAMPLES;
+	readonly sampleRate = SAMPLE_RATE;
+
+	private constructor(
+		private readonly lib: BoundLibrary,
+		private readonly handle: NativeHandle,
+	) {}
+
+	/**
+	 * Load a wake-word model from its three GGUFs and the
+	 * `libwakeword` shared library. Returns a ready-to-use detector
+	 * with a fresh streaming session. Throws
+	 * `WakeWordGgmlUnavailableError` on dlopen / ABI / GGUF failure.
+	 */
+	static async load(args: {
+		libraryPath: string;
+		paths: WakeWordGgmlPaths;
+		config?: WakeWordGgmlConfig;
+	}): Promise<OpenWakeWordGgmlModel> {
+		const lib = loadLibrary(args.libraryPath);
+		const out = new BigUint64Array(1);
+		/* Each path string needs a NUL terminator; we encode through
+		 * Uint8Array and pass an explicit pointer because bun:ffi does
+		 * not auto-convert Buffer -> cstring on every binding shape. */
+		const enc = new TextEncoder();
+		const melBuf = enc.encode(`${args.paths.melspec}\0`);
+		const embBuf = enc.encode(`${args.paths.embedding}\0`);
+		const clsBuf = enc.encode(`${args.paths.classifier}\0`);
+		const rc = lib.bindings.wakeword_open(
+			lib.ptr(melBuf),
+			lib.ptr(embBuf),
+			lib.ptr(clsBuf),
+			lib.ptr(out),
+		);
+		if (rc !== 0) {
+			lib.close();
+			throw new WakeWordGgmlUnavailableError(
+				"model-load-failed",
+				`[wake-word-ggml] wakeword_open(${args.paths.melspec}, ${args.paths.embedding}, ${args.paths.classifier}) returned ${rc}`,
+			);
+		}
+		const handle = out[0] as NativeHandle;
+		const model = new OpenWakeWordGgmlModel(lib, handle);
+		if (args.config?.threshold !== undefined) {
+			const setRc = lib.bindings.wakeword_set_threshold(
+				handle,
+				args.config.threshold,
+			);
+			if (setRc !== 0) {
+				model.close();
+				throw new WakeWordGgmlUnavailableError(
+					"abi-error",
+					`[wake-word-ggml] wakeword_set_threshold(${args.config.threshold}) returned ${setRc}`,
+				);
+			}
+		}
+		return model;
+	}
+
+	/**
+	 * Score one 1280-sample (80 ms @ 16 kHz) fp32 mono frame and
+	 * return the most recent classifier probability ∈ [0, 1]. Early
+	 * frames (before enough mel + embedding context has accumulated)
+	 * return 0.
+	 */
+	async scoreFrame(frame: Float32Array): Promise<number> {
+		if (frame.length !== FRAME_SAMPLES) {
+			throw new Error(
+				`[wake-word-ggml] scoreFrame expects ${FRAME_SAMPLES} samples; got ${frame.length}`,
+			);
+		}
+		const out = new Float32Array(1);
+		const rc = this.lib.bindings.wakeword_process(
+			this.handle,
+			this.lib.ptr(frame),
+			BigInt(frame.length),
+			this.lib.ptr(out),
+		);
+		if (rc !== 0) {
+			throw new WakeWordGgmlUnavailableError(
+				"abi-error",
+				`[wake-word-ggml] wakeword_process returned ${rc}`,
+			);
+		}
+		const p = out[0] ?? 0;
+		return Math.min(1, Math.max(0, p));
+	}
+
+	/**
+	 * Streaming state lives on the native side. The C ABI does not
+	 * expose a separate `reset` entry point yet (Phase 2 will add one
+	 * if the ggml-backed implementation needs it); for now, reset is
+	 * a no-op on the JS side. Callers that need a hard state clear
+	 * close + reopen the session.
+	 */
+	reset(): void {
+		// Intentionally empty — see jsdoc above.
+	}
+
+	/** Release the native session and the dlopen handle. */
+	close(): void {
+		this.lib.bindings.wakeword_close(this.handle);
+		this.lib.close();
+	}
+
+	/** Diagnostics: `"native-cpu"` on this build (pure-fp32 reference). */
+	activeBackend(): string {
+		const raw = this.lib.bindings.wakeword_active_backend();
+		return typeof raw === "string" ? raw : String(raw ?? "");
+	}
+}

package/src/services/voice/wake-word.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Wake-word detection (openWakeWord) — opt-in, local-mode only.
+ *
+ * Replaces the previous `onnxruntime-node`-backed implementation with a
+ * pure GGML / llama.cpp path. The three-stage openWakeWord pipeline (mel
+ * filterbank → speech embedding model → per-phrase classifier head) is
+ * compiled into one combined GGUF
+ * (`wake/openwakeword.gguf`, produced by
+ * `packages/training/scripts/wakeword/convert_openwakeword_to_gguf.py`)
+ * and executed natively by the fused `libelizainference` build via the
+ * `eliza_inference_wakeword_*` FFI surface (ABI v5).
+ *
+ * The JS side is now a thin adapter over that surface — there is NO ONNX
+ * fallback. When the fused library was built without the wake-word
+ * runtime, the JS path throws a structured `WakeWordUnavailableError`
+ * (AGENTS.md §3, §8 — no silent fallbacks).
+ *
+ * Per `packages/inference/AGENTS.md` §1 + the three-mode rules (§1, §5):
+ *   - openWakeWord (Apache-2.0, ~3 MB) ships in the bundle but is
+ *     **opt-in**: voice mode works without it (push-to-talk / VAD-gated).
+ *   - It is **local-mode only**. In `cloud` mode the surface is hidden
+ *     *and inert* (hide-not-disable §5): the model is not loaded, the
+ *     setting is rejected by the API, no background job runs it.
+ *   - Detections feed the same place a push-to-talk press would: they arm
+ *     a listening window that the VAD gate then bounds.
+ *
+ * Streaming pipeline shape (16 kHz mono):
+ *   - 1280-sample (80 ms) PCM frames per `scoreFrame` call.
+ *   - Internally: mel filterbank → 32-bin frames; embedding model windows
+ *     76 mel frames, hop 8 → 96-dim embedding; head windows 16 embeddings
+ *     → P(wake) in [0, 1].
+ *   - The native runtime owns the audio tail, mel ring and embedding
+ *     ring; the JS side feeds frames and reads back probabilities.
+ */
+import type { ElizaInferenceContextHandle, ElizaInferenceFfi } from "./ffi-bindings";
+/** Directory holding the bundled openWakeWord GGUF inside a bundle. */
+export declare const OPENWAKEWORD_DIR_REL_PATH = "wake";
+/**
+ * Combined wake-word GGUF: contains the mel filterbank constants, the
+ * speech embedding model weights, AND every per-phrase classifier head
+ * (`head.<name>.*` tensors). The fused `libelizainference` build mmaps
+ * this file from `<bundleRoot>/wake/openwakeword.gguf` (or the shared
+ * cache at `<state-dir>/local-inference/wake/openwakeword.gguf`).
+ */
+export declare const OPENWAKEWORD_GGUF_REL_PATH: string;
+/**
+ * Default wake-phrase head shipped with a voice bundle. The documented
+ * default Eliza-1 wake phrase is **"hey eliza"** — a two-word,
+ * four-syllable phrase the openWakeWord TTS-augmented pipeline handles
+ * well. It is replaceable: retrain on a different `--phrase` via
+ * `packages/training/scripts/wakeword/train_eliza1_wakeword_head.py`,
+ * convert to GGUF via
+ * `packages/training/scripts/wakeword/convert_openwakeword_to_gguf.py`,
+ * and re-point this constant.
+ */
+export declare const OPENWAKEWORD_DEFAULT_HEAD = "hey-eliza";
+/**
+ * Heads that are placeholders, not trained on the Eliza-1 wake phrase.
+ *
+ * `hey-eliza` stays in this set until a head trained against the real
+ * phrase ships in every tier bundle (the bundled binary is still the
+ * upstream `hey_jarvis_v0.1` weights renamed). `hey_jarvis` stays by
+ * definition — it is the wrong phrase.
+ *
+ * A real "hey eliza" head HAS been trained and verified end-to-end through
+ * this exact runtime — ~98% true-accept / ~4-7% false-accept on a held-out set
+ * scored via `libwakeword.so` (see
+ * `packages/training/scripts/wakeword/HEY_ELIZA_HEAD_PROVENANCE.md`). It must
+ * be trained with `train_eliza1_wakeword_head.py --no-mel-rescale` to match
+ * this runtime's mel preprocessing.
+ *
+ * The trained GGUFs are now PUBLISHED to `elizaos/eliza-1` at
+ * `voice/wakeword/hey-eliza.{melspec,embedding,classifier}.gguf` and registered
+ * in the voice catalog as `wakeword` v0.3.0 (`VOICE_MODEL_VERSIONS` in
+ * `@elizaos/shared`). `hey-eliza` nonetheless STAYS in this set until that head
+ * ships in every tier BUNDLE's `wake/` dir — the gated `publish_all_eliza1.sh`
+ * re-publish — because the bundles users currently download still carry the
+ * renamed `hey_jarvis` placeholder; removing the flag before the bundle ships
+ * the real head would make the runtime treat the placeholder as authentic.
+ * `hey_jarvis` stays by definition (wrong phrase). A future pass should make
+ * this data-driven off the bundle manifest's `releaseState` rather than
+ * hard-coded.
+ */
+export declare const OPENWAKEWORD_PLACEHOLDER_HEADS: ReadonlySet<string>;
+export declare function isPlaceholderWakeWordHead(head: string): boolean;
+/**
+ * Per-frame wake-word probability source. openWakeWord runs on 80 ms
+ * frames of 16 kHz audio; `scoreFrame` takes one PCM frame and returns
+ * the latest P(wake) in [0, 1] (the head only re-runs once enough
+ * context has accumulated — early frames return 0). Stateful (the
+ * streaming front-end carries its buffers); `reset()` clears it.
+ *
+ * The default backend (`GgmlWakeWordModel`) calls into the native FFI
+ * synchronously; the method is still `async` so the interface fits a
+ * async-friendly backend variant (e.g. worker-thread based) and
+ * matches the same shape the previous ONNX backend exposed to callers.
+ */
+export type { WakeWordModel } from "./types.js";
+import type { WakeWordModel } from "./types.js";
+export interface WakeWordConfig {
+    /** P(wake) above this fires a detection. openWakeWord default ~0.5. */
+    threshold?: number;
+    /**
+     * Refractory frames after a detection during which no new detection
+     * fires (debounce a single utterance into one event).
+     */
+    refractoryFrames?: number;
+}
+/**
+ * Thrown when the native openWakeWord runtime cannot service this call:
+ *   - `ffi-missing`: the FFI handle was not provided to the loader (the
+ *     voice lifecycle hands one in via `loadBundledWakeWordModel`).
+ *   - `runtime-not-ready`: the fused `libelizainference` build does not
+ *     export `eliza_inference_wakeword_*` — the wake-word GGUF runtime
+ *     is not yet compiled into this binary. NOT thrown for an absent
+ *     bundled GGUF (that is "wake word unavailable for this bundle",
+ *     not a broken build — `resolveWakeWordModel` returns null instead).
+ *   - `model-load-failed`: the native side rejected the GGUF or the
+ *     selected head name at session open.
+ */
+export declare class WakeWordUnavailableError extends Error {
+    readonly code: "ffi-missing" | "runtime-not-ready" | "model-load-failed";
+    constructor(code: WakeWordUnavailableError["code"], message: string);
+}
+/** Path to the combined wake-word GGUF and the name of the head to bind. */
+export interface WakeWordModelPaths {
+    /** Absolute path to `wake/openwakeword.gguf`. */
+    gguf: string;
+    /** Name of the classifier head inside the GGUF (e.g. "hey-eliza"). */
+    head: string;
+}
+/**
+ * The real openWakeWord streaming detector, backed by the native FFI.
+ * Owns one `eliza_inference_wakeword_*` session; `scoreFrame` consumes
+ * exactly `frameSamples` (1280) samples at 16 kHz and returns the most
+ * recent head probability the native pipeline produced. The audio tail,
+ * mel ring and embedding ring live on the C side; this class is a thin
+ * handle.
+ */
+export declare class GgmlWakeWordModel implements WakeWordModel {
+    private readonly ffi;
+    private readonly handle;
+    readonly frameSamples = 1280;
+    readonly sampleRate = 16000;
+    private closed;
+    private constructor();
+    /**
+     * True only when the fused `libelizainference` build exports the
+     * wake-word ABI and advertises support at runtime. The wake-word
+     * loader uses this to surface a structured `runtime-not-ready` error
+     * before attempting to open a session.
+     */
+    static isSupported(ffi: ElizaInferenceFfi | null | undefined): boolean;
+    /**
+     * Open a native wake-word session. Throws `WakeWordUnavailableError`
+     * when the runtime is not present or rejects the head name. No silent
+     * fallback (AGENTS.md §3).
+     */
+    static load(opts: {
+        ffi: ElizaInferenceFfi;
+        ctx: ElizaInferenceContextHandle | (() => ElizaInferenceContextHandle);
+        headName: string;
+    }): Promise<GgmlWakeWordModel>;
+    scoreFrame(frame: Float32Array): Promise<number>;
+    reset(): void;
+    close(): void;
+}
+/**
+ * Resolve the bundled wake-word GGUF. Unlike the VAD model this is
+ * *optional* — a missing file means "wake word unavailable for this
+ * bundle", not "broken bundle". Returns null when the GGUF is absent so
+ * callers keep voice mode working (push-to-talk / VAD-gated) without it.
+ *
+ * Search order:
+ *   1. `<bundleRoot>/wake/openwakeword.gguf`
+ *   2. `<state-dir>/local-inference/wake/openwakeword.gguf` (shared cache)
+ *
+ * `head` defaults to the bundle's default wake phrase. The head name is
+ * resolved by the native runtime against tensors inside the GGUF, so it
+ * is validated at open time, not here.
+ *
+ * MUST only be called in `local` mode. The cloud-mode router does not
+ * reach this (the wake-word setting is rejected there) — see AGENTS.md §5
+ * hide-not-disable.
+ */
+export declare function resolveWakeWordModel(opts: {
+    bundleRoot?: string;
+    head?: string;
+}): WakeWordModelPaths | null;
+/** Resolved triple of standalone wakeword-cpp paths (library + 3 GGUFs). */
+export interface WakeWordStandalonePaths {
+    libraryPath: string;
+    melspec: string;
+    embedding: string;
+    classifier: string;
+    head: string;
+}
+export declare function resolveWakeWordStandalonePaths(opts: {
+    bundleRoot?: string;
+    head?: string;
+}): WakeWordStandalonePaths | null;
+/**
+ * Open a wake-word session, preferring the fused `libelizainference`
+ * wake-word path (the single native engine the whole voice pipeline runs
+ * through — the user directive: no separate bun:ffi-musl libs). Falls back to
+ * the standalone `wakeword-cpp` build only when the fused build does not carry
+ * the wake-word GGUF. Returns `null` when neither provider can serve a session.
+ *
+ * Provider order:
+ *   1. `GgmlWakeWordModel` (this file) — the fused-`libelizainference` path
+ *      that consumes `wake/openwakeword.gguf` from the bundle cache via the
+ *      `eliza_inference_wakeword_*` ABI. Tried first whenever the bundled GGUF
+ *      is on disk; uses the same `ffi`/`ctx` as VAD / speaker / TTS / ASR.
+ *   2. `OpenWakeWordGgmlModel` from `./wake-word-ggml.ts` — the standalone
+ *      `packages/native/plugins/wakeword-cpp` build (three GGUFs). Guarded
+ *      fallback for paths where the fused build lacks the wake-word runtime.
+ *
+ * `ffi` and `ctx` come from the voice lifecycle — they are the same
+ * `ElizaInferenceFfi` handle and context the VAD / speaker / TTS / ASR paths
+ * use. The standalone fallback uses neither.
+ */
+export declare function loadBundledWakeWordModel(opts: {
+    ffi: ElizaInferenceFfi;
+    ctx: ElizaInferenceContextHandle | (() => ElizaInferenceContextHandle);
+    bundleRoot?: string;
+    head?: string;
+}): Promise<WakeWordModel | null>;
+/**
+ * Streaming wake-word detector. Feed frames; `onWake` fires once per
+ * detected utterance (refractory-debounced). The voice loop wires
+ * `onWake` to "start a listening window" — exactly what a push-to-talk
+ * press does.
+ *
+ * Only constructed in `local` mode. `cloud` mode never instantiates this
+ * (and `resolveWakeWordModel` is never called there), so the surface is
+ * inert per the hide-not-disable rule.
+ */
+export declare class OpenWakeWordDetector {
+    private readonly model;
+    private readonly cfg;
+    private cooldown;
+    private readonly onWake;
+    constructor(args: {
+        model: WakeWordModel;
+        config?: WakeWordConfig;
+        onWake: () => void;
+    });
+    /**
+     * Score one PCM frame; fire `onWake` on a fresh detection. Resolves
+     * to true when this frame fired the wake word.
+     */
+    pushFrame(frame: Float32Array): Promise<boolean>;
+    reset(): void;
+}
+//# sourceMappingURL=wake-word.d.ts.map

package/src/services/voice/wake-word.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wake-word.d.ts","sourceRoot":"","sources":["wake-word.ts"],"names":[],"mappings":"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"}