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

package/dist/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/dist/services/voice/wake-word.d.ts.map

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

package/dist/services/voice/wav-codec.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Mono PCM16 WAV codec — dependency-light so corpus / fixture / test code can
+ * encode + decode WAV without dragging in the heavy `engine-bridge` module
+ * graph. `engine-bridge` re-exports these for its existing callers.
+ */
+import type { TranscriptionAudio } from "./types";
+/** Encode mono float PCM as a 16-bit little-endian WAV byte stream. */
+export declare function encodeMonoPcm16Wav(pcm: Float32Array, sampleRate: number): Uint8Array;
+/** Decode a mono PCM16 WAV byte stream into float PCM + sample rate. */
+export declare function decodeMonoPcm16Wav(bytes: Uint8Array): TranscriptionAudio;
+//# sourceMappingURL=wav-codec.d.ts.map

package/dist/services/voice/wav-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wav-codec.d.ts","sourceRoot":"","sources":["../../../src/services/voice/wav-codec.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAgBlD,uEAAuE;AACvE,wBAAgB,kBAAkB,CACjC,GAAG,EAAE,YAAY,EACjB,UAAU,EAAE,MAAM,GAChB,UAAU,CA4BZ;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,kBAAkB,CA2CxE"}

package/dist/services/voice/workbench-entrypoint.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Voice Workbench entrypoint (#8785).
+ *
+ * One call that generates the corpus for a scenario matrix, runs them headless
+ * through the (injected) voice services, and rolls the result into the single
+ * JSON + Markdown benchmark report. The CLI (`voice:workbench`) and the CI lane
+ * are thin shells over this:
+ *   - mocked lane (always): pass `groundTruthMockServices()` → runs + passes,
+ *     exercising corpus → runner → scorers → report end-to-end with no model;
+ *   - real lane (where provisioned): pass a real services adapter; absent
+ *     backend → `services: null` → every scenario `skipped` (never `pass`).
+ *
+ * Pure orchestration over the already-tested pieces, so it is unit-testable
+ * without a model or a browser.
+ */
+import { type CorpusTtsSynthesizer } from "./corpus-generator";
+import type { VoiceScenario } from "./voice-scenario";
+import { type VoiceWorkbenchReport } from "./voice-workbench-report";
+import { type VoiceWorkbenchServices } from "./workbench-headless-runner";
+export interface BuildAndRunVoiceWorkbenchArgs {
+    /** Scenario matrix to run (defaults to the built-in set). */
+    scenarios?: ReadonlyArray<VoiceScenario>;
+    /** Voice services; null → every scenario is skipped (no backend). */
+    services: VoiceWorkbenchServices | null;
+    /** Corpus sample rate (default 16 kHz). */
+    sampleRate?: number;
+    /** Real TTS for the corpus; omitted → deterministic synthetic speech. */
+    synthesizer?: CorpusTtsSynthesizer;
+}
+export interface VoiceWorkbenchResult {
+    report: VoiceWorkbenchReport;
+    markdown: string;
+}
+/** Generate corpus → run headless → build the report + Markdown. */
+export declare function buildAndRunVoiceWorkbench(args: BuildAndRunVoiceWorkbenchArgs): Promise<VoiceWorkbenchResult>;
+export interface VoiceWorkbenchArtifacts {
+    reportJsonPath: string;
+    reportMarkdownPath: string;
+}
+/** Persist the workbench result as `report.json` + `report.md` under `outDir`. */
+export declare function writeVoiceWorkbenchResult(result: VoiceWorkbenchResult, outDir: string): VoiceWorkbenchArtifacts;
+//# sourceMappingURL=workbench-entrypoint.d.ts.map

package/dist/services/voice/workbench-entrypoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbench-entrypoint.d.ts","sourceRoot":"","sources":["../../../src/services/voice/workbench-entrypoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EACN,KAAK,oBAAoB,EAEzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAGN,KAAK,oBAAoB,EACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEN,KAAK,sBAAsB,EAC3B,MAAM,6BAA6B,CAAC;AAGrC,MAAM,WAAW,6BAA6B;IAC7C,6DAA6D;IAC7D,SAAS,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;IACzC,qEAAqE;IACrE,QAAQ,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACxC,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,WAAW,CAAC,EAAE,oBAAoB,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACpC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,oEAAoE;AACpE,wBAAsB,yBAAyB,CAC9C,IAAI,EAAE,6BAA6B,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAgB/B;AAED,MAAM,WAAW,uBAAuB;IACvC,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;CAC3B;AAED,kFAAkF;AAClF,wBAAgB,yBAAyB,CACxC,MAAM,EAAE,oBAAoB,EAC5B,MAAM,EAAE,MAAM,GACZ,uBAAuB,CAOzB"}

package/dist/services/voice/workbench-headless-runner.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Voice Workbench headless runner (#8785).
+ *
+ * Drives a {@link VoiceScenario} + its generated corpus through the real voice
+ * services WITHOUT a browser, scores every turn with the shared scorers
+ * (`e2e-harness.ts`), and emits one {@link VoiceWorkbenchScenarioRun} the report
+ * layer (`voice-workbench-report.ts`) aggregates. The services are injected
+ * through {@link VoiceWorkbenchServices} so:
+ *   - a provisioned local backend wires the real ASR / diarization / EOT /
+ *     respond / entity / TTS path,
+ *   - a mock returns ground-truth-derived observations for the CI plumbing lane,
+ *   - and an ABSENT backend (`services === null`) or absent corpus
+ *     (`corpus === null`) yields a `skipped` run — never a `pass` (honesty
+ *     contract).
+ *
+ * Pure orchestration: it slices the corpus per turn, asks the services to
+ * observe the turn, and maps observations onto scorer inputs. No model loading
+ * here, so it is unit-testable with a fake services adapter.
+ */
+import type { CorpusGroundTruth, CorpusTurnLabel, GeneratedVoiceCorpus } from "./corpus-generator";
+import type { VoiceScenario } from "./voice-scenario";
+import type { VoiceWorkbenchScenarioRun } from "./voice-workbench-report";
+/** What the real (or mock) services observed for one turn of audio. */
+export interface VoiceTurnObservation {
+    /** ASR hypothesis transcript for the turn's audio. */
+    hypothesisTranscript: string;
+    /** Diarized speaker label, or null when the diarizer missed the turn. */
+    predictedSpeakerLabel: string | null;
+    /** The EOT classifier decided end-of-turn at this turn's boundary. */
+    eotDecided: boolean;
+    /** EOT decision latency (ms) from the true boundary, when measured. */
+    eotLatencyMs?: number;
+    /** The agent decided to respond to this turn. */
+    responded: boolean;
+    /** Entities inferred from this turn's transcript (name/partner extraction). */
+    inferredEntities: string[];
+    /** Voice→entity match: the entity the recognized voice resolved to (or null). */
+    matchedEntityId: string | null;
+    /** First-audio latency (ms) of the agent's spoken reply, when it replied. */
+    firstAudioMs?: number;
+    /** The system judged this turn to be the device owner (owner-security). */
+    predictedOwner?: boolean;
+}
+export interface VoiceWorkbenchServices {
+    /**
+     * Optional one-shot hook before a scenario's turns are scored. Real services
+     * use this to enroll speaker centroids from the generated corpus; mock
+     * services can omit it.
+     */
+    prepareScenario?(args: {
+        scenario: VoiceScenario;
+        corpus: GeneratedVoiceCorpus;
+    }): Promise<void> | void;
+    /**
+     * Feed one turn's audio slice through the real services and report what was
+     * observed. The `label` carries the turn's ground truth (so a mock can echo
+     * it); the real adapter ignores it and measures.
+     */
+    observeTurn(args: {
+        turnIndex: number;
+        audio: Float32Array;
+        sampleRate: number;
+        label: CorpusTurnLabel;
+        /** Scenario-level ground truth (participants, owner set, agents). */
+        groundTruth: CorpusGroundTruth;
+    }): Promise<VoiceTurnObservation>;
+}
+/**
+ * Where to write per-run `.wav` artifacts. When present, the runner encodes the
+ * full corpus + each consumed per-turn slice to disk under `dir` and records the
+ * paths (relative to `relativeTo`) on the run's `audioArtifacts`. Absent ⇒ no IO.
+ */
+export interface VoiceAudioCaptureSink {
+    /** Directory the `.wav` files are written into (created recursively). */
+    dir: string;
+    /** Artifact paths are recorded relative to this dir (the scenario run dir). */
+    relativeTo: string;
+}
+export interface RunVoiceScenarioHeadlessArgs {
+    scenario: VoiceScenario;
+    /** The generated/loaded corpus; null when its artifacts are absent. */
+    corpus: GeneratedVoiceCorpus | null;
+    /** The voice services; null when no backend is provisioned. */
+    services: VoiceWorkbenchServices | null;
+    /** When set, write the run's audio as `.wav` artifacts and record their paths. */
+    captureAudio?: VoiceAudioCaptureSink;
+}
+/**
+ * Run one scenario headless and score it. Returns a `skipped` run (never a
+ * pass) when the corpus or the backend is absent.
+ */
+export declare function runVoiceScenarioHeadless(args: RunVoiceScenarioHeadlessArgs): Promise<VoiceWorkbenchScenarioRun>;
+export interface RunVoiceWorkbenchArgs {
+    scenarios: ReadonlyArray<{
+        scenario: VoiceScenario;
+        corpus: GeneratedVoiceCorpus | null;
+    }>;
+    services: VoiceWorkbenchServices | null;
+}
+/** Run a matrix of scenarios headless, returning one run per scenario. */
+export declare function runVoiceWorkbenchHeadless(args: RunVoiceWorkbenchArgs): Promise<VoiceWorkbenchScenarioRun[]>;
+//# sourceMappingURL=workbench-headless-runner.d.ts.map

package/dist/services/voice/workbench-headless-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbench-headless-runner.d.ts","sourceRoot":"","sources":["../../../src/services/voice/workbench-headless-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EACX,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAc5B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAEX,yBAAyB,EACzB,MAAM,0BAA0B,CAAC;AAGlC,uEAAuE;AACvE,MAAM,WAAW,oBAAoB;IACpC,sDAAsD;IACtD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,sEAAsE;IACtE,UAAU,EAAE,OAAO,CAAC;IACpB,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,SAAS,EAAE,OAAO,CAAC;IACnB,+EAA+E;IAC/E,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,iFAAiF;IACjF,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACtC;;;;OAIG;IACH,eAAe,CAAC,CAAC,IAAI,EAAE;QACtB,QAAQ,EAAE,aAAa,CAAC;QACxB,MAAM,EAAE,oBAAoB,CAAC;KAC7B,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,WAAW,CAAC,IAAI,EAAE;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,YAAY,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,eAAe,CAAC;QACvB,qEAAqE;QACrE,WAAW,EAAE,iBAAiB,CAAC;KAC/B,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACrC,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;IACZ,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,4BAA4B;IAC5C,QAAQ,EAAE,aAAa,CAAC;IACxB,uEAAuE;IACvE,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACpC,+DAA+D;IAC/D,QAAQ,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACxC,kFAAkF;IAClF,YAAY,CAAC,EAAE,qBAAqB,CAAC;CACrC;AA2CD;;;GAGG;AACH,wBAAsB,wBAAwB,CAC7C,IAAI,EAAE,4BAA4B,GAChC,OAAO,CAAC,yBAAyB,CAAC,CA+MpC;AAED,MAAM,WAAW,qBAAqB;IACrC,SAAS,EAAE,aAAa,CAAC;QACxB,QAAQ,EAAE,aAAa,CAAC;QACxB,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC;KACpC,CAAC,CAAC;IACH,QAAQ,EAAE,sBAAsB,GAAG,IAAI,CAAC;CACxC;AAED,0EAA0E;AAC1E,wBAAsB,yBAAyB,CAC9C,IAAI,EAAE,qBAAqB,GACzB,OAAO,CAAC,yBAAyB,EAAE,CAAC,CAYtC"}

package/dist/services/voice/workbench-logic-services.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Voice Workbench real-decision-logic services adapter (#8785, #9427).
+ *
+ * The ground-truth mock (`groundTruthMockServices`) echoes the corpus labels —
+ * it proves the runner → scorers → report wiring, but it can never catch a
+ * regression in the DECISION logic because it never runs it. This adapter does:
+ * for every turn it runs the REAL, shipped modules —
+ *
+ *   - end-of-turn:        `scoreEndOfTurnHeuristic` (`@elizaos/shared/voice-eot`)
+ *   - respond / echo /    `buildVoiceTurnSignal` (`@elizaos/shared/voice/respond-gate`)
+ *     bystander / wake-word   — the SAME gate the UI client ships
+ *   - diarization:        `OnlineSpeakerClusterer` clusters each turn BY ITS
+ *                         AUDIO (blind to the ground-truth label), so the DER
+ *                         gate measures a real attribution and can actually fail
+ *                         on a misattribution (#9427).
+ *   - acoustic self-voice: `selfVoiceSimilarity` measures the turn audio against
+ *                         the agent's TTS imprint — the real value the echo gate
+ *                         consumes (no more hardcoded `0.9`).
+ *   - name extraction:    the inline patterns below (mirrors IDENTIFY_SPEAKER)
+ *
+ * — so the workbench catches a regression in the gate the moment it lands. It is
+ * CI-runnable with NO models or network: it keeps only the perfect-ASR
+ * assumption (the transcript comes from ground truth), so it does NOT measure
+ * ASR WER or EOT latency — those need the real model lane. Everything else is
+ * genuine: EOT decisions, respond/echo/bystander/wake-word, blind speaker
+ * clustering, acoustic self-voice, and name extraction.
+ */
+import type { VoiceWorkbenchServices } from "./workbench-headless-runner";
+/**
+ * Build a services adapter that runs the real decision logic. Stateful across a
+ * scenario's turns (it remembers the agent's last reply so a following
+ * `isAgentEcho` turn is gated against a genuine reply string); state resets at
+ * each scenario's first turn.
+ */
+export declare function realDecisionLogicServices(): VoiceWorkbenchServices;
+//# sourceMappingURL=workbench-logic-services.d.ts.map

package/dist/services/voice/workbench-logic-services.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbench-logic-services.d.ts","sourceRoot":"","sources":["../../../src/services/voice/workbench-logic-services.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAaH,OAAO,KAAK,EAEX,sBAAsB,EACtB,MAAM,6BAA6B,CAAC;AAmCrC;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,sBAAsB,CAoGlE"}

package/dist/services/voice/workbench-real-services.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Voice Workbench real services adapter (#9147).
+ *
+ * `voice:workbench --real` must not be an all-skipped honesty stub: the
+ * provisioned lane has a fused libelizainference build, ASR/TTS regions,
+ * WeSpeaker, pyannote, and ElevenLabs-generated human speech. This adapter
+ * drives those real pieces through the existing workbench runner/scorers.
+ */
+import type { CorpusTtsSynthesizer } from "./corpus-generator";
+import type { VoiceWorkbenchServices } from "./workbench-headless-runner";
+export interface RealVoiceWorkbenchRuntime {
+    services: VoiceWorkbenchServices;
+    synthesizer: CorpusTtsSynthesizer;
+    dispose(): Promise<void>;
+}
+export declare function createRealVoiceWorkbenchRuntimeFromEnv(env?: NodeJS.ProcessEnv): Promise<RealVoiceWorkbenchRuntime>;
+//# sourceMappingURL=workbench-real-services.d.ts.map

package/dist/services/voice/workbench-real-services.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbench-real-services.d.ts","sourceRoot":"","sources":["../../../src/services/voice/workbench-real-services.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,OAAO,KAAK,EAEX,oBAAoB,EAEpB,MAAM,oBAAoB,CAAC;AAS5B,OAAO,KAAK,EAEX,sBAAsB,EACtB,MAAM,6BAA6B,CAAC;AAiDrC,MAAM,WAAW,yBAAyB;IACzC,QAAQ,EAAE,sBAAsB,CAAC;IACjC,WAAW,EAAE,oBAAoB,CAAC;IAClC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAweD,wBAAsB,sCAAsC,CAC3D,GAAG,GAAE,MAAM,CAAC,UAAwB,GAClC,OAAO,CAAC,yBAAyB,CAAC,CAkDpC"}

package/dist/services/voice/workbench-scenarios.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Built-in Voice Workbench scenarios + a ground-truth mock services adapter
+ * (#8785).
+ *
+ * The scenario set spans every {@link VoiceScenarioClass} so the headless runner
+ * and the headful spec matrix exercise the whole surface from one source. The
+ * mock adapter echoes each turn's ground truth, so the CI plumbing lane runs the
+ * runner → scorers → report end-to-end and PASSES without any model — separate
+ * from the gated real-backend lane.
+ */
+import type { VoiceScenario } from "./voice-scenario";
+import type { VoiceWorkbenchServices } from "./workbench-headless-runner";
+export declare const VOICE_WORKBENCH_SCENARIOS: VoiceScenario[];
+/**
+ * A services adapter that echoes each turn's ground truth — perfect ASR /
+ * diarization / EOT / respond / entity / match. Drives the CI plumbing lane
+ * (runner → scorers → report) to a real PASS with no model. NOT a stand-in for
+ * the real backend: it proves the wiring, not the models.
+ */
+export declare function groundTruthMockServices(opts?: {
+    firstAudioMs?: number;
+    eotLatencyMs?: number;
+}): VoiceWorkbenchServices;
+//# sourceMappingURL=workbench-scenarios.d.ts.map

package/dist/services/voice/workbench-scenarios.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbench-scenarios.d.ts","sourceRoot":"","sources":["../../../src/services/voice/workbench-scenarios.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAEX,sBAAsB,EACtB,MAAM,6BAA6B,CAAC;AAErC,eAAO,MAAM,yBAAyB,EAAE,aAAa,EAmWpD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACtC,IAAI,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GACzD,sBAAsB,CAuBxB"}

package/dist/services/voice/wrap-with-first-line-cache.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Wrap a TTS model handler (`ModelType.TEXT_TO_SPEECH`) with the
+ * `FirstLineCache` disk-tier.
+ *
+ * Behaviour on a wrapped handler call:
+ *   1. Snip the first sentence of the input text. Reject if > 10 words or
+ *      no terminator found → defer to the inner handler unchanged.
+ *   2. Build the cache key from the snip + caller-supplied
+ *      `(provider, voiceId, voiceRevision, codec, voiceSettingsFingerprint)`.
+ *   3. On hit: if the snip is the WHOLE input, return cached bytes. If the
+ *      snip is only a prefix, return `cachedBytes ++ synthesize(remainder)`.
+ *      The concat path is safe for the codecs we cache today (mp3, opus,
+ *      ogg are self-framed; wav/pcm_f32 are not, and the wrapper falls
+ *      through for those).
+ *   4. On miss: call the inner handler with the full input, return that.
+ *      In the background, call the inner handler with JUST the snip to get
+ *      a cleanly-framed cache entry (no mid-stream-byte alignment hazards).
+ *
+ * The wrapper is provider-agnostic — `WrapOptions.resolveContext` is the
+ * single seam where each TTS plugin teaches the cache its provider name +
+ * voice id + revision + voice-settings fingerprint.
+ */
+import type { IAgentRuntime } from "@elizaos/core";
+import { type FirstLineCache, type FirstLineCacheKey } from "./first-line-cache";
+export type TtsBytes = Uint8Array | ArrayBuffer | Buffer;
+export type TtsHandlerInput = string | {
+    text: string;
+    [k: string]: unknown;
+};
+export type TtsHandlerOutput = TtsBytes;
+export type TtsHandler = (runtime: IAgentRuntime, input: TtsHandlerInput) => Promise<TtsHandlerOutput>;
+/** Caller-supplied context resolver — provider name + voice metadata. */
+export interface TtsResolvedContext {
+    provider: string;
+    voiceId: string;
+    voiceRevision: string;
+    codec: FirstLineCacheKey["codec"];
+    contentType: string;
+    sampleRate: number;
+    voiceSettingsFingerprint: string;
+    /** Optional: if true, bypass the cache entirely on this call. */
+    bypass?: boolean;
+}
+export interface WrapOptions {
+    /** Inject for tests. */
+    cache?: FirstLineCache;
+    /**
+     * Resolve the per-call provider/voice context. Must be cheap (typically
+     * a settings read + a small sha256). Return `null` to bypass the cache.
+     */
+    resolveContext: (runtime: IAgentRuntime, input: TtsHandlerInput) => Promise<TtsResolvedContext | null> | TtsResolvedContext | null;
+    /**
+     * Whether to attempt to concatenate cached bytes + remainder synthesis.
+     * Defaults to true for mp3/opus/ogg, false for wav/pcm_f32 (concat would
+     * corrupt the RIFF / raw stream).
+     */
+    concatRemainder?: boolean;
+    /** Optional pre-resolved fingerprint of voiceSettings; rarely needed. */
+    enableCachePopulation?: boolean;
+}
+/**
+ * Wrap a TTS handler with first-sentence caching. Returns a new handler with
+ * the same signature.
+ *
+ * The wrapper is safe to apply at runtime registration time — if the cache
+ * is disabled (env / no sqlite), the wrapper short-circuits to the inner
+ * handler with zero overhead beyond a snip attempt.
+ */
+export declare function wrapWithFirstLineCache(inner: TtsHandler, options: WrapOptions): TtsHandler;
+//# sourceMappingURL=wrap-with-first-line-cache.d.ts.map

package/dist/services/voice/wrap-with-first-line-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-with-first-line-cache.d.ts","sourceRoot":"","sources":["../../../src/services/voice/wrap-with-first-line-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAOnD,OAAO,EACN,KAAK,cAAc,EAEnB,KAAK,iBAAiB,EAGtB,MAAM,oBAAoB,CAAC;AAM5B,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,MAAM,CAAC;AACzD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAC9E,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;AACxC,MAAM,MAAM,UAAU,GAAG,CACxB,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,eAAe,KAClB,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE/B,yEAAyE;AACzE,MAAM,WAAW,kBAAkB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,wBAAwB,EAAE,MAAM,CAAC;IACjC,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC3B,wBAAwB;IACxB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB;;;OAGG;IACH,cAAc,EAAE,CACf,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,eAAe,KAClB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,GAAG,kBAAkB,GAAG,IAAI,CAAC;IACpE;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,yEAAyE;IACzE,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAChC;AA2CD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACrC,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,WAAW,GAClB,UAAU,CAgEZ"}