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

package/{src → dist}/services/voice/audio-frame-consumer.d.ts

@@ -31,6 +31,7 @@
  */
 import { type EmitVoiceTurnObservedArgs, type HandleLiveVoiceAttributionOptions } from "../../runtime/voice-entity-binding.js";
 import type { VoiceTurnSignal } from "./eot-classifier.js";
+import { type ResidualSuppressionOptions } from "./nlms-echo-canceller.js";
 import type { VoiceAttributionOutput, VoiceAttributionPipeline } from "./speaker/attribution-pipeline.js";
 import type { PcmFrame, VadEvent, VoiceInputSource } from "./types.js";
 /**
@@ -98,7 +99,27 @@ export interface AttributionPipelineLike {
  */
 export interface RuntimeEventSink {
     emitEvent(type: unknown, payload: Record<string, unknown>): Promise<void>;
+    /**
+     * Optional host-supplied far-end (agent TTS playback) reference for the live
+     * AEC path (#9583). When a host wires this, the live diarization route threads
+     * it into the session's NLMS echo canceller instead of relying on the
+     * playback-frames ingest route. Absent on headless/core runtimes.
+     */
+    voiceEchoReferenceProvider?: EchoReferenceProvider;
 }
+/**
+ * Transcribe a finalized turn's buffered PCM to text (#8786). When injected, the
+ * consumer joins the ASR transcript into the diarization attribution so
+ * `VOICE_TURN_OBSERVED` carries the real text — previously the live audio-frame
+ * path attributed *who* spoke but always emitted `text: ""`, so name/partner
+ * extraction (`VoiceObserver.ingestTurn`) could never fire from live audio.
+ *
+ * Returns the transcript, or `null`/empty for silence / no decode. Best-effort:
+ * the consumer swallows a rejection (counted in `transcriptionErrors`) and falls
+ * back to a transcript-less turn rather than dropping the diarized turn.
+ */
+export type TurnTranscriber = (pcm: Float32Array, sampleRate: number) => Promise<string | null> | string | null;
+export type SelfVoiceSimilarityResolver = (embedding: Float32Array, output: VoiceAttributionOutput) => Promise<number | null | undefined> | number | null | undefined;
 export interface AudioFrameConsumerDeps {
     /** Turn-segmentation VAD (drives speech-start/pause/end). */
     vad: VadSegmenter;
@@ -106,7 +127,34 @@ export interface AudioFrameConsumerDeps {
     pipeline: AttributionPipelineLike;
     /** Runtime event sink for VOICE_TURN_OBSERVED. */
     runtime: RuntimeEventSink;
+    /**
+     * Optional ASR for the finalized turn's PCM (#8786). When present, its text
+     * rides on `VOICE_TURN_OBSERVED` so live name/entity extraction runs. When
+     * absent the path stays diarization-only (transcript `""`, as before).
+     */
+    transcribe?: TurnTranscriber;
+    /**
+     * Optional live acoustic self-voice resolver. When wired, the consumer passes
+     * the turn's WeSpeaker embedding to the host's agent-TTS centroid matcher and
+     * forwards the resulting cosine into the ambient gate.
+     */
+    resolveSelfVoiceSimilarity?: SelfVoiceSimilarityResolver;
+    /**
+     * Optional agent-playback (far-end) reference for acoustic echo cancellation
+     * (#9455). Given a mic frame's clock timestamp and sample count, returns the
+     * agent's TTS playback PCM for that exact window (Float32 16 kHz), or null
+     * when the agent is not playing. When wired, the consumer runs an NLMS echo
+     * canceller on every mic frame BEFORE VAD/attribution so the agent never
+     * transcribes its own TTS. Absent → no AEC (unchanged behavior). The caller
+     * owns the playback capture + the playback→mic delay calibration.
+     */
+    echoReference?: EchoReferenceProvider;
 }
+/**
+ * Returns the agent's TTS playback PCM (the far-end echo reference) aligned to a
+ * mic frame's time window, or null when the agent is silent. See #9455.
+ */
+export type EchoReferenceProvider = (timestampMs: number, samples: number) => Float32Array | null;
 export interface AudioFrameConsumerConfig {
     /** Source metadata stamped onto every attributed turn. */
     source?: VoiceInputSource;
@@ -124,6 +172,12 @@ export interface AudioFrameConsumerConfig {
      * out of the attribution buffer. Default 0.3 s.
      */
     preRollSeconds?: number;
+    /**
+     * Opt-in nonlinear residual-echo suppressor forwarded to the NLMS canceller
+     * (#9583/#9649). Default-off; only meaningful when an `echoReference` is wired
+     * (no canceller exists otherwise). See {@link NlmsEchoCancellerOptions.residualSuppression}.
+     */
+    residualSuppression?: boolean | ResidualSuppressionOptions;
 }
 /** A finalized, attributed turn the consumer surfaces to its caller. */
 export interface AttributedTurn {
@@ -150,6 +204,11 @@ export declare class AudioFrameConsumer {
     private readonly vad;
     private readonly pipeline;
     private readonly runtime;
+    private readonly transcribe;
+    private readonly resolveSelfVoiceSimilarity;
+    private readonly echoReference;
+    /** NLMS echo canceller, instantiated only when an `echoReference` is wired. */
+    private readonly echoCanceller;
     private readonly source;
     private readonly attributionOptions;
     private readonly maxTurnSamples;
@@ -171,6 +230,13 @@ export declare class AudioFrameConsumer {
     private closed;
     /** Count of frames that failed to decode (surfaced via getters, not thrown). */
     droppedFrames: number;
+    /** Count of turns whose ASR transcribe threw (degraded to a transcript-less
+     *  turn rather than dropping the diarized turn). */
+    transcriptionErrors: number;
+    /** Count of mic frames the echo canceller actually processed (i.e. the agent
+     *  was playing). Frames skipped while the agent is silent do not count, so
+     *  this also measures how often AEC took the cheap passthrough path. */
+    echoFramesCancelled: number;
     constructor(deps: AudioFrameConsumerDeps, config?: AudioFrameConsumerConfig);
     /** True while a turn is being buffered (between speech-start and speech-end). */
     get inTurn(): boolean;
@@ -189,6 +255,15 @@ export declare class AudioFrameConsumer {
      * upstream and by the host harness.
      */
     pushDecodedFrame(pcm: Float32Array, timestampMs: number): Promise<void>;
+    /**
+     * Run the echo canceller on one mic frame when (and only when) the agent is
+     * playing. The reference provider returns null while the agent is silent, in
+     * which case the mic frame is passed through verbatim and the FIR
+     * `process()` loop is not invoked. The canceller still observes the silent
+     * far-end so stale playback history is cleared before playback resumes.
+     * Returns the echo-cancelled (or untouched) mic frame.
+     */
+    private cancelEcho;
     /**
      * Flush the VAD (finalize any open segment) and await all pending
      * attribution. Call at end-of-capture so a trailing utterance is not lost.
@@ -200,6 +275,13 @@ export declare class AudioFrameConsumer {
     private beginTurn;
     private finalizeTurn;
     private attributeTurn;
+    /**
+     * Merge the per-turn ASR transcript into the attribution options. Returns the
+     * base options unchanged when no transcriber is wired or the decode yields no
+     * text; a thrown decode is swallowed (counted in `transcriptionErrors`) so a
+     * diarized turn is never dropped over an ASR failure.
+     */
+    private resolveTurnOptions;
     private appendTurnChunk;
     private appendPreRoll;
 }

package/dist/services/voice/audio-frame-consumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-frame-consumer.d.ts","sourceRoot":"","sources":["../../../src/services/voice/audio-frame-consumer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EACN,KAAK,yBAAyB,EAC9B,KAAK,iCAAiC,EAEtC,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAEN,KAAK,0BAA0B,EAC/B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EACX,sBAAsB,EACtB,wBAAwB,EACxB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAMvE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,6EAA6E;AAC7E,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD,qBAAa,qBAAsB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI3B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,YAAY,CA0BxE;AA8BD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,8EAA8E;IAC9E,UAAU,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5D,mEAAmE;IACnE,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,4DAA4D;IAC5D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,0CAA0C;IAC1C,KAAK,IAAI,IAAI,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,SAAS,CACR,GAAG,EAAE,UAAU,CAAC,wBAAwB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,GACvD,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAChC,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E;;;;;OAKG;IACH,0BAA0B,CAAC,EAAE,qBAAqB,CAAC;CACnD;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GAAG,CAC7B,GAAG,EAAE,YAAY,EACjB,UAAU,EAAE,MAAM,KACd,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;AAE5C,MAAM,MAAM,2BAA2B,GAAG,CACzC,SAAS,EAAE,YAAY,EACvB,MAAM,EAAE,sBAAsB,KAC1B,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAMpE,MAAM,WAAW,sBAAsB;IACtC,6DAA6D;IAC7D,GAAG,EAAE,YAAY,CAAC;IAClB,kDAAkD;IAClD,QAAQ,EAAE,uBAAuB,CAAC;IAClC,kDAAkD;IAClD,OAAO,EAAE,gBAAgB,CAAC;IAC1B;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B;;;;OAIG;IACH,0BAA0B,CAAC,EAAE,2BAA2B,CAAC;IACzD;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,qBAAqB,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,KACX,YAAY,GAAG,IAAI,CAAC;AAEzB,MAAM,WAAW,wBAAwB;IACxC,0DAA0D;IAC1D,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,yEAAyE;IACzE,kBAAkB,CAAC,EAAE,iCAAiC,CAAC;IACvD;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,GAAG,0BAA0B,CAAC;CAC3D;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,sBAAsB,CAAC;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,sBAAsB,GAAG,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAC;AAEpE;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAqC;IAChF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+B;IAC7D,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2B;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAoC;IACvE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAa;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqC;IAEnE,0DAA0D;IAC1D,OAAO,CAAC,UAAU,CAAsB;IACxC,OAAO,CAAC,WAAW,CAAK;IACxB,mEAAmE;IACnE,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,cAAc,CAAK;IAC3B,8EAA8E;IAC9E,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,MAAM,CAAS;IAEvB,gFAAgF;IAChF,aAAa,SAAK;IAElB;wDACoD;IACpD,mBAAmB,SAAK;IAExB;;4EAEwE;IACxE,mBAAmB,SAAK;gBAGvB,IAAI,EAAE,sBAAsB,EAC5B,MAAM,GAAE,wBAA6B;IA+BtC,iFAAiF;IACjF,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,0EAA0E;IAC1E,MAAM,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,IAAI;IAKpD;;;;;OAKG;IACG,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBzD;;;;OAIG;IACG,gBAAgB,CACrB,GAAG,EAAE,YAAY,EACjB,WAAW,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC;IAqBhB;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;IAWlB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,2DAA2D;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAc5B,OAAO,CAAC,UAAU;IAgBlB,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,YAAY;YAkBN,aAAa;IAkC3B;;;;;OAKG;YACW,kBAAkB;IAkChC,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,aAAa;CAarB;AAgBD;;;;GAIG;AACH,YAAY,EAAE,yBAAyB,EAAE,CAAC"}

package/dist/services/voice/barge-in.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"barge-in.d.ts","sourceRoot":"","sources":["../../../src/services/voice/barge-in.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EACX,kBAAkB,EAElB,qBAAqB,EAErB,gBAAgB,EAChB,iBAAiB,EACjB,MAAM,SAAS,CAAC;AAEjB;+EAC+E;AAC/E,UAAU,cAAc;IACvB,UAAU,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,IAAI,CAAC;CACnD;AAID,MAAM,WAAW,eAAe;IAC/B,QAAQ,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC5B,SAAS,EAAE,OAAO,CAAC;CACnB;AAkCD,MAAM,WAAW,uBAAuB;IACvC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,iBAAkB,YAAW,iBAAiB;IAC1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IACxD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IACpE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC,0DAA0D;IAC1D,OAAO,CAAC,MAAM,CAAsC;IAEpD;;wBAEoB;IACpB,OAAO,CAAC,aAAa,CAAS;IAC9B;kCAC8B;IAC9B,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,wBAAwB,CAA8C;IAC9E,OAAO,CAAC,sBAAsB,CAAuB;IACrD,OAAO,CAAC,oBAAoB,CAAK;IACjC,OAAO,CAAC,QAAQ,CAA6B;gBAEjC,MAAM,GAAE,uBAA4B;IAMhD,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,IAAI;IAKrD,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,IAAI;IAM7C,SAAS,IAAI,IAAI;IAOjB,oEAAoE;IACpE,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAUzC,IAAI,eAAe,IAAI,OAAO,CAE7B;IAID,OAAO,CAAC,UAAU;IA8ClB,eAAe,CAAC,IAAI,EAAE;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;KACpB,GAAG,IAAI;IAiBR;;;;;OAKG;IACH,QAAQ,CACP,MAAM,GAAE,WAAW,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAY,EAC5D,WAAW,GAAE,MAAgD,GAC3D,kBAAkB;IAkBrB,OAAO,CAAC,WAAW,CAAmC;IAEtD;sEACkE;IAClE,kBAAkB,IAAI,kBAAkB,GAAG,IAAI;IAM/C,yEAAyE;IACzE,YAAY,IAAI,YAAY;IAI5B,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,IAAI;IAK7C,2EAA2E;IAC3E,WAAW,IAAI,IAAI;IAInB,KAAK,IAAI,IAAI;IASb,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,sBAAsB;IA0B9B,OAAO,CAAC,gBAAgB;CASxB"}

package/dist/services/voice/cancellation-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancellation-coordinator.d.ts","sourceRoot":"","sources":["../../../src/services/voice/cancellation-coordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EACN,KAAK,uBAAuB,EAC5B,yBAAyB,EACzB,KAAK,sBAAsB,EAC3B,MAAM,iBAAiB,CAAC;AAEzB;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,eAAe,EAAE;QAChB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QACnD,OAAO,CACN,QAAQ,EAAE,CAAC,KAAK,EAAE;YACjB,IAAI,EACD,SAAS,GACT,WAAW,GACX,SAAS,GACT,SAAS,GACT,iBAAiB,CAAC;YACrB,MAAM,EAAE,MAAM,CAAC;YACf,MAAM,CAAC,EAAE,MAAM,CAAC;SAChB,KAAK,IAAI,GACR,MAAM,IAAI,CAAC;KACd,CAAC;CACF;AAED,MAAM,WAAW,mCAAmC;IACnD,8BAA8B;IAC9B,OAAO,EAAE,kBAAkB,CAAC;IAC5B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,uBAAuB,KAAK,IAAI,CAAC;IACtE;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,uBAAuB,KAAK,IAAI,CAAC;IACpD;;;OAGG;IACH,QAAQ,CAAC,EAAE,yBAAyB,CAAC;CACrC;AAgBD,qBAAa,4BAA4B;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmD;IAC7E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiD;IACzE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,kDAAkD;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;gBAE1C,IAAI,EAAE,mCAAmC;IAOrD;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE;QACb,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;KACd,GAAG,sBAAsB;IA8D1B,2DAA2D;IAC3D,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,sBAAsB,GAAG,IAAI;IAItD,kCAAkC;IAClC,YAAY,IAAI,MAAM,EAAE;IAIxB;;;OAGG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,uBAAuB,GAAG,OAAO;IAI/D;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIhC;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIlC;;;;;;;;;OASG;IACH,qBAAqB,CACpB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE;QACX,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;KACnE,GACC,MAAM,IAAI;IAQb;;;OAGG;IACH,OAAO,IAAI,IAAI;CASf"}

package/dist/services/voice/checkpoint-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-manager.d.ts","sourceRoot":"","sources":["../../../src/services/voice/checkpoint-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAEN,KAAK,eAAe,EACpB,KAAK,gBAAgB,IAAI,oBAAoB,EAC7C,MAAM,sBAAsB,CAAC;AAE9B;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAC;IACX,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACjD;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACrC;;;;OAIG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACxE;;;;OAIG;IACH,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D;;;;OAIG;IACH,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AAED;;;;GAIG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;gBAC1C,OAAO,EAAE,MAAM;CAI3B;AAMD,MAAM,WAAW,wBAAwB;IACxC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC;IACjD,wEAAwE;IACxE,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CACjB;AAID;;;;;;GAMG;AACH,qBAAa,iBAAkB,YAAW,qBAAqB;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmC;IACjE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;gBAE9B,IAAI,EAAE,wBAAwB;IAYpC,cAAc,CACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACV,OAAO,CAAC,gBAAgB,CAAC;IAmBtB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAc1D,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAchE;;;;OAIG;IACG,cAAc,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAI5D,OAAO,CAAC,UAAU;CAOlB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACtC,iDAAiD;IACjD,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,MAAM,kBAAkB,GAAG,CAChC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,KACR,sBAAsB,CAAC;AAE5B;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,qBAAqB;IAkBtD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;IAjB5C,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6C;IACvE;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,KAAK,CACvB;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAChE;QAAE,IAAI,EAAE,SAAS,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GACrC;QAAE,IAAI,EAAE,SAAS,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CACvC,CAAM;IACP;;;OAGG;IACH,aAAa,EAAE,SAAS,MAAM,EAAE,CAAM;gBAET,cAAc,CAAC,EAAE,kBAAkB,YAAA;IAE1D,cAAc,CACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACV,OAAO,CAAC,gBAAgB,CAAC;IAkBtB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAW1D,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAUhE,gDAAgD;IAChD,eAAe,IAAI,MAAM;IAIzB,sDAAsD;IACtD,WAAW,CAAC,MAAM,EAAE,gBAAgB,GAAG,sBAAsB,GAAG,SAAS;CAGzE"}

package/dist/services/voice/checkpoint-policy.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Voice checkpoint policy — thin VAD-event → checkpoint-op translator that
+ * sits between the voice loop (turn-controller / pipeline / vad) and the
+ * `GatedCheckpointManager` (`../checkpoint-manager.ts`).
+ *
+ * Why a separate policy module?
+ *
+ *   - The constraint envelope on this scaffold explicitly forbids editing
+ *     `turn-controller.ts`, `pipeline.ts`, `pipeline-impls.ts`, `vad.ts`,
+ *     `scheduler.ts`, `phrase-chunker.ts`, `barge-in.ts`, `transcriber.ts`,
+ *     and anything under `voice/kokoro/` / `voice/streaming-asr/`. Those
+ *     files are owned by other agents.
+ *   - But the upstream merge for `--ctx-checkpoints` lands "any week now,"
+ *     and the JS-side rollback policy is what the merge unlocks. So the
+ *     policy lives here as a free-standing module that the turn controller
+ *     can pick up in a follow-up PR by injecting it into its VAD handler
+ *     and calling `onSpeechPause` / `onSpeechResume` / `onSpeechEndCommit`
+ *     / `onHardStop` at the matching transitions.
+ *   - The wiring required in `turn-controller.ts` is documented in the
+ *     `WIRING-INSTRUCTIONS` comment at the bottom of this file and in
+ *     `docs/eliza-1-ctx-checkpoints-integration.md`. We intentionally do
+ *     NOT apply the wiring here — that is a follow-up PR scoped to the
+ *     turn-controller owner.
+ *
+ * Policy summary (one C1 per turn, named `pre-speculative-T<turnId>`):
+ *
+ *   - `onSpeechPause(turnId)` — VAD reports the user stopped speaking but
+ *     hangover hasn't elapsed. Save C1 and let the caller kick the
+ *     speculative drafter. If the save fails the policy logs and continues
+ *     (callers MUST treat speculative work as best-effort).
+ *
+ *   - `onSpeechResume(turnId)` — VAD fires `speech-active` within the
+ *     rollback window. If we previously kicked a speculative draft (the
+ *     caller flips `speculativeFired=true` to tell us), restore C1 so the
+ *     KV state is rolled back to the pre-draft point. Otherwise no-op.
+ *
+ *   - `onSpeechEndCommit(turnId)` — VAD's hangover elapsed; the pause was a
+ *     real turn boundary. The speculative draft is promoted. Erase C1: we
+ *     no longer need a rollback target for this turn.
+ *
+ *   - `onHardStop(turnId)` — caller-initiated cancellation (e.g. user
+ *     pressed mute, app backgrounded). If C1 exists, prefer restoring to
+ *     it so the KV cache is in a known-clean state for the next turn; if
+ *     C1 isn't around, fall back to `cancel` (the gated manager will
+ *     either issue `DELETE /slots/<id>` or invoke the SSE-disconnect
+ *     callback depending on the gate).
+ *
+ * All four hooks are idempotent and survive a missing C1 by no-op'ing.
+ * Errors from the underlying manager are caught and reported through the
+ * `events.onError` sink — the policy NEVER throws back into the voice
+ * loop, because a failing checkpoint endpoint must not be able to break
+ * audio.
+ *
+ * The policy holds no state of its own beyond the per-turn name; the
+ * `GatedCheckpointManager` owns the registry, the REST client, and the
+ * capability cache.
+ *
+ * --- WIRING-INSTRUCTIONS (turn-controller.ts) -----------------------------
+ *
+ * The turn-controller owner adds (after the upstream merge lands):
+ *
+ *   1. Construct a `GatedCheckpointManager` once at session start and
+ *      pass it into a `CheckpointPolicy` instance (one per slot).
+ *   2. In the VAD `speech-pause` handler, immediately after the pause
+ *      hangover timer is armed:
+ *
+ *          await policy.onSpeechPause(this.turnId, this.slotId);
+ *          // ...kick speculative drafter against the partial transcript
+ *
+ *   3. In the VAD `speech-active` handler (only when arriving within the
+ *      rollback window — the controller already tracks this):
+ *
+ *          await policy.onSpeechResume(this.turnId, this.slotId, {
+ *            speculativeFired: this.speculativeFired,
+ *          });
+ *          // ...abort the speculative drafter
+ *
+ *   4. In the `speech-end` → SPEAKING transition (after the verifier
+ *      promotes the draft):
+ *
+ *          await policy.onSpeechEndCommit(this.turnId, this.slotId);
+ *
+ *   5. In the `dispose()` path and any other hard-stop site (mute, app
+ *      background, error shutdown, barge-in mid-SPEAKING):
+ *
+ *          await policy.onHardStop(this.turnId, this.slotId, () => {
+ *            this.speculativeAbort?.abort();  // SSE-disconnect callback
+ *          });
+ *
+ *   6. Feature flag: pass `useCtxCheckpoints` through to the
+ *      `GatedCheckpointManager` constructor; when off the policy still
+ *      runs but every call is a logged no-op.
+ *
+ * The turn-controller must NOT call `mgr.save/restore/erase/cancel`
+ * directly — those names are reserved for the policy so the gated/no-op
+ * branching stays in one place. The `policy.events.onError` sink lets the
+ * controller forward checkpoint failures into its existing voice-loop
+ * telemetry without coupling to the REST error type.
+ */
+import type { CheckpointHandle, GatedCheckpointManager, SseDisconnectFn } from "../checkpoint-manager";
+/**
+ * Errors are surfaced through this sink rather than rethrown. The voice
+ * loop wires it into its existing telemetry; tests assert on it directly.
+ */
+export interface CheckpointPolicyEvents {
+    onError?(op: "save" | "restore" | "erase" | "cancel", error: unknown, turnId: string): void;
+    /**
+     * Called after a successful save so callers can record the handle in
+     * their per-turn state if they want to bypass the name-based lookup on
+     * the matching restore.
+     */
+    onSaved?(turnId: string, handle: CheckpointHandle): void;
+    /** Called after a successful restore. */
+    onRestored?(turnId: string, handle: CheckpointHandle): void;
+    /** Called when the policy decides to no-op (registry miss, gate off). */
+    onNoop?(op: "save" | "restore" | "erase" | "cancel", turnId: string, reason: "gate-off" | "registry-miss" | "no-speculative"): void;
+}
+export interface CheckpointPolicyOptions {
+    /** Gated manager. Owned by the caller; one per session. */
+    manager: GatedCheckpointManager;
+    /** Events sink (errors + observability). Optional. */
+    events?: CheckpointPolicyEvents;
+}
+/** Optional second arg to `onSpeechResume` so the policy knows whether
+ * a speculative draft actually fired. When `false`, the resume is a no-op
+ * (no draft means nothing to roll back).
+ */
+export interface SpeechResumeContext {
+    speculativeFired: boolean;
+}
+/**
+ * Voice checkpoint policy. Stateless w.r.t. checkpoints (the manager owns
+ * the registry) — only holds the manager + event sink. One instance per
+ * voice session is enough; the `turnId` argument scopes each operation.
+ */
+export declare class CheckpointPolicy {
+    private readonly manager;
+    private readonly events;
+    constructor(opts: CheckpointPolicyOptions);
+    /**
+     * VAD `speech-pause`. Save C1. Caller kicks the speculative drafter on
+     * its own — the policy doesn't care; it just guarantees the rollback
+     * target exists.
+     */
+    onSpeechPause(turnId: string, slotId: number): Promise<void>;
+    /**
+     * VAD `speech-active` within the rollback window. Restore C1 ONLY if
+     * the caller actually kicked a speculative draft — otherwise the KV
+     * state hasn't been mutated and we'd be doing a needless REST round
+     * trip.
+     */
+    onSpeechResume(turnId: string, slotId: number, ctx: SpeechResumeContext): Promise<void>;
+    /**
+     * VAD's hangover elapsed → real turn boundary. Speculative draft is
+     * being promoted, so C1 is no longer needed. Erase frees the registry
+     * slot (the server-side LRU handles its own eviction independently).
+     */
+    onSpeechEndCommit(turnId: string, slotId: number): Promise<void>;
+    /**
+     * Hard-stop: caller-initiated cancellation. Prefer rolling back to C1
+     * (clean KV state for the next turn) when available, else cancel any
+     * in-flight decode on the slot. `sseDisconnect` is the existing voice-
+     * loop abort hook — required because the gated manager falls back to
+     * it when the REST endpoints aren't available.
+     */
+    onHardStop(turnId: string, slotId: number, sseDisconnect: SseDisconnectFn): Promise<void>;
+}
+/**
+ * Per-turn checkpoint name. Keeps the namespace stable so a hard-stop
+ * after a normal commit doesn't collide with the next turn's C1.
+ *
+ * The format is the only thing callers outside the policy ever see —
+ * `GatedCheckpointManager.getNamedHandle('pre-speculative-T123')` returns
+ * the same handle the policy used. Keep it stable; if the format changes
+ * in a later change, audit every consumer of `getNamedHandle`.
+ */
+export declare function checkpointNameFor(turnId: string): string;
+//# sourceMappingURL=checkpoint-policy.d.ts.map

package/dist/services/voice/checkpoint-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-policy.d.ts","sourceRoot":"","sources":["../../../src/services/voice/checkpoint-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkGG;AAGH,OAAO,KAAK,EACX,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,MAAM,uBAAuB,CAAC;AAE/B;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACtC,OAAO,CAAC,CACP,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,EAC3C,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,GACZ,IAAI,CAAC;IACR;;;;OAIG;IACH,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACzD,yCAAyC;IACzC,UAAU,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC5D,yEAAyE;IACzE,MAAM,CAAC,CACN,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,EAC3C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,UAAU,GAAG,eAAe,GAAG,gBAAgB,GACrD,IAAI,CAAC;CACR;AAED,MAAM,WAAW,uBAAuB;IACvC,2DAA2D;IAC3D,OAAO,EAAE,sBAAsB,CAAC;IAChC,sDAAsD;IACtD,MAAM,CAAC,EAAE,sBAAsB,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC,gBAAgB,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;gBAEpC,IAAI,EAAE,uBAAuB;IAKzC;;;;OAIG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BlE;;;;;OAKG;IACG,cAAc,CACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,mBAAmB,GACtB,OAAO,CAAC,IAAI,CAAC;IAqChB;;;;OAIG;IACG,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBtE;;;;;;OAMG;IACG,UAAU,CACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,eAAe,GAC5B,OAAO,CAAC,IAAI,CAAC;CAyChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOxD"}

package/dist/services/voice/corpus-augment.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Voice Workbench corpus augmentation — acoustic degradation DSP (#8785).
+ *
+ * Real rooms are not clean. The corpus generator produces dry speech; this
+ * module degrades it the way a microphone actually hears it: additive room
+ * noise at a target SNR, reverberation (near vs far), far-field attenuation,
+ * a low-quality/telephone line, and competing background talkers. Every
+ * function is PURE and DETERMINISTIC (seeded PRNG, no `Math.random`, no I/O), so
+ * the same scenario + seed always yields byte-identical audio — a labeled,
+ * reproducible corpus the real ASR/diarization/EOT models can be benchmarked
+ * against, and the DSP itself is unit-testable in CI with no models.
+ *
+ * Layering: this module knows nothing about scenarios. It operates on mono
+ * `Float32Array` PCM at a given sample rate. `corpus-generator.ts` translates a
+ * scenario's declarative {@link AugmentationSpec} into these calls.
+ */
+/** Root-mean-square amplitude over [start, end). */
+export declare function measureRms(pcm: Float32Array, start?: number, end?: number): number;
+/** Peak absolute amplitude over [start, end). */
+export declare function measurePeak(pcm: Float32Array, start?: number, end?: number): number;
+/** Linear amplitude ratio for a dB gain (+6 dB ≈ ×2, −6 dB ≈ ×0.5). */
+export declare function dbToGain(db: number): number;
+/** Estimated SNR (dB) of a signal region against a noise-only region. */
+export declare function estimateSnrDb(signalRms: number, noiseRms: number): number;
+export type NoiseKind = "white" | "pink" | "music";
+/**
+ * Add background noise at a target SNR (dB) relative to the signal's voiced RMS.
+ * Lower `snrDb` = noisier. `pink` is a one-pole-filtered approximation of 1/f
+ * room rumble; `white` is flat; `music` is a seeded harmonic chord (a few
+ * detuned partials under a slow tremolo) — tonal and sustained, the kind of
+ * steady background that fools an energy-only VAD where flat hiss would not.
+ * The noise floor is added across the WHOLE stream (including silent gaps) so
+ * silence is no longer pristine — exactly the condition that makes a real
+ * VAD/EOT classifier work for its living.
+ */
+export declare function addNoise(pcm: Float32Array, opts: {
+    snrDb: number;
+    kind?: NoiseKind;
+    seed?: number;
+}): Float32Array;
+/**
+ * Simulate a low-quality / telephone line: band-limit to ~300–3400 Hz then
+ * companded 8-bit quantization. Cheap mics and phone codecs strip the highs and
+ * add quantization grunge, which is the dominant real-world ASR stressor for
+ * "voices near and far" / low-quality input.
+ */
+export declare function applyLowQualityLine(pcm: Float32Array, sampleRate: number): Float32Array;
+/**
+ * Freeverb-style Schroeder reverb (4 parallel combs → 2 series allpasses),
+ * mixed with the dry signal. `room` (0..1) sets reflection density/decay;
+ * `wet` (0..1) the reflected level. Reverb spreads energy in time — speech
+ * keeps ringing after the talker stops — which is what makes a far/reverberant
+ * voice hard to endpoint and to diarize. The output is `dry.length + tail`
+ * samples so the decay is preserved (callers may keep or trim the tail).
+ */
+export declare function applyReverb(pcm: Float32Array, sampleRate: number, opts?: {
+    room?: number;
+    wet?: number;
+    tailSec?: number;
+}): Float32Array;
+/** Multiply the whole stream by a dB gain (far-field attenuation = negative). */
+export declare function applyGainDb(pcm: Float32Array, db: number): Float32Array;
+/**
+ * Mix an overlay stream (a competing talker, babble, or the agent's own TTS for
+ * an echo test) into a base stream at a given level, starting at `offsetSamples`
+ * and optionally looping the overlay to cover the base. The base length is
+ * preserved. Returns a new array; neither input is mutated.
+ */
+export declare function mixInto(base: Float32Array, overlay: Float32Array, opts?: {
+    gainDb?: number;
+    offsetSamples?: number;
+    loop?: boolean;
+}): Float32Array;
+/** Declarative degradation for one stream (the scenario's `environment`). */
+export interface AugmentationSpec {
+    /** Additive room-noise SNR (dB) relative to voiced speech. Lower = noisier. */
+    noiseSnrDb?: number;
+    /** Noise character (default white). */
+    noiseKind?: NoiseKind;
+    /** Reverb room size 0..1 (near→far, small→large room). */
+    reverb?: number;
+    /** Reverb wet level 0..1 (defaults from `reverb` when omitted). */
+    reverbWet?: number;
+    /** Far-field attenuation in dB (how many dB QUIETER; positive number). */
+    farFieldDb?: number;
+    /** Band-limit + 8-bit companding (telephone / cheap-mic line). */
+    lowQuality?: boolean;
+    /** Competing background talkers, mixed this many dB BELOW the speech. */
+    backgroundTalkersDb?: number;
+    /** Deterministic seed for noise/babble. */
+    seed?: number;
+}
+/** True when the spec asks for any degradation at all. */
+export declare function specIsClean(spec: AugmentationSpec | undefined): boolean;
+export interface AugmentPcmOptions {
+    /**
+     * A babble source (a competing-talker stream) for `backgroundTalkersDb`.
+     * The generator supplies one synthesized from other voices; omitted = no
+     * background talkers even if the spec asks (the runner logs the gap).
+     */
+    babble?: Float32Array;
+    /** Trim reverb tail back to the input length (keeps corpus timing exact). */
+    trimReverbTail?: boolean;
+}
+/**
+ * Apply a full degradation chain to one stream, in acoustically sensible order:
+ * background talkers → reverb (room reflections) → far-field gain → low-quality
+ * line → additive noise floor. Pure; returns a new array.
+ */
+export declare function augmentPcm(pcm: Float32Array, sampleRate: number, spec: AugmentationSpec, options?: AugmentPcmOptions): Float32Array;
+//# sourceMappingURL=corpus-augment.d.ts.map

package/dist/services/voice/corpus-augment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"corpus-augment.d.ts","sourceRoot":"","sources":["../../../src/services/voice/corpus-augment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAuBH,oDAAoD;AACpD,wBAAgB,UAAU,CACzB,GAAG,EAAE,YAAY,EACjB,KAAK,SAAI,EACT,GAAG,SAAa,GACd,MAAM,CAOR;AAED,iDAAiD;AACjD,wBAAgB,WAAW,CAC1B,GAAG,EAAE,YAAY,EACjB,KAAK,SAAI,EACT,GAAG,SAAa,GACd,MAAM,CASR;AAED,uEAAuE;AACvE,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIzE;AAED,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAEnD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACvB,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD,YAAY,CAoDd;AAkFD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAClC,GAAG,EAAE,YAAY,EACjB,UAAU,EAAE,MAAM,GAChB,YAAY,CAKd;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAC1B,GAAG,EAAE,YAAY,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1D,YAAY,CA+Cd;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,GAAG,YAAY,CAKvE;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CACtB,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,YAAY,EACrB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GACpE,YAAY,CAad;AAED,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAChC,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yEAAyE;IACzE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,0DAA0D;AAC1D,wBAAgB,WAAW,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,GAAG,OAAO,CASvE;AAED,MAAM,WAAW,iBAAiB;IACjC;;;;OAIG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,6EAA6E;IAC7E,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACzB,GAAG,EAAE,YAAY,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,gBAAgB,EACtB,OAAO,GAAE,iBAAsB,GAC7B,YAAY,CA0Dd"}

package/dist/services/voice/corpus-generator.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Voice Workbench corpus generator (#8785).
+ *
+ * Turns a declarative {@link VoiceScenario} into one labeled audio stream + a
+ * ground-truth JSON the headless runner scores against. Two synthesis paths,
+ * one shape:
+ *
+ *   - Synthetic (default, deterministic, NO native model): formant-resonator
+ *     speech-like PCM (`__test-helpers__/synthetic-speech.ts`) the Silero VAD
+ *     reads as speech. Reproducible in CI with no artifacts — it exercises the
+ *     pipeline plumbing + the scorers/labels, not diarization/WER *accuracy*.
+ *   - Real TTS (gated): an injected {@link CorpusTtsSynthesizer} (Kokoro /
+ *     OmniVoice via the TTS route) produces natural speech. Real diarization
+ *     DER and transcription WER benchmarking need this path.
+ *
+ * `generateVoiceCorpus` is pure (no I/O) so it is unit-testable without disk;
+ * `writeVoiceCorpus` / `readVoiceCorpus` handle the versioned on-disk corpus.
+ * A turn's labels (speaker, transcript, respond decision, entity) come straight
+ * from the scenario, so the ground truth is reproducible regardless of path.
+ */
+import { type VoiceEnvironment, type VoiceScenario } from "./voice-scenario";
+/** Per-turn ground-truth label with sample-accurate timing. */
+export interface CorpusTurnLabel {
+    index: number;
+    /** Diarization ground-truth label (the participant who spoke). */
+    speaker: string;
+    /** Resolved elizaOS entity id for the speaker, when the scenario binds one. */
+    entityId?: string;
+    /** First sample of voiced speech in this turn (after any lead silence). */
+    speechStartSample: number;
+    /** Sample just past the voiced speech (before trailing pauses). */
+    speechEndSample: number;
+    /** First sample of this turn's whole segment in the stream. */
+    segmentStartSample: number;
+    /** Sample just past this turn's whole segment (incl. trailing pauses). */
+    segmentEndSample: number;
+    /** Reference transcript for WER scoring. */
+    referenceTranscript: string;
+    /** Ground truth: should the agent respond to this turn? */
+    expectRespond: boolean;
+    /** Ground truth: is this segment a real end-of-turn boundary? */
+    expectEndOfTurn?: boolean;
+    /** Expected inferred/recognized entity, when the scenario asserts one. */
+    expectedEntity?: string;
+    /** TTS voice id used for this turn (real-TTS path), when set. */
+    ttsVoiceId?: string;
+    /** True when this turn was formant-synthesized rather than real TTS. */
+    synthetic: boolean;
+    /** Acoustic degradation applied to this turn's audio (when any). */
+    environment?: VoiceEnvironment;
+    /** True when this "turn" is the agent's own TTS echoed back (not a user turn). */
+    isAgentEcho?: boolean;
+    /** Ground truth: the speaker is the device owner / primary enrolled voice. */
+    isOwner?: boolean;
+    /** The agent's spoken reply to this turn (drives the echo gate downstream). */
+    agentReplyText?: string;
+}
+/**
+ * On-disk corpus ground-truth schema version. Bump when the labeled-corpus
+ * shape changes incompatibly; `readVoiceCorpusGroundTruth` treats a corpus
+ * written by a different version as absent (→ `skipped`, never a stale `pass`).
+ */
+export declare const CORPUS_SCHEMA_VERSION = 1;
+export interface CorpusGroundTruth {
+    /** Labeled-corpus schema version (see {@link CORPUS_SCHEMA_VERSION}). */
+    schemaVersion: number;
+    scenarioId: string;
+    classes: VoiceScenario["classes"];
+    sampleRate: number;
+    totalSamples: number;
+    durationSec: number;
+    participants: Array<{
+        label: string;
+        entityId?: string;
+        isOwner?: boolean;
+        ttsVoiceId?: string;
+    }>;
+    agents?: string[];
+    /** Entity ids the agent answers without a wake word (owner + enrolled). */
+    knownSpeakerEntityIds?: string[];
+    turns: CorpusTurnLabel[];
+    /** True when EVERY turn was synthetic (no real TTS used anywhere). */
+    synthetic: boolean;
+}
+export interface GeneratedVoiceCorpus {
+    pcm: Float32Array;
+    sampleRate: number;
+    groundTruth: CorpusGroundTruth;
+}
+/**
+ * Real-TTS synthesizer. Gated: when omitted, the generator uses deterministic
+ * synthetic speech. An implementation wraps the TTS route / Kokoro engine and
+ * returns mono PCM at the requested sample rate.
+ */
+export interface CorpusTtsSynthesizer {
+    synthesize(args: {
+        text: string;
+        voiceId?: string;
+        speakerLabel: string;
+        turnIndex: number;
+        isAgentEcho: boolean;
+        sampleRate: number;
+    }): Promise<Float32Array>;
+}
+export interface GenerateVoiceCorpusOptions {
+    sampleRate?: number;
+    /** Inject a real-TTS synthesizer to produce natural speech (else synthetic). */
+    synthesizer?: CorpusTtsSynthesizer;
+    /** Silence (s) spliced after a turn that declares no explicit pauses. */
+    interTurnSilenceSec?: number;
+    /** Synthetic-speech sizing: characters of text per second of audio. */
+    charsPerSecond?: number;
+}
+/**
+ * Generate one labeled audio stream for a scenario. Throws on an invalid
+ * scenario (fail loud — a malformed corpus must not silently produce garbage).
+ * A turn that carries only `audioRef` (no `text`) is not synthesizable here and
+ * is rejected; pre-rendered audio is supplied through the corpus on disk.
+ */
+export declare function generateVoiceCorpus(scenario: VoiceScenario, options?: GenerateVoiceCorpusOptions): Promise<GeneratedVoiceCorpus>;
+export interface VoiceCorpusPaths {
+    dir: string;
+    audioPath: string;
+    groundTruthPath: string;
+}
+/** Persist a generated corpus as `audio.wav` + `ground-truth.json` under `dir`. */
+export declare function writeVoiceCorpus(corpus: GeneratedVoiceCorpus, dir: string): VoiceCorpusPaths;
+/**
+ * Read a previously-written corpus's ground truth. Returns null when the corpus
+ * directory or its ground-truth file is absent (the honesty contract — the
+ * runner reports `skipped`, never `pass`, when corpus artifacts are missing).
+ */
+export declare function readVoiceCorpusGroundTruth(dir: string): CorpusGroundTruth | null;
+//# sourceMappingURL=corpus-generator.d.ts.map

package/dist/services/voice/corpus-generator.d.ts.map

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

package/dist/services/voice/diarization-error-rate.d.ts

@@ -0,0 +1,40 @@
+export interface DiarizationSegment {
+    /** Speaker label (any stable string — ground-truth and hypothesis label
+     * spaces are mapped against each other, so the raw strings need not match). */
+    speaker: string;
+    /** Segment start, milliseconds. */
+    startMs: number;
+    /** Segment end, milliseconds (must be ≥ startMs). */
+    endMs: number;
+}
+export interface DerResult {
+    /** Diarization Error Rate: (missed + falseAlarm + confusion) / referenceMs.
+     * 0 = perfect; can exceed 1 when false alarms dominate. */
+    der: number;
+    /** Reference speech the system failed to attribute to anyone (ms). */
+    missedMs: number;
+    /** System speech with no reference speaker present (ms). */
+    falseAlarmMs: number;
+    /** Reference speech attributed to the wrong (mapped) speaker (ms). */
+    confusionMs: number;
+    /** Total reference speaker-time (Σ |ref speakers in frame| · frame), the DER denominator. */
+    totalReferenceMs: number;
+    /** The chosen hypothesis→reference speaker mapping (optimal for matched time). */
+    mapping: Record<string, string>;
+}
+export interface DerOptions {
+    /** Frame size in ms (default 10). Smaller = more precise, more work. */
+    frameMs?: number;
+    /** Above this combined speaker count, fall back to a greedy mapping instead
+     * of the exact permutation search (keeps it O(n) not O(n!)). Default 7. */
+    maxExactSpeakers?: number;
+}
+/**
+ * Frame-based Diarization Error Rate between a reference (ground-truth) speaker
+ * timeline and a hypothesis (diarizer output) timeline. Returns DER plus its
+ * missed / false-alarm / confusion decomposition and the speaker mapping used.
+ */
+export declare function computeDiarizationErrorRate(reference: readonly DiarizationSegment[], hypothesis: readonly DiarizationSegment[], options?: DerOptions): DerResult;
+/** Whether a diarization hypothesis is within a scenario's `maxDer` budget. */
+export declare function diarizationWithinBudget(result: Pick<DerResult, "der">, maxDer: number): boolean;
+//# sourceMappingURL=diarization-error-rate.d.ts.map