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

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

@@ -0,0 +1,186 @@
+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 const DEFAULT_PHRASE_CACHE_SEED: ReadonlyArray<string> = [
+	// Immediate acknowledgements — "I heard you, working on it".
+	"okay",
+	"got it",
+	"sure",
+	"right",
+	"on it",
+	"one sec",
+	"one second",
+	"let me check",
+	"let me see",
+	"give me a moment",
+	// Conversational openers / fillers — natural sentence starters the planner
+	// emits before the substantive answer streams in.
+	"okay so",
+	"so",
+	"hmm",
+	"well",
+	"alright",
+	"sure thing",
+	"of course",
+	"no problem",
+	"good question",
+	"let me think",
+];
+
+/**
+ * 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 const FIRST_AUDIO_FILLERS: ReadonlyArray<string> = [
+	"one sec",
+	"okay",
+	"let me check",
+	"hmm",
+	"got it",
+];
+
+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 function canonicalizePhraseText(text: string): string {
+	return text.trim().toLowerCase().replace(/\s+/g, " ");
+}
+
+export function estimatePhraseTokenCount(text: string): number {
+	const normalized = canonicalizePhraseText(text);
+	if (!normalized) return 0;
+	return normalized.split(/\s+/).length;
+}
+
+const DEFAULT_MAX_ENTRIES = 128;
+const DEFAULT_MAX_ESTIMATED_TOKENS_PER_ENTRY = 9;
+const DEFAULT_MAX_PCM_SAMPLES_PER_ENTRY = 24000 * 8;
+
+export class PhraseCache {
+	private readonly entries = new Map<string, CachedPhraseAudio>();
+	private readonly maxEntries: number;
+	private readonly maxEstimatedTokensPerEntry: number;
+	private readonly maxPcmSamplesPerEntry: number;
+
+	constructor(opts: PhraseCacheOptions = {}) {
+		this.maxEntries = Math.max(
+			1,
+			Math.floor(opts.maxEntries ?? DEFAULT_MAX_ENTRIES),
+		);
+		this.maxEstimatedTokensPerEntry = Math.max(
+			1,
+			Math.floor(
+				opts.maxEstimatedTokensPerEntry ??
+					DEFAULT_MAX_ESTIMATED_TOKENS_PER_ENTRY,
+			),
+		);
+		this.maxPcmSamplesPerEntry = Math.max(
+			1,
+			Math.floor(
+				opts.maxPcmSamplesPerEntry ?? DEFAULT_MAX_PCM_SAMPLES_PER_ENTRY,
+			),
+		);
+	}
+
+	put(entry: CachedPhraseAudio): boolean {
+		const key = canonicalizePhraseText(entry.text);
+		if (!key) return false;
+		if (entry.pcm.length > this.maxPcmSamplesPerEntry) return false;
+		if (
+			estimatePhraseTokenCount(entry.text) > this.maxEstimatedTokensPerEntry
+		) {
+			return false;
+		}
+		this.entries.delete(key);
+		this.entries.set(key, entry);
+		this.evictOverflow();
+		return true;
+	}
+
+	/**
+	 * 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 {
+		for (const e of entries) {
+			this.put({
+				text: e.text,
+				pcm: e.pcm,
+				sampleRate: e.sampleRate,
+			});
+		}
+	}
+
+	get(text: string): CachedPhraseAudio | undefined {
+		const key = canonicalizePhraseText(text);
+		const entry = this.entries.get(key);
+		if (!entry) return undefined;
+		this.entries.delete(key);
+		this.entries.set(key, entry);
+		return entry;
+	}
+
+	has(text: string): boolean {
+		return this.entries.has(canonicalizePhraseText(text));
+	}
+
+	size(): number {
+		return this.entries.size;
+	}
+
+	private evictOverflow(): void {
+		while (this.entries.size > this.maxEntries) {
+			const oldest = this.entries.keys().next().value;
+			if (oldest === undefined) return;
+			this.entries.delete(oldest);
+		}
+	}
+}

package/src/services/voice/phrase-chunker.test.ts

@@ -0,0 +1,239 @@
+import { describe, expect, it } from "vitest";
+import { type ClockMs, chunkTokens, PhraseChunker } from "./phrase-chunker";
+import type { TextToken } from "./types";
+
+function tokens(parts: string[]): TextToken[] {
+	return parts.map((text, index) => ({ index, text }));
+}
+
+describe("PhraseChunker punctuation boundaries", () => {
+	it("flushes on semicolon and colon boundaries for faster first audio", () => {
+		const phrases = chunkTokens(tokens(["First:", " second;", " third"]), {});
+
+		expect(phrases.map((phrase) => phrase.text)).toEqual([
+			"First:",
+			" second;",
+			" third",
+		]);
+		expect(phrases.map((phrase) => phrase.terminator)).toEqual([
+			"punctuation",
+			"punctuation",
+			"max-cap",
+		]);
+	});
+});
+
+describe("PhraseChunker T3 time-budget flush", () => {
+	it("force-flushes once the time budget elapses on a slow producer", () => {
+		let now = 0;
+		const clock: ClockMs = () => now;
+		const chunker = new PhraseChunker(
+			// Pin first-phrase budget == full budget so these mechanism tests
+			// exercise the uniform 200ms path (first-phrase shortening is
+			// covered separately below).
+			{
+				maxAccumulationMs: 200,
+				firstPhraseMaxAccumulationMs: 200,
+				maxTokensPerPhrase: 100,
+			},
+			null,
+			clock,
+		);
+
+		expect(chunker.push({ index: 0, text: "hello", acceptedAt: 0 })).toBeNull();
+		now = 100;
+		expect(
+			chunker.push({ index: 1, text: " there", acceptedAt: 0 }),
+		).toBeNull();
+		now = 220;
+		const flushed = chunker.push({ index: 2, text: " friend", acceptedAt: 0 });
+		expect(flushed).not.toBeNull();
+		expect(flushed?.text).toBe("hello there friend");
+		expect(flushed?.terminator).toBe("max-cap");
+	});
+
+	it("does not flush before the budget elapses", () => {
+		let now = 0;
+		const clock: ClockMs = () => now;
+		const chunker = new PhraseChunker(
+			// Pin first-phrase budget == full budget so these mechanism tests
+			// exercise the uniform 200ms path (first-phrase shortening is
+			// covered separately below).
+			{
+				maxAccumulationMs: 200,
+				firstPhraseMaxAccumulationMs: 200,
+				maxTokensPerPhrase: 100,
+			},
+			null,
+			clock,
+		);
+		expect(chunker.push({ index: 0, text: "a", acceptedAt: 0 })).toBeNull();
+		now = 50;
+		expect(chunker.push({ index: 1, text: "b", acceptedAt: 0 })).toBeNull();
+		now = 150;
+		expect(chunker.push({ index: 2, text: "c", acceptedAt: 0 })).toBeNull();
+	});
+
+	it("flushIfTimeBudgetExceeded triggers on caller poll without a new token", () => {
+		let now = 0;
+		const clock: ClockMs = () => now;
+		const chunker = new PhraseChunker(
+			// Pin first-phrase budget == full budget so these mechanism tests
+			// exercise the uniform 200ms path (first-phrase shortening is
+			// covered separately below).
+			{
+				maxAccumulationMs: 200,
+				firstPhraseMaxAccumulationMs: 200,
+				maxTokensPerPhrase: 100,
+			},
+			null,
+			clock,
+		);
+		chunker.push({ index: 0, text: "x", acceptedAt: 0 });
+		now = 100;
+		expect(chunker.flushIfTimeBudgetExceeded()).toBeNull();
+		now = 250;
+		const phrase = chunker.flushIfTimeBudgetExceeded();
+		expect(phrase?.text).toBe("x");
+		expect(phrase?.terminator).toBe("max-cap");
+		expect(chunker.flushIfTimeBudgetExceeded()).toBeNull();
+	});
+
+	it("msUntilTimeBudget reports infinity for an empty buffer or disabled budget", () => {
+		let now = 0;
+		const clock: ClockMs = () => now;
+		const chunker = new PhraseChunker(
+			// Pin first-phrase budget == full budget so these mechanism tests
+			// exercise the uniform 200ms path (first-phrase shortening is
+			// covered separately below).
+			{
+				maxAccumulationMs: 200,
+				firstPhraseMaxAccumulationMs: 200,
+				maxTokensPerPhrase: 100,
+			},
+			null,
+			clock,
+		);
+		expect(chunker.msUntilTimeBudget()).toBe(Number.POSITIVE_INFINITY);
+		chunker.push({ index: 0, text: "x", acceptedAt: 0 });
+		expect(chunker.msUntilTimeBudget()).toBe(200);
+		now = 75;
+		expect(chunker.msUntilTimeBudget()).toBe(125);
+
+		const disabled = new PhraseChunker(
+			{ maxAccumulationMs: 0, maxTokensPerPhrase: 100 },
+			null,
+			clock,
+		);
+		disabled.push({ index: 0, text: "x", acceptedAt: 0 });
+		expect(disabled.msUntilTimeBudget()).toBe(Number.POSITIVE_INFINITY);
+	});
+
+	it("disabled budget never time-flushes", () => {
+		let now = 0;
+		const clock: ClockMs = () => now;
+		const chunker = new PhraseChunker(
+			{ maxAccumulationMs: 0, maxTokensPerPhrase: 100 },
+			null,
+			clock,
+		);
+		chunker.push({ index: 0, text: "a", acceptedAt: 0 });
+		now = 10_000;
+		expect(chunker.push({ index: 1, text: " b", acceptedAt: 0 })).toBeNull();
+		expect(chunker.flushIfTimeBudgetExceeded()).toBeNull();
+	});
+});
+
+describe("PhraseChunker first-phrase budget (TTFA)", () => {
+	it("flushes the first phrase on the shorter budget, later phrases on the full one", () => {
+		let now = 0;
+		const clock: ClockMs = () => now;
+		const chunker = new PhraseChunker(
+			{
+				maxAccumulationMs: 700,
+				firstPhraseMaxAccumulationMs: 300,
+				maxTokensPerPhrase: 100,
+			},
+			null,
+			clock,
+		);
+		// First phrase: silent producer, no punctuation — flushes at 300ms.
+		expect(chunker.push({ index: 0, text: "hello", acceptedAt: 0 })).toBeNull();
+		expect(chunker.msUntilTimeBudget()).toBe(300);
+		now = 300;
+		const first = chunker.flushIfTimeBudgetExceeded();
+		expect(first?.text).toBe("hello");
+		expect(first?.terminator).toBe("max-cap");
+
+		// Second phrase now uses the FULL 700ms budget (no fragmentation).
+		now = 1000;
+		expect(
+			chunker.push({ index: 1, text: " there", acceptedAt: 0 }),
+		).toBeNull();
+		expect(chunker.msUntilTimeBudget()).toBe(700);
+		now = 1300; // 300ms in — would have flushed the first phrase, not this one
+		expect(chunker.flushIfTimeBudgetExceeded()).toBeNull();
+		now = 1700; // full 700ms elapsed
+		expect(chunker.flushIfTimeBudgetExceeded()?.text).toBe(" there");
+	});
+
+	it("derives the first-phrase budget from maxAccumulationMs when unset (half, capped 350)", () => {
+		const now = 0;
+		const clock: ClockMs = () => now;
+		// 700ms full → first-phrase budget = min(350, 350) = 350.
+		const chunker = new PhraseChunker(
+			{ maxAccumulationMs: 700, maxTokensPerPhrase: 100 },
+			null,
+			clock,
+		);
+		chunker.push({ index: 0, text: "x", acceptedAt: 0 });
+		expect(chunker.msUntilTimeBudget()).toBe(350);
+
+		// 400ms full → half = 200 (below the 350 cap).
+		const small = new PhraseChunker(
+			{ maxAccumulationMs: 400, maxTokensPerPhrase: 100 },
+			null,
+			clock,
+		);
+		small.push({ index: 0, text: "x", acceptedAt: 0 });
+		expect(small.msUntilTimeBudget()).toBe(200);
+	});
+
+	it("resets the first-phrase gate on reset() so each reply gets fast first audio", () => {
+		let now = 0;
+		const clock: ClockMs = () => now;
+		const chunker = new PhraseChunker(
+			{
+				maxAccumulationMs: 700,
+				firstPhraseMaxAccumulationMs: 300,
+				maxTokensPerPhrase: 100,
+			},
+			null,
+			clock,
+		);
+		chunker.push({ index: 0, text: "first", acceptedAt: 0 });
+		now = 300;
+		expect(chunker.flushIfTimeBudgetExceeded()).not.toBeNull(); // phrase #1 flushed
+		chunker.reset();
+		now = 1000;
+		chunker.push({ index: 0, text: "again", acceptedAt: 0 });
+		// Back to the short first-phrase budget after reset.
+		expect(chunker.msUntilTimeBudget()).toBe(300);
+	});
+
+	it("clamps an explicit first-phrase budget to the full budget", () => {
+		const now = 0;
+		const clock: ClockMs = () => now;
+		const chunker = new PhraseChunker(
+			{
+				maxAccumulationMs: 200,
+				firstPhraseMaxAccumulationMs: 999,
+				maxTokensPerPhrase: 100,
+			},
+			null,
+			clock,
+		);
+		chunker.push({ index: 0, text: "x", acceptedAt: 0 });
+		expect(chunker.msUntilTimeBudget()).toBe(200);
+	});
+});

package/src/services/voice/phrase-chunker.ts

@@ -0,0 +1,281 @@
+import type { PhonemeTokenizer } from "./phoneme-tokenizer";
+import type {
+	AcceptedToken,
+	Phrase,
+	PhraseChunkerConfig,
+	TextToken,
+} from "./types";
+
+/**
+ * Default phrase boundaries: end-of-clause punctuation plus the three
+ * sentence-final marks. Per `packages/inference/AGENTS.md` §4 / the
+ * voice-swarm brief item A6 — "the first segment delimited by punctuation
+ * OR the first 30 words, whichever comes first". Cutting a phrase at the
+ * first comma/semicolon/colon hands TTS something to say without waiting
+ * for a sentence-final mark.
+ */
+const DEFAULT_TERMINATORS: ReadonlySet<string> = new Set([
+	",",
+	".",
+	"!",
+	"?",
+	";",
+	":",
+]);
+const DEFAULT_PHONEMES_PER_CHUNK = 8;
+/** Default hard word cap when a caller doesn't supply `maxTokensPerPhrase` (the brief's "first 30 words"). */
+const DEFAULT_MAX_TOKENS_PER_PHRASE = 30;
+/**
+ * T3 — default time budget in milliseconds for the time-budget phrase
+ * flush. When a phrase has been accumulating in the buffer for this long
+ * without hitting a punctuation / phoneme / cap boundary, force a flush
+ * so the next phrase reaches TTS instead of stalling behind a slow
+ * producer. Override via `ELIZA_PHRASE_FLUSH_MS` env var.
+ *
+ * The default is deliberately phrase-sized. A 200ms budget was fast on paper
+ * but split slow token streams into word fragments, which made OmniVoice
+ * produce filler-like audio and degraded the downstream ASR loop.
+ */
+function resolveDefaultMaxAccumulationMs(): number {
+	const raw = process.env.ELIZA_PHRASE_FLUSH_MS?.trim();
+	if (raw) {
+		const v = Number.parseInt(raw, 10);
+		if (Number.isFinite(v) && v > 0) return v;
+	}
+	return 700;
+}
+const DEFAULT_MAX_ACCUMULATION_MS = resolveDefaultMaxAccumulationMs();
+
+/**
+ * First-audio (TTFA) optimization: the FIRST phrase of a reply uses a shorter
+ * time budget than the rest. First-audio latency is the dominant voice-UX
+ * metric, and a punctuation-sparse opening otherwise waits the full
+ * {@link DEFAULT_MAX_ACCUMULATION_MS} before any sound plays. Once audio is
+ * flowing, later phrases keep the full budget so the bulk of the reply is not
+ * fragmented into word-sized chunks (the failure mode the 700ms default fixed).
+ * Override via `ELIZA_PHRASE_FLUSH_FIRST_MS`; defaults to half the full budget,
+ * capped at 350ms. A non-positive full budget disables both.
+ */
+function resolveFirstPhraseMs(fullBudgetMs: number): number {
+	if (fullBudgetMs <= 0) return 0;
+	const raw = process.env.ELIZA_PHRASE_FLUSH_FIRST_MS?.trim();
+	if (raw) {
+		const v = Number.parseInt(raw, 10);
+		if (Number.isFinite(v) && v > 0) return Math.min(v, fullBudgetMs);
+	}
+	return Math.min(350, Math.ceil(fullBudgetMs / 2));
+}
+
+/** Wall-clock source the chunker uses. Tests inject a deterministic clock. */
+export type ClockMs = () => number;
+
+const DEFAULT_CLOCK: ClockMs = () => globalThis.performance.now();
+
+export class PhraseChunker {
+	private buffer: AcceptedToken[] = [];
+	private nextPhraseId = 0;
+	private readonly terminators: ReadonlySet<string>;
+	private readonly chunkOn: "punctuation" | "phoneme-stream";
+	private readonly phonemesPerChunk: number;
+	private readonly maxTokensPerPhrase: number;
+	private readonly tokenizer: PhonemeTokenizer | null;
+	private phonemeCount = 0;
+	/**
+	 * T3 — time-budget flush. `firstTokenAtMs` is captured on the first
+	 * `push()` after an empty buffer; once `clock() - firstTokenAtMs >=
+	 * maxAccumulationMs` the chunker force-flushes even without a
+	 * punctuation / phoneme / cap boundary. `maxAccumulationMs <= 0`
+	 * disables the time budget.
+	 */
+	private readonly maxAccumulationMs: number;
+	/** Shorter budget applied only while no phrase has flushed yet this reply. */
+	private readonly firstPhraseMaxAccumulationMs: number;
+	private readonly clock: ClockMs;
+	private firstTokenAtMs = 0;
+	/** Phrases emitted since the last {@link reset}; gates the first-phrase budget. */
+	private phrasesEmitted = 0;
+
+	constructor(
+		config: PhraseChunkerConfig,
+		tokenizer: PhonemeTokenizer | null = null,
+		clock: ClockMs = DEFAULT_CLOCK,
+	) {
+		this.terminators = config.sentenceTerminators ?? DEFAULT_TERMINATORS;
+		this.chunkOn = config.chunkOn ?? "punctuation";
+		this.phonemesPerChunk = Math.max(
+			1,
+			config.phonemesPerChunk ?? DEFAULT_PHONEMES_PER_CHUNK,
+		);
+		this.maxTokensPerPhrase = Math.max(
+			1,
+			config.maxTokensPerPhrase ?? DEFAULT_MAX_TOKENS_PER_PHRASE,
+		);
+		this.maxAccumulationMs =
+			config.maxAccumulationMs !== undefined
+				? Math.max(0, config.maxAccumulationMs)
+				: DEFAULT_MAX_ACCUMULATION_MS;
+		this.firstPhraseMaxAccumulationMs =
+			config.firstPhraseMaxAccumulationMs !== undefined
+				? Math.min(
+						this.maxAccumulationMs,
+						Math.max(0, config.firstPhraseMaxAccumulationMs),
+					)
+				: resolveFirstPhraseMs(this.maxAccumulationMs);
+		this.clock = clock;
+		this.tokenizer = tokenizer;
+		if (this.chunkOn === "phoneme-stream" && this.tokenizer === null) {
+			throw new Error(
+				"PhraseChunker: chunkOn='phoneme-stream' requires a PhonemeTokenizer",
+			);
+		}
+	}
+
+	push(token: AcceptedToken): Phrase | null {
+		if (this.buffer.length === 0) {
+			this.firstTokenAtMs = this.clock();
+		}
+		this.buffer.push(token);
+
+		// Punctuation always wins — a `, . ! ?` boundary forces a flush even
+		// in phoneme-stream mode.
+		if (this.endsWithTerminator(token.text)) {
+			return this.flushAs("punctuation");
+		}
+
+		if (this.chunkOn === "phoneme-stream" && this.tokenizer !== null) {
+			const phonemes = this.tokenizer.tokenize(token.text, token.index);
+			this.phonemeCount += phonemes.length;
+			if (this.phonemeCount >= this.phonemesPerChunk) {
+				return this.flushAs("phoneme-stream");
+			}
+		}
+
+		if (this.buffer.length >= this.maxTokensPerPhrase) {
+			return this.flushAs("max-cap");
+		}
+
+		// T3 — time-budget flush. Re-uses the `"max-cap"` terminator because
+		// adding a new terminator value would require editing the shared
+		// `Phrase` type in `types.ts`. Structurally "the chunker forced a
+		// flush" is what max-cap already means.
+		const budget = this.currentBudgetMs();
+		if (budget > 0 && this.clock() - this.firstTokenAtMs >= budget) {
+			return this.flushAs("max-cap");
+		}
+		return null;
+	}
+
+	/** Active time budget: the shorter first-phrase budget until the reply's
+	 * first phrase has flushed, then the full budget. */
+	private currentBudgetMs(): number {
+		return this.phrasesEmitted === 0
+			? this.firstPhraseMaxAccumulationMs
+			: this.maxAccumulationMs;
+	}
+
+	/**
+	 * T3 — caller-driven check. Returns a phrase when the time budget has
+	 * elapsed for the current buffer, otherwise null. The scheduler polls
+	 * this from a `setTimeout` so even a producer that goes silent before
+	 * pushing the next token still gets its in-flight phrase flushed.
+	 */
+	flushIfTimeBudgetExceeded(): Phrase | null {
+		if (this.buffer.length === 0) return null;
+		const budget = this.currentBudgetMs();
+		if (budget <= 0) return null;
+		if (this.clock() - this.firstTokenAtMs < budget) {
+			return null;
+		}
+		return this.flushAs("max-cap");
+	}
+
+	/**
+	 * T3 — milliseconds remaining until the time budget elapses for the
+	 * current buffer. Negative when the budget has already been exceeded;
+	 * `Number.POSITIVE_INFINITY` when the buffer is empty or the budget is
+	 * disabled. Callers compute their flush timer off this.
+	 */
+	msUntilTimeBudget(): number {
+		if (this.buffer.length === 0) return Number.POSITIVE_INFINITY;
+		const budget = this.currentBudgetMs();
+		if (budget <= 0) return Number.POSITIVE_INFINITY;
+		return this.firstTokenAtMs + budget - this.clock();
+	}
+
+	flushPending(): Phrase | null {
+		if (this.buffer.length === 0) return null;
+		return this.flushAs("max-cap");
+	}
+
+	/**
+	 * Drop buffered tokens that have not flushed whose token index is ≥
+	 * `fromIndex`. Used by the pipeline's rollback path: when the target
+	 * verifier rejects a draft tail, any draft tokens still sitting in the
+	 * chunker's buffer before phrase packing MUST be discarded so
+	 * the verifier's correction does not get glued onto stale text.
+	 * Phonemes are recounted from scratch over what remains.
+	 */
+	dropPendingFrom(fromIndex: number): void {
+		const kept = this.buffer.filter((t) => t.index < fromIndex);
+		if (kept.length === this.buffer.length) return;
+		this.buffer = kept;
+		this.phonemeCount = 0;
+		if (this.buffer.length === 0) {
+			this.firstTokenAtMs = 0;
+		}
+		if (this.chunkOn === "phoneme-stream" && this.tokenizer !== null) {
+			for (const t of this.buffer) {
+				this.phonemeCount += this.tokenizer.tokenize(t.text, t.index).length;
+			}
+		}
+	}
+
+	reset(): void {
+		this.buffer = [];
+		this.phonemeCount = 0;
+		this.firstTokenAtMs = 0;
+		this.phrasesEmitted = 0;
+	}
+
+	private endsWithTerminator(text: string): boolean {
+		if (text.length === 0) return false;
+		const last = text[text.length - 1];
+		return this.terminators.has(last);
+	}
+
+	private flushAs(terminator: Phrase["terminator"]): Phrase {
+		const tokens = this.buffer;
+		this.buffer = [];
+		this.phonemeCount = 0;
+		this.firstTokenAtMs = 0;
+		this.phrasesEmitted++;
+		const fromIndex = tokens[0].index;
+		const toIndex = tokens[tokens.length - 1].index;
+		const text = tokens.map((t) => t.text).join("");
+		const phrase: Phrase = {
+			id: this.nextPhraseId++,
+			text,
+			fromIndex,
+			toIndex,
+			terminator,
+		};
+		return phrase;
+	}
+}
+
+export function chunkTokens(
+	tokens: TextToken[],
+	config: PhraseChunkerConfig,
+	acceptedAt = 0,
+	tokenizer: PhonemeTokenizer | null = null,
+): Phrase[] {
+	const chunker = new PhraseChunker(config, tokenizer);
+	const phrases: Phrase[] = [];
+	for (const t of tokens) {
+		const p = chunker.push({ ...t, acceptedAt });
+		if (p) phrases.push(p);
+	}
+	const tail = chunker.flushPending();
+	if (tail) phrases.push(tail);
+	return phrases;
+}