@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.11-beta.7

package/src/services/voice/partial-stabilizer.d.ts

@@ -0,0 +1,73 @@
+/**
+ * A2 — LocalAgreement-n streaming-ASR partial stabilizer.
+ *
+ * Streaming ASR (the Qwen3-ASR fused build running on partial windows)
+ * emits a fresh partial transcript on every
+ * audio frame. Each partial can revise tokens the previous partial
+ * already showed — "the cat sa" → "the cat sat" → "the cat sat on" is
+ * fine, but "the cat sa" → "the cap sat" rewrites earlier text. Handing
+ * a TTS chunker every revision causes audible stutter when the agent's
+ * drafter starts speaking text the verifier later rejects.
+ *
+ * The LocalAgreement-n trick: only commit a prefix to downstream once it
+ * has appeared identically in `n` consecutive partials. Below that
+ * threshold the text is "pending" — visible to UI for confirmation
+ * latency, but never sent to the drafter / phrase chunker. n=2 is the
+ * sweet spot for voice — large enough to suppress single-frame ASR
+ * jitter, small enough that the stable prefix tracks the speaker
+ * within ~one extra frame.
+ *
+ * Wiring: the streaming-ASR adapter calls `feed(partial)` per frame; the
+ * `stable` portion is what flows into `splitTranscriptToTokens` and the
+ * drafter. `pending` is suffix-only, fed to UI for visual feedback. The
+ * stabilizer is feature-flagged off until the streaming-ASR backend is
+ * wired (see `voice/pipeline.ts`'s `usePartialStabilizer`).
+ *
+ * No `any`, no fallbacks: a malformed partial (e.g. an empty string)
+ * collapses the stable prefix to whatever the agreement window still
+ * supports — this is correctness, not a swallow.
+ */
+export interface PartialStabilizerOptions {
+    /**
+     * Number of consecutive identical partials a token has to appear in
+     * before it migrates from `pending` → `stable`. Default 2 (the
+     * LocalAgreement-2 setting that the streaming-ASR literature finds
+     * close to optimal for English voice input).
+     */
+    agreementCount?: number;
+}
+export interface StabilizerOutput {
+    /** The agreed-on prefix — safe to hand the drafter / phrase chunker. */
+    stable: string;
+    /**
+     * The suffix still awaiting `n` matching partials — surface in UI but
+     * do not commit. Concatenating `stable + pending` reconstructs the
+     * latest raw partial.
+     */
+    pending: string;
+}
+export declare class PartialStabilizer {
+    private readonly agreementCount;
+    /**
+     * The most recent partials, oldest first. We only need the last
+     * `agreementCount` entries — the agreed prefix is the intersection of
+     * all of them. Length 0 before any feed.
+     */
+    private history;
+    /** The longest committed stable prefix so far. Monotonically grows. */
+    private committed;
+    constructor(options?: PartialStabilizerOptions);
+    /**
+     * Feed the latest streaming-ASR partial. Returns the stable / pending
+     * split. The stable prefix is monotonically non-decreasing across calls
+     * — once a span has been agreed `n` times it stays committed even if a
+     * later partial briefly disagrees (the ASR will catch up; rolling back
+     * would cause downstream stutter).
+     */
+    feed(partial: string): StabilizerOutput;
+    /** The current committed stable prefix (read-only view). */
+    stable(): string;
+    /** Clear all history. Call at utterance boundaries. */
+    reset(): void;
+}
+//# sourceMappingURL=partial-stabilizer.d.ts.map

package/src/services/voice/partial-stabilizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"partial-stabilizer.d.ts","sourceRoot":"","sources":["partial-stabilizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,WAAW,wBAAwB;IACxC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAChC,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;CAChB;AAgBD,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC;;;;OAIG;IACH,OAAO,CAAC,OAAO,CAAgB;IAC/B,uEAAuE;IACvE,OAAO,CAAC,SAAS,CAAM;gBAEX,OAAO,GAAE,wBAA6B;IAUlD;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB;IAoCvC,4DAA4D;IAC5D,MAAM,IAAI,MAAM;IAIhB,uDAAuD;IACvD,KAAK,IAAI,IAAI;CAIb"}

package/src/services/voice/partial-stabilizer.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { PartialStabilizer } from "./partial-stabilizer";
+
+describe("PartialStabilizer (LocalAgreement-n)", () => {
+	it("never commits anything from a single partial (n=2)", () => {
+		const s = new PartialStabilizer();
+		const out = s.feed("the cat");
+		expect(out.stable).toBe("");
+		expect(out.pending).toBe("the cat");
+	});
+
+	it("commits the common prefix once a second partial agrees", () => {
+		const s = new PartialStabilizer();
+		s.feed("the cat sa");
+		const out = s.feed("the cat sat");
+		// The two partials share the prefix "the cat sa".
+		expect(out.stable).toBe("the cat sa");
+		expect(out.pending).toBe("t");
+	});
+
+	it("extends the stable prefix as more partials agree", () => {
+		const s = new PartialStabilizer();
+		s.feed("the cat sa");
+		s.feed("the cat sat");
+		// Third partial agrees on "the cat sat" with the second.
+		const out = s.feed("the cat sat on");
+		expect(out.stable).toBe("the cat sat");
+		expect(out.pending).toBe(" on");
+	});
+
+	it("does not roll back a committed prefix when a later partial briefly disagrees", () => {
+		const s = new PartialStabilizer();
+		s.feed("the cat sa");
+		s.feed("the cat sat"); // stable becomes "the cat sa"
+		const out = s.feed("the dog");
+		expect(out.stable).toBe("the cat sa");
+		// The new partial does not start with the committed prefix — the
+		// whole new partial surfaces as pending so UI shows the fresh text.
+		expect(out.pending).toBe("the dog");
+	});
+
+	it("respects a custom agreementCount", () => {
+		const s = new PartialStabilizer({ agreementCount: 3 });
+		expect(s.feed("hello").stable).toBe("");
+		expect(s.feed("hello world").stable).toBe("");
+		// Three identical partials needed before any prefix commits.
+		const out = s.feed("hello world!");
+		expect(out.stable).toBe("hello");
+	});
+
+	it("reset clears all state", () => {
+		const s = new PartialStabilizer();
+		s.feed("abc");
+		s.feed("abcd"); // stable = "abc"
+		expect(s.stable()).toBe("abc");
+		s.reset();
+		expect(s.stable()).toBe("");
+		expect(s.feed("xyz").stable).toBe("");
+	});
+
+	it("rejects an invalid agreementCount", () => {
+		expect(() => new PartialStabilizer({ agreementCount: 0 })).toThrow();
+		expect(() => new PartialStabilizer({ agreementCount: -1 })).toThrow();
+		expect(
+			() => new PartialStabilizer({ agreementCount: Number.NaN }),
+		).toThrow();
+	});
+});

package/src/services/voice/partial-stabilizer.ts

@@ -0,0 +1,140 @@
+/**
+ * A2 — LocalAgreement-n streaming-ASR partial stabilizer.
+ *
+ * Streaming ASR (the Qwen3-ASR fused build running on partial windows)
+ * emits a fresh partial transcript on every
+ * audio frame. Each partial can revise tokens the previous partial
+ * already showed — "the cat sa" → "the cat sat" → "the cat sat on" is
+ * fine, but "the cat sa" → "the cap sat" rewrites earlier text. Handing
+ * a TTS chunker every revision causes audible stutter when the agent's
+ * drafter starts speaking text the verifier later rejects.
+ *
+ * The LocalAgreement-n trick: only commit a prefix to downstream once it
+ * has appeared identically in `n` consecutive partials. Below that
+ * threshold the text is "pending" — visible to UI for confirmation
+ * latency, but never sent to the drafter / phrase chunker. n=2 is the
+ * sweet spot for voice — large enough to suppress single-frame ASR
+ * jitter, small enough that the stable prefix tracks the speaker
+ * within ~one extra frame.
+ *
+ * Wiring: the streaming-ASR adapter calls `feed(partial)` per frame; the
+ * `stable` portion is what flows into `splitTranscriptToTokens` and the
+ * drafter. `pending` is suffix-only, fed to UI for visual feedback. The
+ * stabilizer is feature-flagged off until the streaming-ASR backend is
+ * wired (see `voice/pipeline.ts`'s `usePartialStabilizer`).
+ *
+ * No `any`, no fallbacks: a malformed partial (e.g. an empty string)
+ * collapses the stable prefix to whatever the agreement window still
+ * supports — this is correctness, not a swallow.
+ */
+
+export interface PartialStabilizerOptions {
+	/**
+	 * Number of consecutive identical partials a token has to appear in
+	 * before it migrates from `pending` → `stable`. Default 2 (the
+	 * LocalAgreement-2 setting that the streaming-ASR literature finds
+	 * close to optimal for English voice input).
+	 */
+	agreementCount?: number;
+}
+
+export interface StabilizerOutput {
+	/** The agreed-on prefix — safe to hand the drafter / phrase chunker. */
+	stable: string;
+	/**
+	 * The suffix still awaiting `n` matching partials — surface in UI but
+	 * do not commit. Concatenating `stable + pending` reconstructs the
+	 * latest raw partial.
+	 */
+	pending: string;
+}
+
+const DEFAULT_AGREEMENT_COUNT = 2;
+
+/**
+ * Find the longest character prefix shared by both strings. Character-level
+ * (not word-level) so a partial that finished a word ("sa" → "sat") still
+ * shows agreement on the shared prefix "sa" and only "t" stays pending.
+ */
+function commonPrefixLength(a: string, b: string): number {
+	const n = Math.min(a.length, b.length);
+	let i = 0;
+	while (i < n && a.charCodeAt(i) === b.charCodeAt(i)) i++;
+	return i;
+}
+
+export class PartialStabilizer {
+	private readonly agreementCount: number;
+	/**
+	 * The most recent partials, oldest first. We only need the last
+	 * `agreementCount` entries — the agreed prefix is the intersection of
+	 * all of them. Length 0 before any feed.
+	 */
+	private history: string[] = [];
+	/** The longest committed stable prefix so far. Monotonically grows. */
+	private committed = "";
+
+	constructor(options: PartialStabilizerOptions = {}) {
+		const requested = options.agreementCount ?? DEFAULT_AGREEMENT_COUNT;
+		if (!Number.isFinite(requested) || requested < 1) {
+			throw new Error(
+				`[partial-stabilizer] agreementCount must be a finite integer >= 1; got ${String(requested)}`,
+			);
+		}
+		this.agreementCount = Math.floor(requested);
+	}
+
+	/**
+	 * Feed the latest streaming-ASR partial. Returns the stable / pending
+	 * split. The stable prefix is monotonically non-decreasing across calls
+	 * — once a span has been agreed `n` times it stays committed even if a
+	 * later partial briefly disagrees (the ASR will catch up; rolling back
+	 * would cause downstream stutter).
+	 */
+	feed(partial: string): StabilizerOutput {
+		this.history.push(partial);
+		if (this.history.length > this.agreementCount) {
+			this.history.shift();
+		}
+		if (this.history.length < this.agreementCount) {
+			// Not enough partials yet to confirm anything new — only the
+			// already-committed prefix is stable.
+			return {
+				stable: this.committed,
+				pending: partial.startsWith(this.committed)
+					? partial.slice(this.committed.length)
+					: partial,
+			};
+		}
+		// Intersect: agreed prefix = common prefix across the whole agreement
+		// window.
+		let agreed = this.history[0];
+		for (let i = 1; i < this.history.length; i++) {
+			const sharedLen = commonPrefixLength(agreed, this.history[i]);
+			if (sharedLen < agreed.length) {
+				agreed = agreed.slice(0, sharedLen);
+			}
+			if (agreed.length === 0) break;
+		}
+		if (agreed.length > this.committed.length) {
+			this.committed = agreed;
+		}
+		return {
+			stable: this.committed,
+			pending: partial.startsWith(this.committed)
+				? partial.slice(this.committed.length)
+				: partial,
+		};
+	}
+
+	/** The current committed stable prefix (read-only view). */
+	stable(): string {
+		return this.committed;
+	}
+
+	/** Clear all history. Call at utterance boundaries. */
+	reset(): void {
+		this.history = [];
+		this.committed = "";
+	}
+}

package/src/services/voice/phoneme-tokenizer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Phoneme tokenizer interface used by the IPA-mode phrase chunker.
+ *
+ * The chunker consumes a stream of accepted text tokens and re-emits them
+ * as sub-phrase chunks at phoneme boundaries. This lets TTS start
+ * synthesizing partial phrases earlier than the punctuation-only mode, at
+ * the cost of slightly less prosody coherence per chunk.
+ *
+ * The default tokenizer is synchronous because the chunker runs in the
+ * accepted-token hot path. Full espeak-ng / phonemizer integrations can
+ * implement this interface by resolving their native or package dependency
+ * before constructing the scheduler.
+ */
+export interface Phoneme {
+    /** IPA symbol(s) for this phoneme. */
+    ipa: string;
+    /** Index of the source `TextToken` this phoneme came from. Used by the
+     *  chunker to map sub-phrases back to token-index ranges so that the
+     *  rollback queue can still drop the right audio on a verifier reject. */
+    sourceTokenIndex: number;
+}
+export interface PhonemeTokenizer {
+    /** Stable tokenizer name, used for logging and cache keys. */
+    readonly name: string;
+    /** Relative quality signal for telemetry and debugging. */
+    readonly quality: "ipa" | "approximate";
+    /**
+     * Tokenize a single text token's text into phonemes. The chunker calls
+     * this once per accepted token; the tokenizer returns the phonemes for
+     * that token only. Returning an empty array is legal (e.g. whitespace
+     * tokens) and is treated as "no phoneme boundary added by this token".
+     */
+    tokenize(text: string, sourceTokenIndex: number): readonly Phoneme[];
+}
+/**
+ * Synchronous English IPA approximation for phrase chunking.
+ *
+ * This is not a pronunciation dictionary; it is a deterministic tokenizer
+ * whose output is close enough for boundary counting and rollback range
+ * mapping. Deployments that need accent-accurate phonemization can inject a
+ * higher-quality `PhonemeTokenizer` built around espeak-ng or phonemizer.
+ */
+export declare class RuleBasedEnglishPhonemeTokenizer implements PhonemeTokenizer {
+    readonly name = "RuleBasedEnglishPhonemeTokenizer";
+    readonly quality: "approximate";
+    tokenize(text: string, sourceTokenIndex: number): readonly Phoneme[];
+}
+export declare function createDefaultPhonemeTokenizer(): PhonemeTokenizer;
+//# sourceMappingURL=phoneme-tokenizer.d.ts.map

package/src/services/voice/phoneme-tokenizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phoneme-tokenizer.d.ts","sourceRoot":"","sources":["phoneme-tokenizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,OAAO;IACvB,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ;;8EAE0E;IAC1E,gBAAgB,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,KAAK,GAAG,aAAa,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE,CAAC;CACrE;AA2FD;;;;;;;GAOG;AACH,qBAAa,gCAAiC,YAAW,gBAAgB;IACxE,QAAQ,CAAC,IAAI,sCAAsC;IACnD,QAAQ,CAAC,OAAO,EAAG,aAAa,CAAU;IAE1C,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE;CAepE;AAED,wBAAgB,6BAA6B,IAAI,gBAAgB,CAEhE"}

package/src/services/voice/phoneme-tokenizer.ts

@@ -0,0 +1,158 @@
+/**
+ * Phoneme tokenizer interface used by the IPA-mode phrase chunker.
+ *
+ * The chunker consumes a stream of accepted text tokens and re-emits them
+ * as sub-phrase chunks at phoneme boundaries. This lets TTS start
+ * synthesizing partial phrases earlier than the punctuation-only mode, at
+ * the cost of slightly less prosody coherence per chunk.
+ *
+ * The default tokenizer is synchronous because the chunker runs in the
+ * accepted-token hot path. Full espeak-ng / phonemizer integrations can
+ * implement this interface by resolving their native or package dependency
+ * before constructing the scheduler.
+ */
+
+export interface Phoneme {
+	/** IPA symbol(s) for this phoneme. */
+	ipa: string;
+	/** Index of the source `TextToken` this phoneme came from. Used by the
+	 *  chunker to map sub-phrases back to token-index ranges so that the
+	 *  rollback queue can still drop the right audio on a verifier reject. */
+	sourceTokenIndex: number;
+}
+
+export interface PhonemeTokenizer {
+	/** Stable tokenizer name, used for logging and cache keys. */
+	readonly name: string;
+	/** Relative quality signal for telemetry and debugging. */
+	readonly quality: "ipa" | "approximate";
+	/**
+	 * Tokenize a single text token's text into phonemes. The chunker calls
+	 * this once per accepted token; the tokenizer returns the phonemes for
+	 * that token only. Returning an empty array is legal (e.g. whitespace
+	 * tokens) and is treated as "no phoneme boundary added by this token".
+	 */
+	tokenize(text: string, sourceTokenIndex: number): readonly Phoneme[];
+}
+
+const WORD_IPA: Readonly<Record<string, readonly string[]>> = {
+	a: ["ə"],
+	an: ["æ", "n"],
+	and: ["æ", "n", "d"],
+	are: ["ɑː", "r"],
+	be: ["b", "iː"],
+	eliza: ["ə", "l", "iː", "z", "ə"],
+	hello: ["h", "ə", "l", "oʊ"],
+	is: ["ɪ", "z"],
+	of: ["ʌ", "v"],
+	the: ["ð", "ə"],
+	to: ["t", "uː"],
+	world: ["w", "ɜː", "r", "l", "d"],
+};
+
+const DIGRAPH_IPA: Readonly<Record<string, string>> = {
+	ch: "tʃ",
+	ck: "k",
+	ng: "ŋ",
+	ph: "f",
+	qu: "kʷ",
+	sh: "ʃ",
+	th: "θ",
+	wh: "w",
+};
+
+const LETTER_IPA: Readonly<Record<string, string>> = {
+	a: "æ",
+	b: "b",
+	c: "k",
+	d: "d",
+	e: "ɛ",
+	f: "f",
+	g: "ɡ",
+	h: "h",
+	i: "ɪ",
+	j: "dʒ",
+	k: "k",
+	l: "l",
+	m: "m",
+	n: "n",
+	o: "ɑ",
+	p: "p",
+	q: "k",
+	r: "r",
+	s: "s",
+	t: "t",
+	u: "ʌ",
+	v: "v",
+	w: "w",
+	x: "k",
+	y: "j",
+	z: "z",
+};
+
+const DIGIT_IPA: Readonly<Record<string, readonly string[]>> = {
+	"0": ["z", "iː", "r", "oʊ"],
+	"1": ["w", "ʌ", "n"],
+	"2": ["t", "uː"],
+	"3": ["θ", "r", "iː"],
+	"4": ["f", "ɔː", "r"],
+	"5": ["f", "aɪ", "v"],
+	"6": ["s", "ɪ", "k", "s"],
+	"7": ["s", "ɛ", "v", "ə", "n"],
+	"8": ["eɪ", "t"],
+	"9": ["n", "aɪ", "n"],
+};
+
+function ipaForWord(word: string): readonly string[] {
+	const known = WORD_IPA[word];
+	if (known) return known;
+
+	const out: string[] = [];
+	for (let i = 0; i < word.length; ) {
+		const pair = word.slice(i, i + 2);
+		const digraph = DIGRAPH_IPA[pair];
+		if (digraph) {
+			out.push(digraph);
+			i += 2;
+			continue;
+		}
+
+		const mapped = LETTER_IPA[word[i]];
+		if (mapped) out.push(mapped);
+		i += 1;
+	}
+	return out;
+}
+
+/**
+ * Synchronous English IPA approximation for phrase chunking.
+ *
+ * This is not a pronunciation dictionary; it is a deterministic tokenizer
+ * whose output is close enough for boundary counting and rollback range
+ * mapping. Deployments that need accent-accurate phonemization can inject a
+ * higher-quality `PhonemeTokenizer` built around espeak-ng or phonemizer.
+ */
+export class RuleBasedEnglishPhonemeTokenizer implements PhonemeTokenizer {
+	readonly name = "RuleBasedEnglishPhonemeTokenizer";
+	readonly quality = "approximate" as const;
+
+	tokenize(text: string, sourceTokenIndex: number): readonly Phoneme[] {
+		const out: Phoneme[] = [];
+		const pieces = text.match(/[A-Za-z]+|\d/g) ?? [];
+
+		for (const piece of pieces) {
+			const phonemes = /^\d$/.test(piece)
+				? (DIGIT_IPA[piece] ?? [])
+				: ipaForWord(piece.toLowerCase());
+			for (const ipa of phonemes) {
+				out.push({ ipa, sourceTokenIndex });
+			}
+		}
+
+		return out;
+	}
+}
+
+export function createDefaultPhonemeTokenizer(): PhonemeTokenizer {
+	return new RuleBasedEnglishPhonemeTokenizer();
+}

package/src/services/voice/phrase-cache.d.ts

@@ -0,0 +1,76 @@
+export interface CachedPhraseAudio {
+    text: string;
+    pcm: Float32Array;
+    sampleRate: number;
+}
+/**
+ * Canonical seed list for the voice phrase cache: short openers, fillers, and
+ * acknowledgements the assistant emits constantly. Pre-synthesizing these and
+ * holding their PCM in `PhraseCache` removes the TTS forward pass from the
+ * critical path for the most common first utterances — `dispatchPhrase` hits
+ * the cache and writes audio to the ring buffer on the same tick.
+ *
+ * Used by:
+ *   - the preset generator (`scripts/voice-preset/build-default-voice-preset.mjs`),
+ *     which synthesizes these against a real OmniVoice TTS backend and writes
+ *     the PCM into `cache/voice-preset-default.bin` — the seeded source of truth.
+ *   - `EngineVoiceBridge.start()` indirectly: the bundle's preset ships these
+ *     phrases with their PCM, which `PhraseCache.seed(...)` loads at startup.
+ *   - the idle-time auto-prewarm hook (`EngineVoiceBridge.prewarmIdlePhrases`),
+ *     which only runs when a real TTS backend is present — never against the
+ *     silent backend (caching zeros is not a phrase cache).
+ *   - the first-audio filler (`FIRST_AUDIO_FILLERS` is a subset).
+ *
+ * Entries are kept here in canonical form (lowercase, single-spaced, trimmed)
+ * so the preset generator and the runtime agree byte-for-byte on the keys.
+ */
+export declare const DEFAULT_PHRASE_CACHE_SEED: ReadonlyArray<string>;
+/**
+ * The subset of `DEFAULT_PHRASE_CACHE_SEED` suitable to play the instant VAD
+ * fires `speech-start`, masking first-token latency (AGENTS.md §4 / H4). Kept
+ * short and uncommitted — anything that takes a stance ("of course") is
+ * excluded so the filler never contradicts the eventual reply. The first
+ * entry found in the phrase cache wins.
+ */
+export declare const FIRST_AUDIO_FILLERS: ReadonlyArray<string>;
+export interface PhraseCacheOptions {
+    /** Maximum distinct phrase texts retained. Older non-accessed entries
+     * are evicted first. */
+    maxEntries?: number;
+    /**
+     * Opportunistic live-cache guardrail. Voice mode primarily benefits from
+     * cached acknowledgements and first sentence fragments; longer text is less
+     * likely to repeat and can evict useful hot phrases.
+     */
+    maxEstimatedTokensPerEntry?: number;
+    /**
+     * Guardrail for live opportunistic caching. Long-form direct TTS can be
+     * megabytes of PCM and is not a good phrase-cache resident.
+     */
+    maxPcmSamplesPerEntry?: number;
+}
+export declare function canonicalizePhraseText(text: string): string;
+export declare function estimatePhraseTokenCount(text: string): number;
+export declare class PhraseCache {
+    private readonly entries;
+    private readonly maxEntries;
+    private readonly maxEstimatedTokensPerEntry;
+    private readonly maxPcmSamplesPerEntry;
+    constructor(opts?: PhraseCacheOptions);
+    put(entry: CachedPhraseAudio): boolean;
+    /**
+     * Pre-populate the cache from a voice-preset seed list. Texts are stored
+     * verbatim — callers (the format reader) are responsible for canonicalizing
+     * before serialization, but we re-canonicalize on insert to be safe.
+     */
+    seed(entries: ReadonlyArray<{
+        text: string;
+        pcm: Float32Array;
+        sampleRate: number;
+    }>): void;
+    get(text: string): CachedPhraseAudio | undefined;
+    has(text: string): boolean;
+    size(): number;
+    private evictOverflow;
+}
+//# sourceMappingURL=phrase-cache.d.ts.map

package/src/services/voice/phrase-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phrase-cache.d.ts","sourceRoot":"","sources":["phrase-cache.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,YAAY,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,yBAAyB,EAAE,aAAa,CAAC,MAAM,CAwB3D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,aAAa,CAAC,MAAM,CAMrD,CAAC;AAEF,MAAM,WAAW,kBAAkB;IAClC;4BACwB;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI7D;AAMD,qBAAa,WAAW;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;IAChE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAS;IACpD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAS;gBAEnC,IAAI,GAAE,kBAAuB;IAoBzC,GAAG,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO;IAetC;;;;OAIG;IACH,IAAI,CACH,OAAO,EAAE,aAAa,CAAC;QACtB,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,YAAY,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;KACnB,CAAC,GACA,IAAI;IAUP,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAShD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,IAAI,IAAI,MAAM;IAId,OAAO,CAAC,aAAa;CAOrB"}