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

package/dist/services/voice/kokoro/kokoro-ffi-runtime.d.ts

@@ -0,0 +1,75 @@
+/**
+ * In-process Kokoro-82M runtime over the fused `libelizainference` FFI
+ * (the `eliza_inference_kokoro_*` exports — introduced at ABI v10; the fused
+ * library is currently ABI v12, which adds EOT (v11) and ASR word timestamps
+ * (v12) on top, so these symbols are present in every current build — see
+ * `ELIZA_INFERENCE_ABI_VERSION` in ffi-bindings.ts).
+ *
+ * This is the canonical Kokoro execution path on every platform. It replaces
+ * the local-TCP `KokoroGgufRuntime` (POST `/v1/audio/speech` on a running
+ * llama-server) for the mobile case — iOS and Google Play forbid the app
+ * opening a local TCP socket, so the HTTP→llama-server route cannot ship there.
+ * Kokoro synthesizes through the same dlopen()-ed handle as OmniVoice: the
+ * fused build links Eliza-1's Kokoro engine (its own GGUF reader + iSTFT
+ * decoder) behind `eliza_inference_kokoro_supported/load/synthesize/sample_rate`.
+ *
+ * Ownership: this runtime owns its own FFI handle + context. The context is
+ * created with `create(bundleRoot)` anchored at the bundle root (or the Kokoro
+ * model root when there is no Eliza-1 bundle), mirroring how the desktop fused
+ * text runtime obtains its ctx. The GGUF + the active voice `.bin` are loaded
+ * once via `kokoroLoad` and reloaded only when the requested voice changes.
+ *
+ * No silent fallback (AGENTS.md §3): when the loaded library does not export
+ * the Kokoro symbols (`kokoroSupported() === false`) or the model/voice files
+ * are missing, construction / first synthesis throws a structured
+ * `VoiceLifecycleError` rather than dropping back to the TCP route.
+ */
+import { type ElizaInferenceContextHandle, type ElizaInferenceFfi } from "../ffi-bindings";
+import type { KokoroRuntime, KokoroRuntimeInputs } from "./kokoro-runtime";
+import type { KokoroModelLayout } from "./types";
+export interface KokoroFfiRuntimeOptions {
+    /** Resolved on-disk Kokoro layout (GGUF filename + voices dir + root). */
+    layout: KokoroModelLayout;
+    /**
+     * Directory the FFI context anchors at (`create(bundleRoot)`). Defaults to
+     * the Kokoro model root, which is sufficient for the standalone Kokoro
+     * engine — it loads the GGUF + voice `.bin` by explicit absolute path, not
+     * by bundle convention.
+     */
+    bundleRoot?: string;
+    /**
+     * Inject a pre-loaded FFI handle (the desktop fused engine already owns one).
+     * When omitted the runtime loads its own via `resolveFusedLibraryPath`.
+     */
+    ffi?: ElizaInferenceFfi;
+    /**
+     * Inject a context to reuse. When omitted the runtime creates its own with
+     * `ffi.create(bundleRoot)` and destroys it on `dispose`.
+     */
+    ctx?: ElizaInferenceContextHandle;
+}
+export declare class KokoroFfiRuntime implements KokoroRuntime {
+    readonly id: "gguf";
+    readonly sampleRate: number;
+    private readonly layout;
+    private readonly ffi;
+    private readonly ownsFfi;
+    private readonly ctx;
+    private readonly ownsCtx;
+    /** Voice id currently resident on the ctx (null until first load). */
+    private loadedVoiceId;
+    private disposed;
+    constructor(opts: KokoroFfiRuntimeOptions);
+    synthesize(args: KokoroRuntimeInputs): Promise<{
+        cancelled: boolean;
+    }>;
+    dispose(): void;
+    /**
+     * Load the GGUF + the requested voice `.bin` into the ctx, reloading only
+     * when the voice changes (Kokoro keeps the model resident; swapping voices
+     * is a cheap re-load of the 256-float style tensor).
+     */
+    private ensureVoiceLoaded;
+    private kokoroSynthesize;
+}
+//# sourceMappingURL=kokoro-ffi-runtime.d.ts.map

package/dist/services/voice/kokoro/kokoro-ffi-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kokoro-ffi-runtime.d.ts","sourceRoot":"","sources":["../../../../src/services/voice/kokoro/kokoro-ffi-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,OAAO,EACN,KAAK,2BAA2B,EAChC,KAAK,iBAAiB,EAEtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAcjD,MAAM,WAAW,uBAAuB;IACvC,0EAA0E;IAC1E,MAAM,EAAE,iBAAiB,CAAC;IAC1B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,iBAAiB,CAAC;IACxB;;;OAGG;IACH,GAAG,CAAC,EAAE,2BAA2B,CAAC;CAClC;AAED,qBAAa,gBAAiB,YAAW,aAAa;IACrD,QAAQ,CAAC,EAAE,EAAG,MAAM,CAAU;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAoB;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA8B;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,sEAAsE;IACtE,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,QAAQ,CAAS;gBAEb,IAAI,EAAE,uBAAuB;IA4CnC,UAAU,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;IA4C5E,OAAO,IAAI,IAAI;IAOf;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAoCzB,OAAO,CAAC,gBAAgB;CASxB"}

package/dist/services/voice/kokoro/kokoro-runtime.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Kokoro-82M model runner.
+ *
+ * Execution paths:
+ *
+ *   1. GGUF via llama-server (default). When the host llama-server advertises
+ *      a Kokoro-capable build and exposes `/v1/audio/speech`, we POST text in
+ *      and stream PCM out.
+ *
+ *   2. Python subprocess — eval-loop only. Spawns `python -m kokoro_tts`.
+ *      Never the default in production.
+ */
+import type { KokoroPhonemeSequence, KokoroVoicePack } from "./types";
+/** Pinned GGUF candidate location (carried by our llama.cpp fork). The
+ *  runtime references this only for diagnostics; the fork-side builder
+ *  produces the file at this path. */
+export declare const KOKORO_GGUF_REL_PATH = "voice/kokoro-82m-v1_0.gguf";
+/** One synthesized PCM segment delivered to the streaming backend. */
+export interface KokoroRuntimeChunk {
+    pcm: Float32Array;
+    sampleRate: number;
+    isFinal: boolean;
+}
+/**
+ * Construction-time inputs for a runtime instance. The voice pack contains
+ * the style tensor reference; the runtime is responsible for resolving the
+ * bytes off `layout.voicesDir/<file>`.
+ */
+export interface KokoroRuntimeInputs {
+    phonemes: KokoroPhonemeSequence;
+    voice: KokoroVoicePack;
+    /**
+     * Output sample budget. The runtime always honours the model's native
+     * sample rate (`layout.sampleRate`, usually 24 kHz) — this caps the
+     * total samples to prevent runaway generation. Defaults to 16 seconds
+     * at the layout sample rate (matches the longest phrase the chunker
+     * will emit + headroom).
+     */
+    maxSamples?: number;
+    /** Cancellation signal — polled at chunk boundaries. */
+    cancelSignal: {
+        cancelled: boolean;
+    };
+    /** Per-chunk callback; returning `true` cancels the rest of the run. */
+    onChunk: (chunk: KokoroRuntimeChunk) => boolean | undefined;
+}
+/** Shared runtime contract — `KokoroTtsBackend` depends on this, not the
+ *  concrete classes. Tests inject a mock. */
+export interface KokoroRuntime {
+    readonly id: "gguf" | "python" | "mock";
+    readonly sampleRate: number;
+    synthesize(args: KokoroRuntimeInputs): Promise<{
+        cancelled: boolean;
+    }>;
+    dispose(): void;
+}
+export interface KokoroPythonRuntimeOptions {
+    pythonBinary: string;
+    /** Resolved layout — the subprocess discovers the model under here. */
+    layout: {
+        root: string;
+        sampleRate: number;
+    };
+    /** Optional env passed through to the subprocess. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Subprocess-backed runtime. Spawns `python -m kokoro_tts ...` per
+ * synthesis call (no warm-pool — the Python path is the *eval* path, not
+ * the realtime path). Production code paths never select this; the
+ * fine-tune evaluator wires it explicitly.
+ */
+export declare class KokoroPythonRuntime implements KokoroRuntime {
+    readonly id: "python";
+    readonly sampleRate: number;
+    constructor(opts: KokoroPythonRuntimeOptions);
+    synthesize(_args: KokoroRuntimeInputs): Promise<{
+        cancelled: boolean;
+    }>;
+    dispose(): void;
+}
+export interface KokoroMockRuntimeOptions {
+    sampleRate: number;
+    /** Total samples emitted per synthesis call. */
+    totalSamples?: number;
+    /** Number of body chunks to split the output across. */
+    chunkCount?: number;
+}
+export declare class KokoroMockRuntime implements KokoroRuntime {
+    readonly id: "mock";
+    readonly sampleRate: number;
+    private readonly opts;
+    calls: number;
+    constructor(opts: KokoroMockRuntimeOptions);
+    synthesize(args: KokoroRuntimeInputs): Promise<{
+        cancelled: boolean;
+    }>;
+    dispose(): void;
+}
+//# sourceMappingURL=kokoro-runtime.d.ts.map

package/dist/services/voice/kokoro/kokoro-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kokoro-runtime.d.ts","sourceRoot":"","sources":["../../../../src/services/voice/kokoro/kokoro-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAEtE;;sCAEsC;AACtC,eAAO,MAAM,oBAAoB,+BAA+B,CAAC;AAEjE,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IAClC,GAAG,EAAE,YAAY,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IACnC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,KAAK,EAAE,eAAe,CAAC;IACvB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,YAAY,EAAE;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;IACrC,wEAAwE;IACxE,OAAO,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,GAAG,SAAS,CAAC;CAC5D;AAED;6CAC6C;AAC7C,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,UAAU,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACvE,OAAO,IAAI,IAAI,CAAC;CAChB;AAMD,MAAM,WAAW,0BAA0B;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,qDAAqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IACxD,QAAQ,CAAC,EAAE,EAAG,QAAQ,CAAU;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,IAAI,EAAE,0BAA0B;IAItC,UAAU,CACf,KAAK,EAAE,mBAAmB,GACxB,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;IASlC,OAAO,IAAI,IAAI;CAGf;AAOD,MAAM,WAAW,wBAAwB;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,iBAAkB,YAAW,aAAa;IACtD,QAAQ,CAAC,EAAE,EAAG,MAAM,CAAU;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqC;IAC1D,KAAK,SAAK;gBAEE,IAAI,EAAE,wBAAwB;IASpC,UAAU,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;IAsC5E,OAAO,IAAI,IAAI;CAGf"}

package/dist/services/voice/kokoro/phoneme-stream.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Phoneme streaming for Kokoro-82M.
+ *
+ * Kokoro consumes a sequence of phoneme ids (espeak-ng IPA tokenised against a
+ * small fixed vocab). The scheduler emits phrases at punctuation or
+ * `phoneme-stream` boundaries (see `voice/phrase-chunker.ts` `chunkOn`
+ * option). This module is the seam between those phrase boundaries and the
+ * model's input tensor:
+ *
+ *   text → phonemizer.phonemize() → KokoroPhonemeSequence (ids) → runtime
+ *
+ * For maximum responsiveness the runtime can call `streamPhonemes()` against
+ * an async text iterator (chunked draft tokens) and forward each window of
+ * accumulated ids as soon as a phoneme boundary fires. The default `flushAt`
+ * is one phoneme — i.e. emit progress per id — but production deployments
+ * lift this to ~8 phonemes to amortise the ONNX forward pass on small
+ * windows. This file intentionally has no dependency on the rest of the
+ * voice scaffold so it can be reused by the fine-tune evaluator script.
+ */
+import type { KokoroPhonemizer } from "./types";
+export interface PhonemeStreamWindow {
+    /** Cumulative ids since stream start. The runtime can re-tokenise or
+     *  carry state by id; the simplest implementation forwards the full
+     *  window each call. */
+    ids: Int32Array;
+    /** Cumulative phoneme string for debugging / display. */
+    phonemes: string;
+    /** True for the final window in the stream. */
+    isFinal: boolean;
+}
+export interface StreamPhonemesOptions {
+    phonemizer: KokoroPhonemizer;
+    lang: string;
+    /** Emit a window every N new phoneme ids. Default 8 (≈ first audio after a
+     *  short syllable cluster — matches the phrase chunker's default cap). */
+    flushAt?: number;
+}
+/**
+ * Phonemize an async text source and emit cumulative windows. The caller
+ * consumes the iterator with `for await (const window of streamPhonemes(…))`.
+ * A pull-style API keeps this independent of the scheduler's event loop —
+ * the bench harness and the eval loop both reuse it without taking on a
+ * scheduler dependency.
+ */
+export declare function streamPhonemes(textChunks: AsyncIterable<string>, opts: StreamPhonemesOptions): AsyncIterable<PhonemeStreamWindow>;
+/** Synchronous variant for whole-phrase callers (the scheduler dispatches
+ *  one phrase at a time in the default `punctuation` mode). Returns the
+ *  full id array — equivalent to draining `streamPhonemes` on a single-item
+ *  iterator and taking the last window. */
+export declare function phonemizePhrase(text: string, opts: StreamPhonemesOptions): Promise<PhonemeStreamWindow>;
+//# sourceMappingURL=phoneme-stream.d.ts.map

package/dist/services/voice/kokoro/phoneme-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phoneme-stream.d.ts","sourceRoot":"","sources":["../../../../src/services/voice/kokoro/phoneme-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAyB,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEvE,MAAM,WAAW,mBAAmB;IACnC;;4BAEwB;IACxB,GAAG,EAAE,UAAU,CAAC;IAChB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACrC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb;8EAC0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAuB,cAAc,CACpC,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,EACjC,IAAI,EAAE,qBAAqB,GACzB,aAAa,CAAC,mBAAmB,CAAC,CAwCpC;AAqBD;;;2CAG2C;AAC3C,wBAAsB,eAAe,CACpC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,qBAAqB,GACzB,OAAO,CAAC,mBAAmB,CAAC,CAG9B"}

package/dist/services/voice/kokoro/phonemizer.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Text → phoneme-id adapter for Kokoro-82M.
+ *
+ * Kokoro is trained against espeak-ng IPA tokens with a small fixed vocab
+ * (~178 entries: IPA symbols + stress/punct markers + special <s>/<pad>).
+ * Production deployments should bring real espeak-ng phonemization
+ * (`phonemizer` is the pure-JS eSpeak NG package); the bundled fallback here is a
+ * deterministic letter-to-pseudo-phoneme adapter that produces audible
+ * speech for ASCII English text but loses prosodic accuracy.
+ *
+ * Resolution order:
+ *   1. Caller-provided `KokoroPhonemizer` (preferred — bring your own).
+ *   2. Dynamically-imported `phonemizer`/`phonemize` npm package, if installed.
+ *   3. Bundled `FallbackG2PPhonemizer` (degrades gracefully, never throws on
+ *      ASCII input).
+ *
+ * Non-ASCII text with no real phonemizer raises `KokoroPhonemizerError` —
+ * silent garbage out is worse than a surfaced error (AGENTS.md §3).
+ */
+import { type KokoroPhonemeSequence, type KokoroPhonemizer } from "./types";
+/**
+ * Deterministic ASCII-only G2P used when no real phonemizer is installed.
+ * Lossy by design — this exists so dev environments without espeak-ng still
+ * produce lexically useful smoke output for common English phrases, not to
+ * replace a production Misaki/espeak phonemizer.
+ */
+export declare class FallbackG2PPhonemizer implements KokoroPhonemizer {
+    readonly id = "fallback-g2p";
+    phonemize(text: string, _lang: string): Promise<KokoroPhonemeSequence>;
+}
+/**
+ * Wraps the npm `phonemizer` package when present. It returns an IPA string
+ * which we tokenise with the same VOCAB above. Real Kokoro inference should
+ * use a proper espeak tokenizer — production deployments bring their own;
+ * this is the "install npm and it works" middle ground.
+ */
+export declare class NpmPhonemizePhonemizer implements KokoroPhonemizer {
+    private readonly mod;
+    private readonly callStyle;
+    readonly id: string;
+    private constructor();
+    static tryLoad(): Promise<NpmPhonemizePhonemizer | null>;
+    phonemize(text: string, lang: string): Promise<KokoroPhonemeSequence>;
+}
+export declare function kokoroLangToPhonemizerLanguage(lang: string): string;
+/** Lazy resolver: caller override → npm `phonemizer` → bundled fallback. */
+export declare function resolvePhonemizer(override?: KokoroPhonemizer): Promise<KokoroPhonemizer>;
+/** Exported for tests and bench-time diagnostics. */
+export declare const KOKORO_PAD_ID: number;
+//# sourceMappingURL=phonemizer.d.ts.map

package/dist/services/voice/kokoro/phonemizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phonemizer.d.ts","sourceRoot":"","sources":["../../../../src/services/voice/kokoro/phonemizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACN,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EAErB,MAAM,SAAS,CAAC;AAuLjB;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,gBAAgB;IAC7D,QAAQ,CAAC,EAAE,kBAAkB;IAEvB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;CA2B5E;AAaD;;;;;GAKG;AACH,qBAAa,sBAAuB,YAAW,gBAAgB;IAG7D,OAAO,CAAC,QAAQ,CAAC,GAAG;IAEpB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO;WAQM,OAAO,IAAI,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAqBxD,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;CA0B3E;AAED,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASnE;AAED,4EAA4E;AAC5E,wBAAsB,iBAAiB,CACtC,QAAQ,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,gBAAgB,CAAC,CAK3B;AAED,qDAAqD;AACrD,eAAO,MAAM,aAAa,QAAM,CAAC"}

package/dist/services/voice/kokoro/pick-runtime.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Kokoro runtime selector — picks the resolved-runtime path.
+ *
+ * The env knob is `KOKORO_BACKEND`:
+ *
+ *   ffi   (default)  → KokoroFfiRuntime → in-process synthesis through the
+ *                       fused `libelizainference` handle (the
+ *                       `eliza_inference_kokoro_*` exports, introduced at ABI
+ *                       v10; the fused library is currently ABI v12). This is
+ *                       the SOLE synthesis path on every platform.
+ *   mock             → KokoroMockRuntime. Tests only.
+ *
+ * The legacy `fork` / `server` value (POST `/v1/audio/speech` on a running
+ * llama-server) was removed — Kokoro is folded into the fused lib, so there is
+ * one runtime, not a duplicate HTTP transport. The "onnx" value was removed
+ * earlier with `onnxruntime-node`.
+ */
+import { type KokoroFfiRuntimeOptions } from "./kokoro-ffi-runtime";
+import { type KokoroMockRuntimeOptions, type KokoroRuntime } from "./kokoro-runtime";
+export type KokoroBackendId = "ffi" | "mock";
+export interface KokoroBackendInputs {
+    /** Override the env-resolved backend (tests / programmatic selection). */
+    backend?: KokoroBackendId;
+    /** Default backend derived from the discovered model layout. Used when no
+     *  explicit backend and no `KOKORO_BACKEND` env override are set. When
+     *  omitted the selector defaults to the in-process `ffi` path. */
+    defaultBackend?: KokoroBackendId;
+    /** Construction options for the in-process FFI path. Used iff backend === "ffi". */
+    ffi?: KokoroFfiRuntimeOptions;
+    /** Construction options for the mock path. */
+    mock?: KokoroMockRuntimeOptions;
+    /** Override the process.env source. */
+    env?: NodeJS.ProcessEnv;
+}
+export interface KokoroBackendDecision {
+    backend: KokoroBackendId;
+    /** One-line reason — surfaced to telemetry. */
+    reason: string;
+    runtime: KokoroRuntime;
+}
+/**
+ * Resolve the `KOKORO_BACKEND` env variable. Throws on an unrecognized value
+ * — silent fallback would hide a misconfiguration (AGENTS.md §3 "no silent
+ * fallback"). The legacy `fork` / `server` (HTTP) value is rejected with a
+ * pointer to the in-process path.
+ */
+export declare function readKokoroBackendFromEnv(env?: NodeJS.ProcessEnv): KokoroBackendId | undefined;
+/**
+ * Pick the Kokoro runtime backend.
+ *
+ *   1. Explicit `inputs.backend` wins.
+ *   2. Else env (`KOKORO_BACKEND`).
+ *   3. Else `inputs.defaultBackend`.
+ *   4. Else default → `ffi` (in-process fused handle, the only mobile-safe path).
+ *
+ * If the chosen backend's options block is missing the call throws a
+ * structured error (no silent downgrade). Callers must wire the options
+ * for the backends they enable.
+ */
+export declare function pickKokoroRuntimeBackend(inputs: KokoroBackendInputs): KokoroBackendDecision;
+//# sourceMappingURL=pick-runtime.d.ts.map

package/dist/services/voice/kokoro/pick-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pick-runtime.d.ts","sourceRoot":"","sources":["../../../../src/services/voice/kokoro/pick-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAEN,KAAK,uBAAuB,EAC5B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEN,KAAK,wBAAwB,EAC7B,KAAK,aAAa,EAClB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,MAAM,CAAC;AAE7C,MAAM,WAAW,mBAAmB;IACnC,0EAA0E;IAC1E,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B;;sEAEkE;IAClE,cAAc,CAAC,EAAE,eAAe,CAAC;IACjC,oFAAoF;IACpF,GAAG,CAAC,EAAE,uBAAuB,CAAC;IAC9B,8CAA8C;IAC9C,IAAI,CAAC,EAAE,wBAAwB,CAAC;IAChC,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACrC,OAAO,EAAE,eAAe,CAAC;IACzB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,aAAa,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACvC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAClC,eAAe,GAAG,SAAS,CAc7B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACvC,MAAM,EAAE,mBAAmB,GACzB,qBAAqB,CAuCvB"}

package/dist/services/voice/kokoro/runtime-selection.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Voice backend selection — Kokoro is the only on-device TTS backend.
+ *
+ * OmniVoice TTS was retired (it was an autoregressive LM-based synth: heavier,
+ * slower TTFB, and only it could voice-clone). Kokoro (StyleTTS2 / iSTFTNet,
+ * non-autoregressive) is faster, smaller, and ships in every bundle — desktop
+ * and mobile alike — so the selector collapses to a single auditable answer.
+ * The function + env reader are kept (rather than inlined) so the engine layer
+ * and tests retain one seam to ask "is a TTS backend available?".
+ */
+export type VoiceBackendChoice = "kokoro";
+/** Retained for the env override; `auto` and `kokoro` both resolve to Kokoro. */
+export type VoiceBackendMode = "kokoro" | "auto";
+export interface VoiceBackendInputs {
+    /** Caller-set mode. Defaults to `auto`; both modes resolve to Kokoro. */
+    mode?: VoiceBackendMode;
+    /** Whether Kokoro model artifacts are present on disk. The selector throws
+     *  rather than returning a backend when this is `false` — no silent downgrade. */
+    kokoroAvailable: boolean;
+    /** True on mobile (iOS / Android) builds — informational only now. */
+    mobile?: boolean;
+}
+export interface VoiceBackendDecision {
+    backend: VoiceBackendChoice;
+    /** One-line reason — surfaced to telemetry. */
+    reason: string;
+}
+/** Resolve the env override (`ELIZA_TTS_BACKEND=kokoro|auto`). */
+export declare function readVoiceBackendModeFromEnv(env?: NodeJS.ProcessEnv): VoiceBackendMode | undefined;
+export declare function selectVoiceBackend(inputs: VoiceBackendInputs): VoiceBackendDecision;
+//# sourceMappingURL=runtime-selection.d.ts.map

package/dist/services/voice/kokoro/runtime-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-selection.d.ts","sourceRoot":"","sources":["../../../../src/services/voice/kokoro/runtime-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;AAE1C,iFAAiF;AACjF,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjD,MAAM,WAAW,kBAAkB;IAClC,yEAAyE;IACzE,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB;sFACkF;IAClF,eAAe,EAAE,OAAO,CAAC;IACzB,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;CACf;AAED,kEAAkE;AAClE,wBAAgB,2BAA2B,CAC1C,GAAG,GAAE,MAAM,CAAC,UAAwB,GAClC,gBAAgB,GAAG,SAAS,CAY9B;AAED,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,kBAAkB,GACxB,oBAAoB,CAYtB"}

package/dist/services/voice/kokoro/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Public types for the Kokoro-82M TTS backend (Apache-2.0, hexgrad/Kokoro-82M
+ * upstream).
+ *
+ * Kokoro is a small (~82M-param) StyleTTS-2 derivative that ships with a set
+ * of "voice packs" — pre-baked 256-dim style vectors (one .bin per voice).
+ * Adding voices is a cheap (~512KB) extra download.
+ */
+/** Canonical voice-pack id. Convention: `<lang>_<name>` (af_bella, am_michael). */
+export type KokoroVoiceId = string;
+/** One bundled voice pack — small fp32 style tensor on disk. */
+export interface KokoroVoicePack {
+    /** `af_bella`, `af_sarah`, `am_michael`, ... */
+    id: KokoroVoiceId;
+    /** Human-readable name shown in UI. */
+    displayName: string;
+    /** Two-letter language tag (`a` = American English, `b` = British English, etc. per Kokoro convention). */
+    lang: string;
+    /** Filename inside the voices/ directory, relative to the Kokoro model root. */
+    file: string;
+    /** Style-vector dim (256 for v1.0). */
+    dim: number;
+    /** Genre/voice tags for picker UIs. */
+    tags?: ReadonlyArray<string>;
+}
+/** Where the runtime expects to find Kokoro on disk. */
+export interface KokoroModelLayout {
+    /** Directory under `<stateDir>/local-inference/models/kokoro/`. */
+    root: string;
+    /** Model file — the Kokoro GGUF carried by our llama.cpp fork. */
+    modelFile: string;
+    /** Directory containing the per-voice style tensors. */
+    voicesDir: string;
+    /** Model output sample rate (Kokoro v1.0 = 24000). */
+    sampleRate: number;
+}
+/** Construction-time configuration for `KokoroTtsBackend`. */
+export interface KokoroBackendOptions {
+    /** Resolved on-disk layout. Required — the backend never guesses paths. */
+    layout: KokoroModelLayout;
+    /**
+     * Voice id to use when the caller's `SpeakerPreset.voiceId` is not in the
+     * voice-pack registry. The named voice MUST be present in `layout.voicesDir`.
+     */
+    defaultVoiceId: KokoroVoiceId;
+    /**
+     * Optional phonemizer override. Defaults to the bundled lazy phonemizer,
+     * which uses `phonemize` if installed and falls back to a deterministic
+     * grapheme-to-phoneme adapter otherwise (documented tradeoff in README).
+     */
+    phonemizer?: KokoroPhonemizer;
+    /**
+     * Max samples emitted in a single streaming chunk. Defaults to a quarter-
+     * second at 24kHz (6000) so the scheduler ring buffer sees a continuous
+     * trickle and TTFB stays close to the first inference completion.
+     */
+    streamingChunkSamples?: number;
+}
+/** A pure (or async-pure) text → phoneme-id sequence converter. */
+export interface KokoroPhonemizer {
+    /** Phonemize a single utterance into a sequence of integer ids. */
+    phonemize(text: string, lang: string): Promise<KokoroPhonemeSequence>;
+    /** Human-facing id (`"phonemize"`, `"espeak-ng"`, `"fallback-g2p"`, ...). */
+    readonly id: string;
+}
+export interface KokoroPhonemeSequence {
+    /** Token ids for the model's `input_ids` tensor. */
+    ids: Int32Array;
+    /** Original phoneme string, for debugging and tests. */
+    phonemes: string;
+}
+/** Raised when the on-disk model layout is missing or malformed. */
+export declare class KokoroModelMissingError extends Error {
+    readonly code: "kokoro-model-missing";
+    constructor(message: string);
+}
+/** Raised when phonemization cannot proceed (no phonemizer + non-ASCII text). */
+export declare class KokoroPhonemizerError extends Error {
+    readonly code: "kokoro-phonemizer-error";
+    constructor(message: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/voice/kokoro/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/services/voice/kokoro/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,mFAAmF;AACnF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AAEnC,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC/B,gDAAgD;IAChD,EAAE,EAAE,aAAa,CAAC;IAClB,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,2GAA2G;IAC3G,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IACjC,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,8DAA8D;AAC9D,MAAM,WAAW,oBAAoB;IACpC,2EAA2E;IAC3E,MAAM,EAAE,iBAAiB,CAAC;IAC1B;;;OAGG;IACH,cAAc,EAAE,aAAa,CAAC;IAC9B;;;;OAIG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAChC,mEAAmE;IACnE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACtE,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACrC,oDAAoD;IACpD,GAAG,EAAE,UAAU,CAAC;IAChB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,oEAAoE;AACpE,qBAAa,uBAAwB,SAAQ,KAAK;IACjD,QAAQ,CAAC,IAAI,EAAG,sBAAsB,CAAU;gBACpC,OAAO,EAAE,MAAM;CAI3B;AAED,iFAAiF;AACjF,qBAAa,qBAAsB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,IAAI,EAAG,yBAAyB,CAAU;gBACvC,OAAO,EAAE,MAAM;CAI3B"}

package/dist/services/voice/kokoro/voice-presets.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Registry of bundled Kokoro voice packs (upstream: hexgrad/Kokoro-82M).
+ *
+ * Each entry maps a stable `KokoroVoiceId` (the `voices/<id>.bin` filename
+ * Kokoro ships) onto display metadata. The runtime resolves a caller's
+ * `SpeakerPreset.voiceId` against this table; an unknown id falls through to
+ * the backend's `defaultVoiceId`.
+ *
+ * The actual style tensor (256 fp32 values) lives at
+ * `<modelRoot>/voices/<file>` and is loaded lazily on first use.
+ *
+ * Reference: https://huggingface.co/hexgrad/Kokoro-82M
+ */
+import type { KokoroVoicePack } from "./types";
+export declare const KOKORO_VOICE_PACKS: ReadonlyArray<KokoroVoicePack>;
+/** Look up a voice pack by id. Returns `undefined` for unknown ids — the
+ *  backend chooses how to fall back (typically `defaultVoiceId`). */
+export declare function findKokoroVoice(id: string): KokoroVoicePack | undefined;
+/** The voice the runtime selects when nothing is configured. */
+export declare const KOKORO_DEFAULT_VOICE_ID = "af_same";
+/** Conservative fallback voice when a configured/default preset is not staged. */
+export declare const KOKORO_FALLBACK_VOICE_ID = "af_bella";
+//# sourceMappingURL=voice-presets.d.ts.map

package/dist/services/voice/kokoro/voice-presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-presets.d.ts","sourceRoot":"","sources":["../../../../src/services/voice/kokoro/voice-presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC,eAAe,CAkG7D,CAAC;AAIF;qEACqE;AACrE,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEvE;AAED,gEAAgE;AAChE,eAAO,MAAM,uBAAuB,YAAY,CAAC;AAEjD,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,aAAa,CAAC"}

package/dist/services/voice/kokoro/voices.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Kokoro-82M voice catalog.
+ *
+ * Re-exports the bundled `KOKORO_VOICE_PACKS` table from `voice-presets.ts`
+ * under the canonical filename the integration spec calls out, and adds a few
+ * search helpers used by the runtime-selection layer and the picker UI.
+ *
+ * Each voice pack ships as a small (~256 fp32 values × 4 bytes ≈ 1 KB) style
+ * tensor under `<modelRoot>/voices/<file>`. Adding voices is cheap (download
+ * a single .bin), and a hot ONNX session can swap voices per-utterance with
+ * no re-init cost — the model is the same.
+ *
+ * Upstream registry: https://huggingface.co/hexgrad/Kokoro-82M/tree/main/voices
+ */
+import type { KokoroVoiceId, KokoroVoicePack } from "./types";
+export { findKokoroVoice, KOKORO_DEFAULT_VOICE_ID, KOKORO_VOICE_PACKS, } from "./voice-presets";
+/** All voice ids that ship with the upstream Kokoro v1.0 release. */
+export declare function listKokoroVoiceIds(): ReadonlyArray<KokoroVoiceId>;
+/** Filter voice packs by language tag (`a` US, `b` UK, etc.). */
+export declare function listKokoroVoicesByLang(lang: string): ReadonlyArray<KokoroVoicePack>;
+/** Filter by an exact tag (`female`, `male`, `british`, `breathy`, ...). */
+export declare function listKokoroVoicesByTag(tag: string): ReadonlyArray<KokoroVoicePack>;
+/**
+ * Resolve a caller-supplied voice id against the registry. Returns the
+ * matching pack, or the default pack when the id is not bundled. Never
+ * throws — runtime selection treats this as a graceful fallback because the
+ * caller's `SpeakerPreset.voiceId` may have been authored for OmniVoice.
+ */
+export declare function resolveKokoroVoiceOrDefault(id: string): KokoroVoicePack;
+//# sourceMappingURL=voices.d.ts.map

package/dist/services/voice/kokoro/voices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voices.d.ts","sourceRoot":"","sources":["../../../../src/services/voice/kokoro/voices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAO9D,OAAO,EACN,eAAe,EACf,uBAAuB,EACvB,kBAAkB,GAClB,MAAM,iBAAiB,CAAC;AAEzB,qEAAqE;AACrE,wBAAgB,kBAAkB,IAAI,aAAa,CAAC,aAAa,CAAC,CAEjE;AAED,iEAAiE;AACjE,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,MAAM,GACV,aAAa,CAAC,eAAe,CAAC,CAEhC;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CACpC,GAAG,EAAE,MAAM,GACT,aAAa,CAAC,eAAe,CAAC,CAEhC;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,CAUvE"}