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

package/src/services/voice/__tests__/voice-state-machine-prefill.test.ts

@@ -0,0 +1,275 @@
+/**
+ * Integration tests: VoiceStateMachine + C7 optimistic prefill.
+ *
+ * Tests the three key integration scenarios:
+ *
+ *   1. PAUSE_TENTATIVE entry fires `prefillOptimistic` (verifiable via
+ *      MockCheckpointManager — phase 1 + phase 3 saves appear).
+ *
+ *   2. SPEECH_ACTIVE_REBOUND (within rollback window): the in-flight prefill
+ *      is discarded; C1 is restored; the machine returns to LISTENING.
+ *
+ *   3. SPEECH_END: the machine awaits the prefill result and passes it to
+ *      `onCommit(prefillResult)` so the verifier can resume from the
+ *      prefilled KV state.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import { MockCheckpointManager } from "../checkpoint-manager";
+import type { PrefillOptimisticResult } from "../prefill-client";
+import type {
+	DrafterAbortReason,
+	DrafterHandle,
+	StartDrafterFn,
+} from "../voice-state-machine";
+import { VoiceStateMachine } from "../voice-state-machine";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function fakeDrafter(): {
+	fn: StartDrafterFn;
+	calls: Array<{ turnId: string; aborted: DrafterAbortReason | null }>;
+} {
+	const calls: Array<{ turnId: string; aborted: DrafterAbortReason | null }> =
+		[];
+	const fn: StartDrafterFn = ({ turnId }) => {
+		const rec = { turnId, aborted: null as DrafterAbortReason | null };
+		calls.push(rec);
+		const handle: DrafterHandle = {
+			abort(reason) {
+				if (rec.aborted === null) rec.aborted = reason;
+			},
+		};
+		return handle;
+	};
+	return { fn, calls };
+}
+
+function okFetch(): typeof fetch {
+	const mock = vi
+		.fn()
+		.mockResolvedValue(
+			new Response(JSON.stringify({ content: "" }), { status: 200 }),
+		);
+	return Object.assign(mock, { preconnect: fetch.preconnect }) as typeof fetch;
+}
+
+function makeMachineWithPrefill(mgr = new MockCheckpointManager()) {
+	const drafter = fakeDrafter();
+	const commits: Array<{
+		turnId: string;
+		transcript: string;
+		prefillResult?: PrefillOptimisticResult;
+	}> = [];
+	const rollbacks: Array<{ turnId: string }> = [];
+	const prefillEvents: Array<{
+		turnId: string;
+		result: PrefillOptimisticResult | null;
+		error: unknown;
+	}> = [];
+
+	const machine = new VoiceStateMachine({
+		slotId: "conv-prefill",
+		checkpointManager: mgr,
+		startDrafter: drafter.fn,
+		pauseHangoverMs: 200,
+		prefillConfig: {
+			baseUrl: "http://localhost:8080",
+			checkpointOptions: {
+				fetchImpl: okFetch(),
+			},
+		},
+		events: {
+			onCommit(turnId, transcript, prefillResult) {
+				commits.push({ turnId, transcript, prefillResult });
+			},
+			onRollback(turnId) {
+				rollbacks.push({ turnId });
+			},
+			onPrefill(turnId, result, error) {
+				prefillEvents.push({ turnId, result, error });
+			},
+		},
+	});
+
+	return { machine, mgr, drafter, commits, rollbacks, prefillEvents };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("VoiceStateMachine + C7 prefill integration", () => {
+	it("PAUSE_TENTATIVE entry fires prefillOptimistic — two saves appear in the checkpoint manager", async () => {
+		const mgr = new MockCheckpointManager();
+		const { machine } = makeMachineWithPrefill(mgr);
+
+		await machine.dispatch({ type: "speech-start", timestampMs: 0 });
+		await machine.dispatch({
+			type: "speech-pause",
+			timestampMs: 1000,
+			partialTranscript: "how do I bake",
+		});
+
+		// Allow the async prefill to settle.
+		await new Promise((r) => setTimeout(r, 20));
+
+		expect(machine.getState()).toBe("PAUSE_TENTATIVE");
+
+		// C1 (pre-draft) from the voice state machine + pre-prefill + post-prefill
+		// from prefillOptimistic. Order: pre-draft, pre-prefill, post-prefill.
+		const saves = mgr.operations.filter((op) => op.kind === "save");
+		// At minimum the pre-prefill and post-prefill saves from prefillOptimistic.
+		const prefillSaves = saves.filter(
+			(s) => s.name === "pre-prefill" || s.name === "post-prefill",
+		);
+		expect(prefillSaves).toHaveLength(2);
+		expect(prefillSaves[0].name).toBe("pre-prefill");
+		expect(prefillSaves[1].name).toBe("post-prefill");
+	});
+
+	it("PAUSE_TENTATIVE → onPrefill fires with the prefill result", async () => {
+		const { machine, prefillEvents } = makeMachineWithPrefill();
+
+		await machine.dispatch({ type: "speech-start", timestampMs: 0 });
+		await machine.dispatch({
+			type: "speech-pause",
+			timestampMs: 1000,
+			partialTranscript: "how do I bake",
+		});
+
+		// Allow the async prefill to settle.
+		await new Promise((r) => setTimeout(r, 20));
+
+		expect(prefillEvents).toHaveLength(1);
+		const prefillEvent = prefillEvents[0];
+		if (!prefillEvent) {
+			throw new Error("expected prefill event");
+		}
+		expect(prefillEvent.result).not.toBeNull();
+		expect(prefillEvent.error).toBeNull();
+		const result = prefillEvent.result;
+		if (result === null) {
+			throw new Error("expected prefill result");
+		}
+		expect(result.eotProb).toBeCloseTo(0.5, 1); // latestEotProb default = 0.5
+		expect(result.tokenCount).toBeGreaterThanOrEqual(1);
+	});
+
+	it("SPEECH_END awaits the prefill and passes the result to onCommit", async () => {
+		const { machine, commits } = makeMachineWithPrefill();
+
+		await machine.dispatch({ type: "speech-start", timestampMs: 0 });
+		await machine.dispatch({
+			type: "speech-pause",
+			timestampMs: 1000,
+			partialTranscript: "how do I bake",
+		});
+		await machine.dispatch({
+			type: "speech-end",
+			timestampMs: 1500,
+			finalTranscript: "how do I bake bread",
+		});
+
+		expect(machine.getState()).toBe("SPEAKING");
+		expect(commits).toHaveLength(1);
+		expect(commits[0].transcript).toBe("how do I bake bread");
+		// The prefill result is attached.
+		expect(commits[0].prefillResult).toBeDefined();
+		expect(commits[0].prefillResult?.backend).toBe("slot-save-emulation");
+		expect(commits[0].prefillResult?.checkpointHandle).toBeDefined();
+	});
+
+	it("SPEECH_ACTIVE_REBOUND (within window): prefill in-flight is discarded, C1 is restored, returns to LISTENING", async () => {
+		const mgr = new MockCheckpointManager();
+		const { machine, drafter } = makeMachineWithPrefill(mgr);
+
+		await machine.dispatch({ type: "speech-start", timestampMs: 0 });
+		await machine.dispatch({
+			type: "speech-pause",
+			timestampMs: 1000,
+			partialTranscript: "how do I",
+		});
+		// Rebound within 2 × 200ms = 400ms window.
+		await machine.dispatch({ type: "speech-active", timestampMs: 1200 });
+
+		expect(machine.getState()).toBe("LISTENING");
+		// Drafter was aborted.
+		expect(drafter.calls[0].aborted).toBe("resumed");
+		// C1 was discarded (not just the prefill). In the mock, discard is called.
+		expect(mgr.operations.some((op) => op.kind === "discard")).toBe(true);
+	});
+
+	it("barge-in on SPEAKING restores C1 (pre-draft, not post-prefill)", async () => {
+		const mgr = new MockCheckpointManager();
+		const { machine } = makeMachineWithPrefill(mgr);
+
+		await machine.dispatch({ type: "speech-start", timestampMs: 0 });
+		await machine.dispatch({
+			type: "speech-pause",
+			timestampMs: 1000,
+			partialTranscript: "bake bread",
+		});
+		await machine.dispatch({
+			type: "speech-end",
+			timestampMs: 1500,
+			finalTranscript: "how to bake bread",
+		});
+		expect(machine.getState()).toBe("SPEAKING");
+
+		await machine.dispatch({ type: "barge-in", timestampMs: 2200 });
+		expect(machine.getState()).toBe("LISTENING");
+
+		// A restore was called.
+		const restores = mgr.operations.filter((op) => op.kind === "restore");
+		expect(restores).toHaveLength(1);
+		// The restored handle should be the C1 (pre-draft) handle, not the post-prefill handle.
+		// The pre-draft save is the first "pre-draft" named save.
+		const preDraftSave = mgr.operations.find(
+			(op) => op.kind === "save" && op.name === "pre-draft",
+		);
+		expect(preDraftSave).toBeDefined();
+		if (!preDraftSave) {
+			throw new Error("expected pre-draft checkpoint save");
+		}
+		expect(restores[0].handleId).toBe(preDraftSave.handleId);
+	});
+
+	it("works normally when no prefillConfig is provided (backward compat)", async () => {
+		const mgr = new MockCheckpointManager();
+		const drafter = fakeDrafter();
+		const commits: Array<{ prefillResult?: PrefillOptimisticResult }> = [];
+		const machine = new VoiceStateMachine({
+			slotId: "conv-no-prefill",
+			checkpointManager: mgr,
+			startDrafter: drafter.fn,
+			pauseHangoverMs: 200,
+			events: {
+				onCommit(_turnId, _transcript, prefillResult) {
+					commits.push({ prefillResult });
+				},
+			},
+		});
+
+		await machine.dispatch({ type: "speech-start", timestampMs: 0 });
+		await machine.dispatch({
+			type: "speech-pause",
+			timestampMs: 1000,
+			partialTranscript: "hello",
+		});
+		await machine.dispatch({
+			type: "speech-end",
+			timestampMs: 1500,
+			finalTranscript: "hello world",
+		});
+
+		expect(machine.getState()).toBe("SPEAKING");
+		expect(commits[0].prefillResult).toBeUndefined();
+		// Only C1 (pre-draft) save — no prefill saves.
+		const saves = mgr.operations.filter((op) => op.kind === "save");
+		expect(saves).toHaveLength(1);
+		expect(saves[0].name).toBe("pre-draft");
+	});
+});

package/src/services/voice/__tests__/voice-state-machine.test.ts

@@ -0,0 +1,354 @@
+/**
+ * Unit tests for `VoiceStateMachine`.
+ *
+ * Each test drives the machine with synthetic events and asserts on:
+ *   - the public state at each step,
+ *   - the operations recorded by `MockCheckpointManager` (save/restore/
+ *     discard),
+ *   - the drafter lifecycle (started / aborted / reason).
+ *
+ * The four-state flow under test:
+ *
+ *   IDLE → LISTENING → PAUSE_TENTATIVE → (LISTENING | SPEAKING)
+ *   SPEAKING → LISTENING (on barge-in, restores C1)
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+	type CheckpointHandle,
+	MockCheckpointManager,
+} from "../checkpoint-manager";
+import {
+	type DrafterAbortReason,
+	type DrafterHandle,
+	type StartDrafterFn,
+	VoiceStateMachine,
+} from "../voice-state-machine";
+
+interface DrafterCall {
+	turnId: string;
+	partial: string;
+	aborted: DrafterAbortReason | null;
+}
+
+function fakeDrafter(): { fn: StartDrafterFn; calls: DrafterCall[] } {
+	const calls: DrafterCall[] = [];
+	const fn: StartDrafterFn = ({ turnId, partialTranscript }) => {
+		const record: DrafterCall = {
+			turnId,
+			partial: partialTranscript,
+			aborted: null,
+		};
+		calls.push(record);
+		// The state machine always pairs `controller.abort()` with an explicit
+		// `handle.abort(reason)` — record only the explicit reason so tests can
+		// assert which transition aborted the draft. (Wiring `signal` here too
+		// would race with the always-fired AbortController.abort() call.)
+		const handle: DrafterHandle = {
+			abort(reason) {
+				if (record.aborted === null) record.aborted = reason;
+			},
+		};
+		return handle;
+	};
+	return { fn, calls };
+}
+
+interface CapturedEvents {
+	states: Array<{ prev: string; next: string }>;
+	drafterStarted: string[];
+	drafterAborted: Array<{ turnId: string; reason: DrafterAbortReason }>;
+	commits: Array<{ turnId: string; transcript: string }>;
+	rollbacks: Array<{ turnId: string; handle: CheckpointHandle }>;
+	errors: Array<{ op: "save" | "restore" | "discard"; error: unknown }>;
+}
+
+function captureEvents(): {
+	captured: CapturedEvents;
+	events: ConstructorParameters<typeof VoiceStateMachine>[0]["events"];
+} {
+	const captured: CapturedEvents = {
+		states: [],
+		drafterStarted: [],
+		drafterAborted: [],
+		commits: [],
+		rollbacks: [],
+		errors: [],
+	};
+	return {
+		captured,
+		events: {
+			onStateChange: (prev, next) => captured.states.push({ prev, next }),
+			onDrafterStart: (turnId) => captured.drafterStarted.push(turnId),
+			onDrafterAbort: (turnId, reason) =>
+				captured.drafterAborted.push({ turnId, reason }),
+			onCommit: (turnId, transcript) =>
+				captured.commits.push({ turnId, transcript }),
+			onRollback: (turnId, handle) =>
+				captured.rollbacks.push({ turnId, handle }),
+			onError: (op, error) => captured.errors.push({ op, error }),
+		},
+	};
+}
+
+function makeMachine(mock = new MockCheckpointManager()): {
+	machine: VoiceStateMachine;
+	mock: MockCheckpointManager;
+	drafterCalls: DrafterCall[];
+	captured: CapturedEvents;
+} {
+	const drafter = fakeDrafter();
+	const ev = captureEvents();
+	const machine = new VoiceStateMachine({
+		slotId: "conv-1",
+		checkpointManager: mock,
+		startDrafter: drafter.fn,
+		events: ev.events,
+		pauseHangoverMs: 200,
+	});
+	return {
+		machine,
+		mock,
+		drafterCalls: drafter.calls,
+		captured: ev.captured,
+	};
+}
+
+describe("VoiceStateMachine — happy paths and rollback", () => {
+	it("starts in IDLE; speech-start transitions to LISTENING", async () => {
+		const { machine } = makeMachine();
+		expect(machine.getState()).toBe("IDLE");
+		await machine.dispatch({ type: "speech-start", timestampMs: 0 });
+		expect(machine.getState()).toBe("LISTENING");
+	});
+
+	it("speech-pause saves the C1 checkpoint and starts the drafter", async () => {
+		const { machine, mock, drafterCalls } = makeMachine();
+		await machine.dispatch({ type: "speech-start", timestampMs: 0 });
+		await machine.dispatch({
+			type: "speech-pause",
+			timestampMs: 1000,
+			partialTranscript: "how do I",
+		});
+		expect(machine.getState()).toBe("PAUSE_TENTATIVE");
+		expect(mock.operations).toContainEqual({
+			kind: "save",
+			slotId: "conv-1",
+			name: "pre-draft",
+			handleId: 1,
+		});
+		expect(drafterCalls).toHaveLength(1);
+		expect(drafterCalls[0].partial).toBe("how do I");
+		expect(machine.getActiveCheckpoint()).not.toBeNull();
+	});
+
+	it("speech-active within rollback window discards C1 and returns to LISTENING", async () => {
+		const { machine, mock, drafterCalls, captured } = makeMachine();
+		await machine.dispatch({ type: "speech-start", timestampMs: 0 });
+		await machine.dispatch({
+			type: "speech-pause",
+			timestampMs: 1000,
+			partialTranscript: "how do I",
+		});
+		// Rollback window is 2 * 200ms = 400ms; arrive at 200ms (within window).
+		await machine.dispatch({ type: "speech-active", timestampMs: 1200 });
+		expect(machine.getState()).toBe("LISTENING");
+		expect(mock.operations.filter((op) => op.kind === "discard")).toHaveLength(
+			1,
+		);
+		expect(machine.getActiveCheckpoint()).toBeNull();
+		// Drafter was aborted with reason "resumed".
+		expect(drafterCalls[0].aborted).toBe("resumed");
+		expect(captured.drafterAborted.some((d) => d.reason === "resumed")).toBe(
+			true,
+		);
+	});
+
+	it("speech-end commits the turn and retains C1 for barge-in", async () => {
+		const { machine, mock, captured } = makeMachine();
+		await machine.dispatch({ type: "speech-start", timestampMs: 0 });
+		await machine.dispatch({
+			type: "speech-pause",
+			timestampMs: 1000,
+			partialTranscript: "how do I",
+		});
+		await machine.dispatch({
+			type: "speech-end",
+			timestampMs: 1500,
+			finalTranscript: "how do I bake bread",
+		});
+		expect(machine.getState()).toBe("SPEAKING");
+		// C1 is retained.
+		expect(machine.getActiveCheckpoint()).not.toBeNull();
+		expect(mock.liveHandleCount()).toBe(1);
+		// No discard happened — the only operation should be the save.
+		expect(mock.operations.filter((op) => op.kind === "discard")).toHaveLength(
+			0,
+		);
+		expect(captured.commits).toEqual([
+			{ turnId: "turn-1", transcript: "how do I bake bread" },
+		]);
+	});
+
+	it("barge-in mid-SPEAKING restores C1 and re-enters LISTENING with a new turn id", async () => {
+		const { machine, mock, drafterCalls, captured } = makeMachine();
+		await machine.dispatch({ type: "speech-start", timestampMs: 0 });
+		await machine.dispatch({
+			type: "speech-pause",
+			timestampMs: 1000,
+			partialTranscript: "how do I",
+		});
+		await machine.dispatch({
+			type: "speech-end",
+			timestampMs: 1500,
+			finalTranscript: "how do I bake bread",
+		});
+		const turnBeforeBarge = machine.getTurnId();
+		expect(turnBeforeBarge).toBe("turn-1");
+
+		await machine.dispatch({ type: "barge-in", timestampMs: 2200 });
+		expect(machine.getState()).toBe("LISTENING");
+		expect(mock.operations.filter((op) => op.kind === "restore")).toHaveLength(
+			1,
+		);
+		expect(captured.rollbacks).toHaveLength(1);
+		expect(captured.rollbacks[0].handle.name).toBe("pre-draft");
+		expect(machine.getTurnId()).toBe("turn-2");
+		// Drafter was aborted with barge-in reason.
+		expect(drafterCalls[0].aborted).toBe("barge-in");
+	});
+
+	it("two consecutive barge-ins restore the same C1 twice", async () => {
+		const { machine, mock } = makeMachine();
+		await machine.dispatch({ type: "speech-start", timestampMs: 0 });
+		await machine.dispatch({
+			type: "speech-pause",
+			timestampMs: 1000,
+			partialTranscript: "how do I",
+		});
+		await machine.dispatch({
+			type: "speech-end",
+			timestampMs: 1500,
+			finalTranscript: "how do I bake bread",
+		});
+		const c1 = machine.getActiveCheckpoint();
+		expect(c1).not.toBeNull();
+
+		// First barge-in.
+		await machine.dispatch({ type: "barge-in", timestampMs: 2000 });
+		expect(machine.getState()).toBe("LISTENING");
+		expect(machine.getActiveCheckpoint()).toBe(c1);
+
+		// Second turn: speech-start, then speech-end without pause means no new
+		// C1; we go straight to SPEAKING but retain the original C1.
+		await machine.dispatch({ type: "speech-start", timestampMs: 2100 });
+		await machine.dispatch({
+			type: "speech-end",
+			timestampMs: 2400,
+			finalTranscript: "wait, actually...",
+		});
+		expect(machine.getState()).toBe("SPEAKING");
+
+		// Second barge-in restores the same C1.
+		await machine.dispatch({ type: "barge-in", timestampMs: 2500 });
+		expect(machine.getState()).toBe("LISTENING");
+		expect(mock.operations.filter((op) => op.kind === "restore")).toHaveLength(
+			2,
+		);
+		// Both restores target the same handle id.
+		const restoreOps = mock.operations.filter((op) => op.kind === "restore");
+		expect(restoreOps[0].handleId).toBe(restoreOps[1].handleId);
+	});
+
+	it("speech-active outside the rollback window promotes to SPEAKING without rollback", async () => {
+		const { machine, mock } = makeMachine();
+		await machine.dispatch({ type: "speech-start", timestampMs: 0 });
+		await machine.dispatch({
+			type: "speech-pause",
+			timestampMs: 1000,
+			partialTranscript: "how do I",
+		});
+		// Window is 2 * 200ms = 400ms; arrive at 500ms (outside).
+		await machine.dispatch({ type: "speech-active", timestampMs: 1500 });
+		expect(machine.getState()).toBe("SPEAKING");
+		expect(mock.operations.filter((op) => op.kind === "discard")).toHaveLength(
+			0,
+		);
+	});
+
+	it("dispose aborts the drafter and discards an outstanding C1", async () => {
+		const { machine, mock, drafterCalls } = makeMachine();
+		await machine.dispatch({ type: "speech-start", timestampMs: 0 });
+		await machine.dispatch({
+			type: "speech-pause",
+			timestampMs: 1000,
+			partialTranscript: "how do I",
+		});
+		await machine.dispose();
+		expect(machine.getState()).toBe("IDLE");
+		expect(mock.liveHandleCount()).toBe(0);
+		expect(drafterCalls[0].aborted).toBe("shutdown");
+	});
+
+	it("checkpoints disabled: state machine still transitions but never touches the manager", async () => {
+		const mock = new MockCheckpointManager();
+		const drafter = fakeDrafter();
+		const machine = new VoiceStateMachine({
+			slotId: "conv-1",
+			checkpointManager: mock,
+			startDrafter: drafter.fn,
+			enableCheckpoints: false,
+			pauseHangoverMs: 200,
+		});
+		await machine.dispatch({ type: "speech-start", timestampMs: 0 });
+		await machine.dispatch({
+			type: "speech-pause",
+			timestampMs: 1000,
+			partialTranscript: "how do I",
+		});
+		await machine.dispatch({
+			type: "speech-end",
+			timestampMs: 1500,
+			finalTranscript: "how do I bake bread",
+		});
+		await machine.dispatch({ type: "barge-in", timestampMs: 2000 });
+		expect(machine.getState()).toBe("LISTENING");
+		// No manager activity.
+		expect(mock.operations).toHaveLength(0);
+		// Drafter still ran.
+		expect(drafter.calls).toHaveLength(1);
+		expect(drafter.calls[0].aborted).toBe("barge-in");
+	});
+
+	it("a save failure surfaces via onError but does not block state transitions", async () => {
+		const failingMock: MockCheckpointManager = Object.assign(
+			new MockCheckpointManager(),
+			{
+				saveCheckpoint: async () => {
+					throw new Error("simulated save failure");
+				},
+			},
+		);
+		const drafter = fakeDrafter();
+		const ev = captureEvents();
+		const machine = new VoiceStateMachine({
+			slotId: "conv-1",
+			checkpointManager: failingMock,
+			startDrafter: drafter.fn,
+			events: ev.events,
+			pauseHangoverMs: 200,
+		});
+		await machine.dispatch({ type: "speech-start", timestampMs: 0 });
+		await machine.dispatch({
+			type: "speech-pause",
+			timestampMs: 1000,
+			partialTranscript: "how do I",
+		});
+		// State advanced despite the failure; error surfaced.
+		expect(machine.getState()).toBe("PAUSE_TENTATIVE");
+		expect(ev.captured.errors).toHaveLength(1);
+		expect(ev.captured.errors[0].op).toBe("save");
+		// Drafter still kicked.
+		expect(drafter.calls).toHaveLength(1);
+	});
+});