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

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

@@ -0,0 +1,109 @@
+/**
+ * Optimistic-generation policy — Wave 3 W3-9.
+ *
+ * Decides whether the LM should fire optimistically the moment the turn
+ * detector crosses the EOT threshold (before the audio buffer is fully
+ * drained), or wait for the full hangover. Per the user spec:
+ *
+ *   > "We want to optimize to start running and checking basically the
+ *    second there is no audio / voice detected, and then we start
+ *    optimistically processing, and if the user starts talking again we
+ *    kill and add to the conversation and start reprocessing."
+ *
+ * Default heuristic:
+ *   - Plugged-in (or power state unknown): optimistic = true.
+ *   - On battery: optimistic = false (the extra forward pass burns
+ *     joules every false-positive EOT).
+ *
+ * Callers (notably `VoiceStateMachine`) read `shouldStartOptimisticLm()`
+ * each time they consider firing the speculative drafter. The policy can be
+ * mutated at runtime via `setOptimisticOverride()` so a Settings UI toggle
+ * or a per-session env var can pin the value without restarting the engine.
+ */
+/** Power-source signal. `unknown` is treated as "plugged in" for the
+ *  default policy (a desktop without battery telemetry). */
+export type PowerSourceState = "plugged-in" | "battery" | "unknown";
+/**
+ * Resolve the current power-source state.
+ *
+ * Production callers (engine bridge) prime the optimistic policy with this
+ * once at session start. There is no canonical power-source accessor in
+ * `device-tier.ts` (the hardware probe records RAM / GPU / cores but no
+ * battery telemetry), so this resolver consults two cheap signals:
+ *
+ *   1. `ELIZA_VOICE_POWER_SOURCE` env var (`"plugged-in" | "battery" |
+ *      "unknown"`). Wins outright when set — operators / Settings can pin
+ *      the policy without restarting the engine.
+ *   2. Linux `/sys/class/power_supply` AC online status when available
+ *      synchronously. Returns `"plugged-in"` when any AC adapter reports
+ *      `online`, `"battery"` when only batteries are present and none
+ *      report online, `"unknown"` otherwise.
+ *
+ * macOS / Windows / mobile go through `"unknown"` here — the desktop probe
+ * surfaces those via the Electrobun side and Settings overrides it through
+ * (1). The default heuristic (`unknown → enabled`) treats those as
+ * plugged-in for the optimistic gate, which is the right default for
+ * desktop / dev (battery-aware mobile builds set the override explicitly).
+ */
+export declare function resolvePowerSourceState(): PowerSourceState;
+export interface OptimisticPolicyOptions {
+    /**
+     * Default value when no override is set. Resolved from the device tier
+     * at construction time (per the user spec: true on plugged-in,
+     * false on battery). Defaults to `true` when no power signal is given.
+     */
+    defaultEnabled?: boolean;
+    /**
+     * The threshold the turn detector's EOT probability must clear before
+     * the optimistic LM start fires. Mirrors `EOT_TENTATIVE_THRESHOLD`
+     * (the existing default) but is configurable per-policy so tier-aware
+     * deployments can tighten it on slower devices.
+     */
+    eotThreshold?: number;
+}
+export interface ResolveOptimisticPolicyArgs {
+    powerSource?: PowerSourceState;
+    /**
+     * Explicit override. When set, wins over both the default and the
+     * power-source heuristic. Sourced from `voice.optimisticGenerationOnEot`
+     * in user settings (Wave 3C).
+     */
+    override?: boolean;
+}
+export declare const DEFAULT_OPTIMISTIC_EOT_THRESHOLD = 0.6;
+/**
+ * Pure resolver. Takes the power source + an optional override and returns
+ * whether optimistic LM start should fire.
+ */
+export declare function resolveOptimisticPolicyEnabled(args: ResolveOptimisticPolicyArgs): boolean;
+/**
+ * Mutable runtime policy. The voice state machine asks
+ * `policy.shouldStartOptimisticLm(eotProb)` before firing the drafter.
+ *
+ * Reasoning for a class rather than a free function: at runtime we need
+ * the override + the power source to be hot-swappable from Settings or a
+ * device-event listener (battery state change) without re-plumbing the
+ * machine.
+ */
+export declare class OptimisticGenerationPolicy {
+    private overrideValue;
+    private powerSource;
+    private readonly defaultEnabled;
+    private readonly eotThreshold;
+    constructor(opts?: OptimisticPolicyOptions);
+    /** Update the power source (called by the device-tier observer). */
+    setPowerSource(state: PowerSourceState): void;
+    /** Set / clear the user override. */
+    setOverride(value: boolean | undefined): void;
+    /** Resolve "should we be optimistic right now?". */
+    enabled(): boolean;
+    /**
+     * Combined gate: the policy must be enabled AND the EOT probability
+     * must clear the policy's threshold. This is the canonical check the
+     * voice state machine calls before firing the drafter on a partial
+     * transcript.
+     */
+    shouldStartOptimisticLm(eotProb: number): boolean;
+    get threshold(): number;
+}
+//# sourceMappingURL=optimistic-policy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"optimistic-policy.d.ts","sourceRoot":"","sources":["../../../src/services/voice/optimistic-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;4DAC4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,IAAI,gBAAgB,CAyC1D;AAED,MAAM,WAAW,uBAAuB;IACvC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,2BAA2B;IAC3C,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,eAAO,MAAM,gCAAgC,MAAM,CAAC;AAEpD;;;GAGG;AACH,wBAAgB,8BAA8B,CAC7C,IAAI,EAAE,2BAA2B,GAC/B,OAAO,CAMT;AAED;;;;;;;;GAQG;AACH,qBAAa,0BAA0B;IACtC,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,WAAW,CAAmB;IACtC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,IAAI,GAAE,uBAA4B;IAM9C,oEAAoE;IACpE,cAAc,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAI7C,qCAAqC;IACrC,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI;IAI7C,oDAAoD;IACpD,OAAO,IAAI,OAAO;IAWlB;;;;;OAKG;IACH,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAKjD,IAAI,SAAS,IAAI,MAAM,CAEtB;CACD"}

package/dist/services/voice/optimistic-rollback.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Optimistic-decode-with-rollback controller for the voice loop.
+ *
+ *   IDLE
+ *     │ speech-start
+ *     ▼
+ *   LISTENING
+ *     │ speech-pause
+ *     ▼
+ *   PAUSE_TENTATIVE  ── speech-active (within rollback window) ──▶ LISTENING
+ *     │                                                              ▲
+ *     │ speech-end (or pause > rollback window)                       │
+ *     ▼                                                               │
+ *   DRAFT_RESPONSE  ──── speech-active (within rollback window) ──────┘
+ *     │                  (restore checkpoint, abort drafter)
+ *     │ commit
+ *     ▼
+ *   COMMITTED → IDLE
+ *
+ * On `speech-pause` we snapshot the slot's KV state (`C1-<turn-id>`) and
+ * speculatively start the drafter against the partial transcript so that
+ * when the user IS done, the response is already underway. If they resume
+ * within the rollback window (~2× pause hangover), we restore the snapshot
+ * and abort the speculative draft — net cost is one checkpoint write/read.
+ *
+ * This module deliberately does NOT modify `turn-controller.ts`,
+ * `vad.ts`, `scheduler.ts`, `phrase-chunker.ts`, `barge-in.ts`, `pipeline.ts`,
+ * `pipeline-impls.ts`, or `transcriber.ts` — those are owned elsewhere.
+ * Instead, the turn controller composes this controller after the upstream
+ * llama.cpp merge lands and the feature flag flips.
+ */
+import type { CheckpointClient, CheckpointHandle } from "../checkpoint-client";
+import type { VadEventSource } from "./types";
+/**
+ * State of the optimistic-rollback controller. Mirrors the comment-block
+ * state machine above; exported so tests and telemetry can assert on it.
+ */
+export type OptimisticRollbackState = "idle" | "listening" | "pause-tentative" | "draft-response" | "committed";
+/**
+ * Telemetry event stream. Stays narrow — the controller emits exactly four
+ * lifecycle events per turn (save, restore-or-commit, draft-start,
+ * draft-abort). Consumers wire these into the existing voice-bench
+ * trajectory captures.
+ */
+export interface OptimisticRollbackTelemetry {
+    onCheckpointSaved?: (handle: CheckpointHandle, turnId: string) => void;
+    onCheckpointRestored?: (handle: CheckpointHandle, turnId: string) => void;
+    onSpeculativeDraftStarted?: (turnId: string) => void;
+    onSpeculativeDraftAborted?: (turnId: string, reason: AbortReason) => void;
+    /**
+     * Fired when the controller silently swallows an error from the
+     * checkpoint client — surfacing it via telemetry rather than rethrowing
+     * keeps a failing checkpoint endpoint from breaking the voice loop. The
+     * caller decides whether to flip the feature flag off.
+     */
+    onCheckpointError?: (op: "save" | "restore" | "cancel", error: unknown, turnId: string) => void;
+}
+export type AbortReason = "resumed" | "committed" | "shutdown";
+/**
+ * Speculative drafter handle. The voice turn controller hands one of these
+ * in when starting the drafter so this module can abort it without
+ * importing the drafter's internals. `abort()` MUST be idempotent — the
+ * controller may call it again on shutdown.
+ */
+export interface SpeculativeDraftHandle {
+    abort(): void;
+}
+/**
+ * Caller-supplied drafter starter. Returns a handle the controller can
+ * abort. Called on entry to `pause-tentative`. The promise must resolve
+ * synchronously (or near-synchronously) — the speculative draft runs in
+ * the background.
+ */
+export type StartSpeculativeDraft = (partialTranscript: string, turnId: string) => SpeculativeDraftHandle;
+/**
+ * Caller-supplied source for the partial transcript captured at the
+ * `speech-pause` instant. Kept as a function so the controller doesn't
+ * have to hold a reference to the transcriber.
+ */
+export type ReadPartialTranscript = () => string;
+export interface OptimisticRollbackControllerOptions {
+    /** The slot id the voice loop is pinned to for this turn. */
+    slotId: number;
+    /**
+     * Per-process feature flag. Defaults to `false` — flip on once the
+     * upstream `--ctx-checkpoints` merge lands AND the rollout plan in
+     * `docs/eliza-1-optimistic-rollback.md` reaches the desired bucket.
+     * Forwards every VAD event to the wrapped state machine when off but
+     * never makes a checkpoint REST call.
+     */
+    enableOptimisticRollback?: boolean;
+    /**
+     * VAD pause hangover (ms). Default 100 ms (lowered from 220ms; further
+     * reduction gated on semantic EOT classifier V2) — matches the voice
+     * loop's standard hangover. The rollback window is `2 ×` this value.
+     */
+    pauseHangoverMs?: number;
+    /** Source of VAD events; usually `VadDetector`. */
+    vadSource: VadEventSource;
+    client: CheckpointClient;
+    startSpeculativeDraft: StartSpeculativeDraft;
+    readPartialTranscript: ReadPartialTranscript;
+    telemetry?: OptimisticRollbackTelemetry;
+    /**
+     * Wall-clock function. Injected for tests; defaults to `Date.now`. The
+     * controller uses this to enforce the rollback window — if a
+     * `speech-active` arrives more than `2 × pauseHangoverMs` after the
+     * `speech-pause`, the controller commits rather than restores.
+     */
+    now?: () => number;
+}
+/**
+ * Optimistic-rollback controller. Subscribes to a `VadEventSource` and
+ * drives the checkpoint REST client + a caller-supplied speculative
+ * drafter. Idempotent `dispose()` for clean shutdown.
+ */
+export declare class OptimisticRollbackController {
+    private state;
+    private currentTurnId;
+    private pauseTimestampMs;
+    private currentCheckpoint;
+    private currentDraft;
+    private readonly unsubscribe;
+    private readonly enabled;
+    private readonly pauseHangoverMs;
+    private readonly slotId;
+    private readonly client;
+    private readonly startSpeculativeDraft;
+    private readonly readPartialTranscript;
+    private readonly telemetry;
+    private readonly now;
+    private disposed;
+    constructor(opts: OptimisticRollbackControllerOptions);
+    /** Current state — read-only view for tests / telemetry. */
+    getState(): OptimisticRollbackState;
+    /**
+     * Detach from the VAD source and abort any in-flight speculative draft.
+     * Safe to call multiple times.
+     */
+    dispose(): void;
+    private handleVadEvent;
+    private transitionToListening;
+    private handleSpeechPause;
+    private startDraftIfStillPaused;
+    private handleSpeechActive;
+    private handleSpeechEnd;
+    private rollback;
+    private commit;
+    private turnIdString;
+}
+//# sourceMappingURL=optimistic-rollback.d.ts.map

package/dist/services/voice/optimistic-rollback.d.ts.map

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

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

@@ -0,0 +1,73 @@
+/**
+ * A2 — LocalAgreement-n streaming-ASR partial stabilizer.
+ *
+ * Streaming ASR (the fused Gemma ASR 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/dist/services/voice/partial-stabilizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"partial-stabilizer.d.ts","sourceRoot":"","sources":["../../../src/services/voice/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/dist/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/dist/services/voice/phoneme-tokenizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phoneme-tokenizer.d.ts","sourceRoot":"","sources":["../../../src/services/voice/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/dist/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/dist/services/voice/phrase-cache.d.ts.map

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

package/dist/services/voice/phrase-chunker.d.ts

@@ -0,0 +1,62 @@
+import type { PhonemeTokenizer } from "./phoneme-tokenizer";
+import type { AcceptedToken, Phrase, PhraseChunkerConfig, TextToken } from "./types";
+/** Wall-clock source the chunker uses. Tests inject a deterministic clock. */
+export type ClockMs = () => number;
+export declare class PhraseChunker {
+    private buffer;
+    private nextPhraseId;
+    private readonly terminators;
+    private readonly chunkOn;
+    private readonly phonemesPerChunk;
+    private readonly maxTokensPerPhrase;
+    private readonly tokenizer;
+    private phonemeCount;
+    /**
+     * 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;
+    /** Shorter budget applied only while no phrase has flushed yet this reply. */
+    private readonly firstPhraseMaxAccumulationMs;
+    private readonly clock;
+    private firstTokenAtMs;
+    /** Phrases emitted since the last {@link reset}; gates the first-phrase budget. */
+    private phrasesEmitted;
+    constructor(config: PhraseChunkerConfig, tokenizer?: PhonemeTokenizer | null, clock?: ClockMs);
+    push(token: AcceptedToken): Phrase | null;
+    /** Active time budget: the shorter first-phrase budget until the reply's
+     * first phrase has flushed, then the full budget. */
+    private currentBudgetMs;
+    /**
+     * 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;
+    /**
+     * 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;
+    flushPending(): Phrase | null;
+    /**
+     * 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;
+    reset(): void;
+    private endsWithTerminator;
+    private flushAs;
+}
+export declare function chunkTokens(tokens: TextToken[], config: PhraseChunkerConfig, acceptedAt?: number, tokenizer?: PhonemeTokenizer | null): Phrase[];
+//# sourceMappingURL=phrase-chunker.d.ts.map

package/dist/services/voice/phrase-chunker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phrase-chunker.d.ts","sourceRoot":"","sources":["../../../src/services/voice/phrase-chunker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EACX,aAAa,EACb,MAAM,EACN,mBAAmB,EACnB,SAAS,EACT,MAAM,SAAS,CAAC;AA8DjB,8EAA8E;AAC9E,MAAM,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC;AAInC,qBAAa,aAAa;IACzB,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsB;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD,OAAO,CAAC,YAAY,CAAK;IACzB;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,4BAA4B,CAAS;IACtD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAChC,OAAO,CAAC,cAAc,CAAK;IAC3B,mFAAmF;IACnF,OAAO,CAAC,cAAc,CAAK;gBAG1B,MAAM,EAAE,mBAAmB,EAC3B,SAAS,GAAE,gBAAgB,GAAG,IAAW,EACzC,KAAK,GAAE,OAAuB;IAgC/B,IAAI,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI;IAmCzC;yDACqD;IACrD,OAAO,CAAC,eAAe;IAMvB;;;;;OAKG;IACH,yBAAyB,IAAI,MAAM,GAAG,IAAI;IAU1C;;;;;OAKG;IACH,iBAAiB,IAAI,MAAM;IAO3B,YAAY,IAAI,MAAM,GAAG,IAAI;IAK7B;;;;;;;OAOG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAexC,KAAK,IAAI,IAAI;IAOb,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,OAAO;CAkBf;AAED,wBAAgB,WAAW,CAC1B,MAAM,EAAE,SAAS,EAAE,EACnB,MAAM,EAAE,mBAAmB,EAC3B,UAAU,SAAI,EACd,SAAS,GAAE,gBAAgB,GAAG,IAAW,GACvC,MAAM,EAAE,CAUV"}