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

package/dist/services/voice/pipeline-impls.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Concrete implementations of the `VoicePipeline` seams (`pipeline.ts`).
+ *
+ * `pipeline.ts` defines two interfaces — `DraftProposer`, `TargetVerifier`
+ * — plus the ASR contract (it consumes the live `StreamingTranscriber`
+ * from `voice/types.ts` directly) and an overlapped scheduler that drives
+ * the fused mic→speech graph from `packages/inference/AGENTS.md` §4. This
+ * module fills those interfaces against the live runtime:
+ *
+ *   - `MissingAsrTranscriber` — a `StreamingTranscriber` that hard-fails
+ *     when no ASR backend is available (AGENTS.md §3 — no silent cloud
+ *     fallback). The bridge's `resolveTranscriber()` returns this instead
+ *     of throwing eagerly so the failure surfaces at turn time.
+ *   - `MtpDraftProposer` — proposes a small MTP draft window from the
+ *     running in-process llama.cpp runtime; honours `cancel.cancelled`
+ *     between kernel ticks.
+ *   - `MtpTargetVerifier` — verifies against the text model's KV cache
+ *     and consumes exact verifier accept/reject events when the runtime
+ *     emits them.
+ *
+ * Hard-fail discipline (AGENTS.md §3 + §9): a missing fused ASR region in
+ * voice mode is a thrown `VoiceStartupError`, never a silent cloud
+ * fallback, never log-and-continue.
+ *
+ * Why a separate file from `pipeline.ts`: `pipeline.ts` stays
+ * dependency-light (it is the streaming contract, importable by text-only
+ * callers). The runtime wiring lives here so
+ * the contract module does not drag it in.
+ */
+import type { GenerateArgs } from "../backend";
+import { type DraftProposer, type TargetVerifier } from "./pipeline";
+import type { PcmFrame, StreamingTranscriber, TextToken, TranscriptUpdate, VerifierStreamEvent } from "./types";
+/**
+ * A `StreamingTranscriber` that hard-fails: used when no ASR backend is
+ * available (no fused streaming decoder, no fused batch decoder, no
+ * bundled ASR region) but a voice turn was requested. AGENTS.md §3 —
+ * missing required voice backend in voice mode is a thrown
+ * `VoiceStartupError`, never a silent fallback. The bridge returns this
+ * from `resolveTranscriber()` so the failure surfaces when the pipeline
+ * actually feeds audio rather than at bridge construction.
+ */
+export declare class MissingAsrTranscriber implements StreamingTranscriber {
+    private readonly reason;
+    constructor(reason: string);
+    feed(_frame: PcmFrame): void;
+    flush(): Promise<TranscriptUpdate>;
+    on(): () => void;
+    dispose(): void;
+}
+/**
+ * Minimal surface of the running MTP text runtime the draft/verify
+ * adapters need. Kept structural so tests can pass a fake without
+ * standing up a real runtime.
+ */
+export interface MtpTextRunner {
+    /** True when MTP speculative decoding is enabled. */
+    hasDrafter(): boolean;
+    generateWithVerifierEvents(args: GenerateArgs & {
+        onVerifierEvent: (event: VerifierStreamEvent) => void | Promise<void>;
+    }): Promise<{
+        text: string;
+    }>;
+}
+/** Adapt a local-inference backend onto `MtpTextRunner`. */
+export declare function mtpTextRunner(runner: {
+    mtpEnabled(): boolean;
+    generateWithUsage(args: GenerateArgs & {
+        onVerifierEvent: (event: VerifierStreamEvent) => void | Promise<void>;
+    }): Promise<{
+        text: string;
+    }>;
+}): MtpTextRunner;
+/**
+ * `DraftProposer` over native MTP. The runtime draft window already bounds
+ * proposals; this adapter additionally
+ * clamps to the pipeline's `maxDraft` and stops early on
+ * `cancel.cancelled`. GPU dispatch is N=1 (the fork's voice profile
+ * disables command-buffer batching — ledger §2 "Keep voice dispatch
+ * unbatched") so a barge-in lands at the next kernel boundary.
+ *
+ * Until the fork exposes a "draft only, return the proposed tokens"
+ * endpoint, the proposer issues a short low-temperature completion
+ * (`maxTokens = maxDraft`) and treats the produced tokens as the draft
+ * window. The verifier then re-checks them against the target's KV — the
+ * standard speculative-decoding contract, just with the draft sourced
+ * from the same server.
+ */
+export declare class MtpDraftProposer implements DraftProposer {
+    private readonly runner;
+    constructor(runner: MtpTextRunner);
+    propose(args: {
+        prefix: ReadonlyArray<TextToken>;
+        maxDraft: number;
+        cancel: {
+            cancelled: boolean;
+        };
+    }): Promise<TextToken[]>;
+}
+/**
+ * `TargetVerifier` over the text model via MTP. Runs one
+ * autoregressive verify step against the runtime KV cache: it sends the
+ * accepted prefix and reads back the model's own continuation. The
+ * leading tokens that match the supplied `draft` are "accepted from
+ * draft"; the first mismatch is the correction; the model's `done` /
+ * stop is propagated.
+ *
+ * When the native fork emits exact verifier reject ranges, the
+ * `onVerifierEvent` callback already carries `kind: "reject"` events with
+ * the rejected token positions — this adapter records both and trusts the
+ * server's accept/reject split rather than re-deriving it.
+ */
+export declare class MtpTargetVerifier implements TargetVerifier {
+    private readonly runner;
+    private readonly maxStep;
+    constructor(runner: MtpTextRunner, opts?: {
+        maxStep?: number;
+    });
+    verify(args: {
+        prefix: ReadonlyArray<TextToken>;
+        draft: ReadonlyArray<TextToken>;
+        cancel: {
+            cancelled: boolean;
+        };
+    }): Promise<{
+        accepted: TextToken[];
+        done: boolean;
+    }>;
+}
+/**
+ * Bridge a `{cancelled: boolean}` flag (the pipeline's cancellation
+ * primitive — checked between kernel ticks) onto an `AbortSignal` so the
+ * local generation aborts when a barge-in fires.
+ *
+ * L6 — event-driven cancellation. The cancel token may expose an
+ * `onCancel(listener)` hook (set by the scheduler / pipeline when it
+ * wires the token up); when present, we fire `controller.abort()`
+ * synchronously from that hook and skip polling entirely. When the
+ * token is the plain `{cancelled: boolean}` POJO with no hook, we fall
+ * back to a coarse poll so a barge-in still lands in bounded time —
+ * but the hook-driven path is what voice barge-ins use in production.
+ */
+export interface CancelTokenWithSignal {
+    cancelled: boolean;
+    /**
+     * Optional hook the token's owner fires synchronously when `cancelled`
+     * flips from false to true. The listener returns nothing; calling it
+     * after `cancelled` has already been set is a harmless no-op.
+     */
+    onCancel?: (listener: () => void) => () => void;
+}
+//# sourceMappingURL=pipeline-impls.d.ts.map

package/dist/services/voice/pipeline-impls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-impls.d.ts","sourceRoot":"","sources":["../../../src/services/voice/pipeline-impls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,OAAO,EACN,KAAK,aAAa,EAElB,KAAK,cAAc,EACnB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACX,QAAQ,EACR,oBAAoB,EACpB,SAAS,EACT,gBAAgB,EAChB,mBAAmB,EACnB,MAAM,SAAS,CAAC;AAMjB;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,YAAW,oBAAoB;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM;IAC3C,IAAI,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI;IAGtB,KAAK,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAGxC,EAAE,IAAI,MAAM,IAAI;IAGhB,OAAO,IAAI,IAAI;CACf;AAMD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,qDAAqD;IACrD,UAAU,IAAI,OAAO,CAAC;IACtB,0BAA0B,CACzB,IAAI,EAAE,YAAY,GAAG;QACpB,eAAe,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACtE,GACC,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7B;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACrC,UAAU,IAAI,OAAO,CAAC;IACtB,iBAAiB,CAChB,IAAI,EAAE,YAAY,GAAG;QACpB,eAAe,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACtE,GACC,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7B,GAAG,aAAa,CAUhB;AAaD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;gBAE3B,MAAM,EAAE,aAAa;IAI3B,OAAO,CAAC,IAAI,EAAE;QACnB,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;QACjC,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE;YAAE,SAAS,EAAE,OAAO,CAAA;SAAE,CAAC;KAC/B,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;CA6BxB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAkB,YAAW,cAAc;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,aAAa,EAAE,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO;IAK5D,MAAM,CAAC,IAAI,EAAE;QAClB,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;QACjC,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;QAChC,MAAM,EAAE;YAAE,SAAS,EAAE,OAAO,CAAA;SAAE,CAAC;KAC/B,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;CA2CrD;AAMD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACrC,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;CAChD"}

package/dist/services/voice/pipeline.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Pipelined parallel-generation scheduler — the fused mic→speech graph
+ * from `packages/inference/AGENTS.md` §4:
+ *
+ *   mic / file → ASR → text tokens
+ *                      ↓
+ *                    scheduler ──→ MTP drafter (proposes N tokens)
+ *                                         ∥  (overlap, not sequential)
+ *                                  target verifier (text model)
+ *                                         ↓
+ *                                accepted tokens → phrase chunker
+ *                                         ↓                  ↘
+ *                              speaker preset (cached)    rollback queue
+ *                                         ↓                  ↙
+ *                                    OmniVoice TTS ←── on-reject: cancel chunk
+ *                                         ↓
+ *                                    PCM ring buffer → audio out
+ *
+ * The headline contract: **the moment ASR emits its last token, the
+ * MTP drafter starts drafting AND the target starts verifying — they
+ * overlap.** Drafter speculation N tokens ahead happens concurrently
+ * with the target verifying the previous window; accepted tokens are
+ * handed to the phrase chunker within the same scheduler tick.
+ *
+ * GPU command buffers stay N=1 (no command-buffer batching for voice)
+ * so a barge-in cancel lands at the next kernel boundary, not after a
+ * batch flush.
+ *
+ * Why this lives next to `VoiceScheduler` and not inside it: the
+ * scheduler owns the *audio* side (chunker → TTS → ring buffer →
+ * rollback → barge-in). This module owns the *text-generation* side
+ * (audio source → ASR → drafter∥verifier loop) and feeds accepted /
+ * rejected ranges into the scheduler. Keeping them separate keeps the
+ * scheduler usable from text-only callers (which reach the same nodes
+ * via the same scheduler — AGENTS.md §4) without an ASR/drafter
+ * dependency.
+ */
+import { PartialStabilizer } from "./partial-stabilizer";
+import type { VoiceScheduler } from "./scheduler";
+import type { StreamingTranscriber, TextToken, TranscriptionAudio, VerifierStreamEvent } from "./types";
+/**
+ * Split a transcript string into contiguous text tokens. The fused ASR
+ * tokenizer is shared with the text backbone (AGENTS.md §1 — zero
+ * re-tokenization), so the pipeline only needs *contiguous* token
+ * indices, not the model's exact subword boundaries; whitespace-aware
+ * word chunking is the closest stable approximation when only surface
+ * text is available. Empty input yields no tokens.
+ *
+ * `tokenIds`, when supplied, are the text-model vocabulary ids the fused
+ * ASR decoder emitted for `transcript`. When the lengths line up they are
+ * attached as `TextToken.id` so a downstream in-process handoff can skip
+ * re-tokenization; otherwise (mismatch — the surface split disagrees with
+ * the decoder's subword boundaries) the ids are dropped and only the
+ * word-chunk approximation is returned.
+ */
+export declare function splitTranscriptToTokens(transcript: string, startIndex?: number, tokenIds?: ReadonlyArray<number>): TextToken[];
+/**
+ * MTP drafter. `propose` returns up to `maxDraft` candidate
+ * continuation tokens given the accepted prefix. N=1 command buffers —
+ * the implementation MUST keep its GPU dispatch short enough to cancel
+ * at the next kernel boundary (no command-buffer batching for voice).
+ * Honours `cancel.cancelled` between kernel ticks.
+ */
+export interface DraftProposer {
+    propose(args: {
+        prefix: ReadonlyArray<TextToken>;
+        maxDraft: number;
+        cancel: {
+            cancelled: boolean;
+        };
+    }): Promise<TextToken[]>;
+}
+/**
+ * Target verifier (the text model). Given the accepted prefix plus a
+ * draft window, returns which leading draft tokens are accepted and the
+ * one corrected token at the first divergence (if any). When the draft
+ * is empty, the verifier still produces one token (plain autoregressive
+ * step). Honours `cancel.cancelled` between kernel ticks.
+ */
+export interface TargetVerifier {
+    verify(args: {
+        prefix: ReadonlyArray<TextToken>;
+        draft: ReadonlyArray<TextToken>;
+        cancel: {
+            cancelled: boolean;
+        };
+    }): Promise<{
+        accepted: TextToken[];
+        /** Set when the verifier reached the natural end of generation. */
+        done: boolean;
+    }>;
+}
+export interface VoicePipelineDeps {
+    scheduler: VoiceScheduler;
+    /**
+     * The live frame-fed ASR adapter (`voice/transcriber.ts` — fused
+     * `eliza_inference_asr_stream_*`, the fused batch adapter, or
+     * `MissingAsrTranscriber` deferring a hard failure). The pipeline drives
+     * it as a batch: it feeds the whole (VAD-gated) utterance buffer as one
+     * frame, `flush()`es to finalize, then splits the final transcript into
+     * contiguous text tokens (`splitTranscriptToTokens`). One `StreamingTranscriber`
+     * contract — there is no separate batch ASR interface.
+     */
+    transcriber: StreamingTranscriber;
+    drafter: DraftProposer;
+    verifier: TargetVerifier;
+}
+export interface VoicePipelineConfig {
+    /**
+     * Max tokens MTP drafts per round. Per-tier; small (≤8) so a
+     * rollback is cheap. The drafter and verifier overlap one round: while
+     * the verifier checks round k, the drafter speculates round k+1.
+     */
+    maxDraftTokens: number;
+    /**
+     * Hard cap on generated tokens per turn (safety stop). The verifier's
+     * `done` flag is the normal stop; this bounds a runaway model.
+     */
+    maxGeneratedTokens?: number;
+    /**
+     * A2 — when true, run streaming-ASR partials through a LocalAgreement-n
+     * stabilizer (`PartialStabilizer`) before splitting them into tokens
+     * and feeding the drafter. Off by default until the streaming-ASR
+     * fast path lands and validates the latency/quality trade. The
+     * `StreamingTranscriber.flush()`-driven batch path is unaffected (the
+     * stabilizer is a no-op on a single final partial).
+     */
+    usePartialStabilizer?: boolean;
+    /**
+     * A2 — agreement count `n` for `PartialStabilizer` when enabled.
+     * Ignored when `usePartialStabilizer` is false. Default 2.
+     */
+    partialStabilizerAgreementCount?: number;
+}
+export interface VoicePipelineEvents {
+    /** Fired once, the instant ASR emits its final token (= drafter+verifier kick-off). */
+    onAsrComplete?(tokens: ReadonlyArray<TextToken>): void;
+    /**
+     * Fired exactly once per turn, right after the ASR phase finishes and
+     * before the first drafter/verifier round. ASR → text → TTS are
+     * sequential within a turn (AGENTS.md §4), so the idle ASR-model pages
+     * can be dropped now — wire this to `MmapRegionHandle.evictPages()`
+     * (`madvise(MADV_DONTNEED)` on POSIX) for the ASR region to claw back
+     * ~1 GB of peak RSS while TTS decodes. The pages page back in
+     * transparently on the next turn's `feed()`; a host that prefers to
+     * keep ASR resident simply doesn't supply this hook. May be async; the
+     * pipeline does not block on it (a slow trim must not delay first audio).
+     */
+    onAsrPhaseComplete?(): void | Promise<void>;
+    /** Fired with each verifier accept/reject event before it hits the scheduler. */
+    onVerifierEvent?(event: VerifierStreamEvent): void;
+    /** Fired when the loop exits (verifier `done`, token cap, or barge-in cancel). */
+    onComplete?(reason: "done" | "token-cap" | "cancelled"): void;
+}
+/**
+ * One pipeline per active voice turn. Construct, call `run(audio)`,
+ * await the returned promise (or call `cancel()` for barge-in). The
+ * scheduler's barge-in controller also cancels an in-flight run — wire
+ * `bridge.triggerBargeIn()` and this run's `cancel()` to the same VAD
+ * signal so both the audio side (ring buffer drain) and the text side
+ * (stop drafting/verifying) abort together.
+ */
+export declare class VoicePipeline {
+    private readonly scheduler;
+    private readonly transcriber;
+    private readonly drafter;
+    private readonly verifier;
+    private readonly maxDraftTokens;
+    private readonly maxGeneratedTokens;
+    private readonly events;
+    /**
+     * A2 — when `config.usePartialStabilizer === true`, this is the active
+     * `PartialStabilizer` instance. Streaming-ASR consumers feed partials
+     * through it; the batch path in `transcribeAll()` collapses on a single
+     * final partial so the stabilizer is a no-op there. Exposed via
+     * `getPartialStabilizer()` so the streaming-ASR adapter (separate agent)
+     * can plug straight in once it ships.
+     */
+    private readonly partialStabilizer;
+    private active;
+    constructor(deps: VoicePipelineDeps, config: VoicePipelineConfig, events?: VoicePipelineEvents);
+    /** True while a turn is in flight. */
+    isRunning(): boolean;
+    /**
+     * A2 — the active `PartialStabilizer` when the pipeline was built with
+     * `usePartialStabilizer: true`, otherwise null. The streaming-ASR
+     * adapter (separate agent) feeds partials into this instance and
+     * forwards the `stable` portion downstream. Returning null when the
+     * feature flag is off lets the adapter skip the work entirely.
+     */
+    getPartialStabilizer(): PartialStabilizer | null;
+    /**
+     * Run one mic→speech turn. ASR streams first; the instant its last
+     * token lands, the drafter and verifier kick off concurrently and
+     * accepted tokens flow into the scheduler's chunker on the same tick.
+     * Resolves with the exit reason. Throws if a turn is already running.
+     */
+    run(audio: TranscriptionAudio): Promise<"done" | "token-cap" | "cancelled">;
+    /**
+     * Barge-in: cancel the in-flight turn. Stops ASR, stops the
+     * drafter/verifier loop at the next kernel boundary, and triggers the
+     * scheduler's barge-in (ring buffer drain + chunker flush + in-flight
+     * TTS cancel). No-op when no turn is running.
+     */
+    cancel(): void;
+    private execute;
+    /**
+     * Feed the whole utterance buffer to the live transcriber, finalize,
+     * and return the final transcript as contiguous text tokens. The
+     * transcriber is disposed afterwards (it is one per turn). A barge-in
+     * cancel checked before `flush()` short-circuits to an empty list.
+     */
+    private transcribeAll;
+    private finish;
+}
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/services/voice/pipeline.d.ts.map

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

package/dist/services/voice/prefill-client.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Optimistic prefill client (C7) — implements `/v1/prefill` against the
+ * llama.cpp REST API in three phases:
+ *
+ *   Phase 1 — `slot/save`:  snapshot the pre-user-message KV state so a
+ *             rollback can restore it if speech continues (SPEECH_ACTIVE_REBOUND).
+ *
+ *   Phase 2 — `POST /completion` with stream=false + cache_prompt=true:
+ *             run the model's prefill over `partialText` without sampling any
+ *             output tokens.  This warms the KV cache so the subsequent real
+ *             generation can skip one full prefill RTT.
+ *
+ *   Phase 3 — `slot/save` again: snapshot the post-prefill KV state under a
+ *             separate name.  The voice state machine passes this handle to the
+ *             verifier so generation resumes from the prefilled position.
+ *
+ * The upstream `/v1/prefill` endpoint is absent — the fork PR that
+ * adds it is tracked in `docs/eliza-1-optimistic-rollback.md`.  Until it
+ * lands, phases 1–3 are emulated via the existing slot-save REST path.  When
+ * the upstream endpoint ships the body of `prefillOptimistic` switches to a
+ * single REST call — callers see no signature change.
+ *
+ * Upstream endpoint contract: replace phases 2+3 with a single
+ * `POST /v1/prefill { slotId, partialText, eotProb }` once llama.cpp exposes
+ * it. That call must run the model prefill against `slotId`, save the resulting
+ * KV checkpoint, and return `{ handle, eotProb }`.
+ */
+import type { CheckpointHandle, CheckpointManagerLike } from "./checkpoint-manager";
+import type { ContextPartial } from "./eager-context-builder";
+/**
+ * Input contract for the optimistic prefill call.  `partialText` is the
+ * current partial transcript; `eotProb` is the caller's estimate that the
+ * user has stopped speaking (from VAD hangover progress or the EOT classifier).
+ */
+export interface PrefillOptimisticArgs {
+    /** Base URL of the llama-server (`http://host:port`). */
+    baseUrl: string;
+    /** Slot id pinning this conversation. */
+    slotId: string;
+    /** Partial transcript to prefill against.  Non-empty. */
+    partialText: string;
+    /**
+     * Probability the partial is end-of-turn (0..1).  Today recorded as
+     * telemetry only; once `/v1/prefill` lands the server uses it to decide
+     * whether to also kick the drafter inline.
+     */
+    eotProb: number;
+    /**
+     * Deterministic context from `EagerContextBuilder` (C3).  Used to build the
+     * system prompt passed to the prefill `/completion` call so the KV cache
+     * covers both the system prompt and the partial transcript.  Optional — when
+     * absent, only the partial transcript is prefilled.
+     */
+    context?: ContextPartial;
+}
+export interface PrefillOptimisticResult {
+    /**
+     * Handle to the POST-prefill KV snapshot.  Pass to
+     * `CheckpointManager.restoreCheckpoint` on SPEECH_END so the verifier
+     * resumes from the prefilled position.
+     */
+    checkpointHandle: CheckpointHandle;
+    /**
+     * Approximate token count of the prefilled text.  Derived from a rough
+     * whitespace tokenizer since the REST emulation path doesn't return a token count;
+     * once the upstream endpoint lands, the server returns the real count.
+     */
+    tokenCount: number;
+    /**
+     * Wall-clock milliseconds the prefill round-trip took (phases 1–3).
+     */
+    prefillMs: number;
+    /**
+     * Backend label.  `slot-save-emulation` = pre-upstream emulation path;
+     * `prefill-v1` = native `/v1/prefill` endpoint.
+     */
+    backend: "slot-save-emulation" | "prefill-v1";
+    /**
+     * End-of-turn probability echoed back from the server.  Today equals the
+     * caller's `eotProb` (the emulation path has nothing to refine it with); once the
+     * upstream endpoint lands, the server returns its own model estimate.
+     */
+    eotProb: number;
+}
+export interface PrefillOptimisticOptions {
+    checkpointManager: CheckpointManagerLike;
+    /**
+     * Name to use for the PRE-prefill snapshot (C1 — used by the rollback path
+     * on SPEECH_ACTIVE_REBOUND).  Defaults to `pre-prefill`.
+     */
+    preCheckpointName?: string;
+    /**
+     * Name to use for the POST-prefill snapshot (the one the verifier starts
+     * from on SPEECH_END).  Defaults to `post-prefill`.
+     */
+    postCheckpointName?: string;
+    /**
+     * Optional fetch implementation for tests.  Defaults to global `fetch`.
+     */
+    fetchImpl?: typeof fetch;
+    /**
+     * Request timeout for the `/completion` prefill call (ms).  Default 5 000 ms.
+     * The call is a no-sample prefill-only pass, so it should complete in
+     * O(transcript_tokens / throughput) — typically well under 1 s for short
+     * partials.
+     */
+    prefillTimeoutMs?: number;
+}
+/**
+ * Run the three-phase optimistic prefill and return a checkpoint handle for
+ * the post-prefill KV state.
+ *
+ * Voice state machine wiring:
+ *   - Call on `PAUSE_TENTATIVE` entry with `eotProb` from the EOT classifier.
+ *   - On `SPEECH_ACTIVE_REBOUND` (within rollback window): restore to the
+ *     PRE-prefill checkpoint (C1 saved in phase 1) via the checkpoint manager.
+ *     The post-prefill handle returned here is no longer needed.
+ *   - On `SPEECH_END`: pass `result.checkpointHandle` to the verifier so it
+ *     can resume generation from the prefilled KV state, saving one full
+ *     prefill RTT.
+ */
+export declare function prefillOptimistic(args: PrefillOptimisticArgs, opts: PrefillOptimisticOptions): Promise<PrefillOptimisticResult>;
+//# sourceMappingURL=prefill-client.d.ts.map

package/dist/services/voice/prefill-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefill-client.d.ts","sourceRoot":"","sources":["../../../src/services/voice/prefill-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EACX,gBAAgB,EAChB,qBAAqB,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAM9D;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACrC,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACvC;;;;OAIG;IACH,gBAAgB,EAAE,gBAAgB,CAAC;IACnC;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,EAAE,qBAAqB,GAAG,YAAY,CAAC;IAC9C;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,wBAAwB;IACxC,iBAAiB,EAAE,qBAAqB,CAAC;IACzC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B;AAUD;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACtC,IAAI,EAAE,qBAAqB,EAC3B,IAAI,EAAE,wBAAwB,GAC5B,OAAO,CAAC,uBAAuB,CAAC,CAoDlC"}

package/dist/services/voice/prefix-preserving-queue.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Prefix-preserving TTS rollback queue for barge-in handling.
+ *
+ * When the user barges in mid-response, the naive approach drops ALL
+ * in-flight audio chunks. This queue does better: it tags each audio
+ * chunk with the token range it covers, and on barge-in retains chunks
+ * whose token range ends at or before the divergence point (the last
+ * committed token index when the barge-in fires).
+ *
+ * If the new user utterance continues the topic, audio up to the
+ * divergence point plays smoothly. Chunks for tokens past the divergence
+ * are dropped.
+ *
+ * Data model:
+ *
+ *   TaggedAudioChunk — a PCM buffer paired with [start, end] token indices
+ *     (inclusive) and its duration in milliseconds.
+ *
+ *   PrefixPreservingQueue — ordered queue of TaggedAudioChunk. On barge-in
+ *     with a given divergencePoint:
+ *       keep   when chunk.tokenRange[1] <= divergencePoint
+ *       drop   when chunk.tokenRange[0] >  divergencePoint
+ *       trim   when chunk straddles the point (tokenRange[0] <= point
+ *              but tokenRange[1] > point) — kept whole; the scheduler
+ *              treats sub-phrase granularity as a best-effort approximation.
+ *
+ * The old `handleBargeIn` path (ring-buffer drain + full stop) remains
+ * active as a fallback when the queue is not wired (e.g. the backend
+ * emits chunks without token-range tags). When the queue IS wired, the
+ * scheduler calls `rollbackAt(divergencePoint)` instead of a plain drain,
+ * and replays the retained prefix into the sink before resuming.
+ */
+export interface TaggedAudioChunk {
+    pcm: Float32Array;
+    /**
+     * Inclusive token-index range the audio chunk covers.
+     * [start, end] where start <= end. Both values are in the
+     * scheduler's token-index space (same as `Phrase.fromIndex` /
+     * `Phrase.toIndex`).
+     */
+    tokenRange: [number, number];
+    /**
+     * Wall-clock duration of this chunk in milliseconds, computed from
+     * `pcm.length / sampleRate * 1000`. Stored here so the queue can
+     * report total retained duration to telemetry without knowing the
+     * sample rate.
+     */
+    durationMs: number;
+}
+export interface RollbackResult {
+    /** Chunks retained (token range ends at or before divergencePoint). */
+    retained: TaggedAudioChunk[];
+    /** Chunks dropped (token range starts after divergencePoint). */
+    dropped: TaggedAudioChunk[];
+    /**
+     * Chunks that straddled the divergence point
+     * (started at or before, ended after) — kept in `retained` at phrase
+     * granularity. Callers can inspect this for telemetry.
+     */
+    straddled: TaggedAudioChunk[];
+    /** Sum of retained chunk durations in milliseconds. */
+    retainedDurationMs: number;
+    /** Sum of dropped chunk durations in milliseconds. */
+    droppedDurationMs: number;
+}
+/**
+ * Prefix-preserving audio chunk queue.
+ *
+ * Usage:
+ *   1. On each audio chunk arriving from the TTS backend, call `enqueue`.
+ *   2. On barge-in, call `rollbackAt(divergencePoint)` — returns the
+ *      partition of retained vs dropped chunks. The caller replays the
+ *      retained prefix into the audio sink and discards the rest.
+ *   3. Call `clear()` to reset (e.g. on a new turn).
+ *
+ * Thread-safety: single-threaded JS — no locking needed.
+ */
+export declare class PrefixPreservingQueue {
+    private readonly chunks;
+    /** Number of chunks currently in the queue. */
+    get size(): number;
+    /**
+     * Add a tagged audio chunk to the tail of the queue. Chunks MUST be
+     * enqueued in token-range order (ascending `tokenRange[0]`) — the queue
+     * does not sort. Violations produce unspecified rollback behaviour.
+     */
+    enqueue(chunk: TaggedAudioChunk): void;
+    /**
+     * Partition the queue at `divergencePoint` (the last committed token
+     * index). Clears the queue and returns the three-way split.
+     *
+     * Decision per chunk:
+     *   chunk.tokenRange[1] <= divergencePoint  → retained (prefix)
+     *   chunk.tokenRange[0] >  divergencePoint  → dropped  (post-divergence)
+     *   otherwise (straddle)                    → retained (best-effort)
+     *
+     * After this call the queue is empty. Callers should replay `retained`
+     * into the audio sink.
+     */
+    rollbackAt(divergencePoint: number): RollbackResult;
+    /**
+     * Drop all queued chunks without replaying any of them. Used by the
+     * hard-stop / full-cancel path as a fallback when the new utterance
+     * does not continue the topic.
+     */
+    clear(): TaggedAudioChunk[];
+    /**
+     * Peek at the current queue without modifying it (snapshot for
+     * telemetry / tests).
+     */
+    snapshot(): ReadonlyArray<TaggedAudioChunk>;
+}
+//# sourceMappingURL=prefix-preserving-queue.d.ts.map

package/dist/services/voice/prefix-preserving-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefix-preserving-queue.d.ts","sourceRoot":"","sources":["../../../src/services/voice/prefix-preserving-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,WAAW,gBAAgB;IAChC,GAAG,EAAE,YAAY,CAAC;IAClB;;;;;OAKG;IACH,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC9B,uEAAuE;IACvE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,iEAAiE;IACjE,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B;;;;OAIG;IACH,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,uDAAuD;IACvD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,qBAAqB;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IAEjD,+CAA+C;IAC/C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAItC;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,eAAe,EAAE,MAAM,GAAG,cAAc;IAmCnD;;;;OAIG;IACH,KAAK,IAAI,gBAAgB,EAAE;IAK3B;;;OAGG;IACH,QAAQ,IAAI,aAAa,CAAC,gBAAgB,CAAC;CAG3C"}