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

package/src/services/voice/__tests__/checkpoint-manager.test.ts

@@ -0,0 +1,241 @@
+/**
+ * Unit tests for `CheckpointManager` (REST-backed) and
+ * `MockCheckpointManager` (in-memory).
+ *
+ * `CheckpointManager` is verified by replacing the underlying fetch and
+ * asserting the REST URLs / methods. `MockCheckpointManager` is verified
+ * by save/restore/discard round-trips that check the recorded operations
+ * + the snapshot replay semantics.
+ */
+
+import { describe, expect, it } from "vitest";
+import type { CheckpointFetch } from "../../checkpoint-client";
+import {
+	CheckpointHandleInvalidError,
+	CheckpointManager,
+	MockCheckpointManager,
+} from "../checkpoint-manager";
+import { prefillOptimistic } from "../prefill-client";
+
+interface RecordedRequest {
+	url: string;
+	method: string | undefined;
+}
+
+function makeFetch(recorded: RecordedRequest[]): CheckpointFetch {
+	return async (url, init) => {
+		recorded.push({ url: String(url), method: init?.method });
+		return {
+			ok: true,
+			status: 200,
+			statusText: "OK",
+			async text() {
+				return "{}";
+			},
+		};
+	};
+}
+
+function makePrefillFetch(): typeof fetch {
+	const impl = Object.assign(
+		async () => new Response(JSON.stringify({ content: "" }), { status: 200 }),
+		{ preconnect: fetch.preconnect },
+	);
+	return impl as typeof fetch;
+}
+
+describe("CheckpointManager (REST-backed)", () => {
+	it("saveCheckpoint hits POST /slots/<id>/save and returns a live handle", async () => {
+		const recorded: RecordedRequest[] = [];
+		const mgr = new CheckpointManager({
+			baseUrl: "http://127.0.0.1:9999",
+			fetchImpl: makeFetch(recorded),
+			resolveSlotId: () => 3,
+		});
+		const handle = await mgr.saveCheckpoint("conv-1", "pre-draft");
+		expect(handle.slotId).toBe("conv-1");
+		expect(handle.name).toBe("pre-draft");
+		expect(handle.backendRef?.slotId).toBe(3);
+		expect(handle.backendRef?.filename).toMatch(/^C1-conv-1-pre-draft-/);
+		expect(recorded).toHaveLength(1);
+		expect(recorded[0].method).toBe("POST");
+		expect(recorded[0].url).toMatch(/\/slots\/3\/save\?filename=/);
+	});
+
+	it("restoreCheckpoint hits POST /slots/<id>/restore against the saved filename", async () => {
+		const recorded: RecordedRequest[] = [];
+		const mgr = new CheckpointManager({
+			baseUrl: "http://127.0.0.1:9999",
+			fetchImpl: makeFetch(recorded),
+			resolveSlotId: () => 5,
+		});
+		const handle = await mgr.saveCheckpoint("conv-2", "pre-draft");
+		await mgr.restoreCheckpoint(handle);
+		expect(recorded).toHaveLength(2);
+		expect(recorded[1].method).toBe("POST");
+		expect(recorded[1].url).toMatch(/\/slots\/5\/restore\?filename=/);
+		if (!handle.backendRef) {
+			throw new Error("expected checkpoint backend reference");
+		}
+		expect(recorded[1].url).toContain(handle.backendRef.filename);
+	});
+
+	it("discardCheckpoint hits DELETE /slots/<id> and invalidates the handle", async () => {
+		const recorded: RecordedRequest[] = [];
+		const mgr = new CheckpointManager({
+			baseUrl: "http://127.0.0.1:9999",
+			fetchImpl: makeFetch(recorded),
+			resolveSlotId: () => 7,
+		});
+		const handle = await mgr.saveCheckpoint("conv-3", "pre-draft");
+		await mgr.discardCheckpoint(handle);
+		expect(recorded.at(-1)?.method).toBe("DELETE");
+		expect(recorded.at(-1)?.url).toBe("http://127.0.0.1:9999/slots/7");
+		await expect(mgr.restoreCheckpoint(handle)).rejects.toBeInstanceOf(
+			CheckpointHandleInvalidError,
+		);
+		await expect(mgr.discardCheckpoint(handle)).rejects.toBeInstanceOf(
+			CheckpointHandleInvalidError,
+		);
+	});
+
+	it("each save returns a distinct handle even for the same (slotId, name)", async () => {
+		const recorded: RecordedRequest[] = [];
+		const mgr = new CheckpointManager({
+			baseUrl: "http://127.0.0.1:9999",
+			fetchImpl: makeFetch(recorded),
+			resolveSlotId: () => 0,
+		});
+		const a = await mgr.saveCheckpoint("conv-x", "pre-draft");
+		const b = await mgr.saveCheckpoint("conv-x", "pre-draft");
+		expect(a.id).not.toBe(b.id);
+		expect(a.backendRef?.filename).not.toBe(b.backendRef?.filename);
+	});
+
+	it("rejects malformed slotId or checkpoint name", async () => {
+		const mgr = new CheckpointManager({
+			baseUrl: "http://127.0.0.1:9999",
+			fetchImpl: makeFetch([]),
+		});
+		await expect(mgr.saveCheckpoint("", "pre-draft")).rejects.toThrow(
+			/invalid slotId/,
+		);
+		await expect(mgr.saveCheckpoint("conv-1", "../etc/passwd")).rejects.toThrow(
+			/invalid checkpoint name/,
+		);
+	});
+});
+
+describe("MockCheckpointManager", () => {
+	it("records save / restore / discard operations in order", async () => {
+		const mock = new MockCheckpointManager();
+		const handle = await mock.saveCheckpoint("conv-1", "pre-draft");
+		await mock.restoreCheckpoint(handle);
+		await mock.discardCheckpoint(handle);
+		expect(mock.operations).toEqual([
+			{ kind: "save", slotId: "conv-1", name: "pre-draft", handleId: 1 },
+			{ kind: "restore", handleId: 1 },
+			{ kind: "discard", handleId: 1 },
+		]);
+	});
+
+	it("restore replays the snapshot's tokens onto currentTokens", async () => {
+		const mock = new MockCheckpointManager(() => ({
+			tokens: [10, 11, 12],
+			metadata: { partial: "hello wo" },
+		}));
+		const handle = await mock.saveCheckpoint("conv-1", "pre-draft");
+		mock.currentTokens = [99, 99, 99, 99]; // simulate post-pause drafter writes
+		await mock.restoreCheckpoint(handle);
+		expect(mock.currentTokens).toEqual([10, 11, 12]);
+	});
+
+	it("the same handle can be restored more than once (consecutive barge-ins)", async () => {
+		let snapshotCallCount = 0;
+		const mock = new MockCheckpointManager(() => {
+			snapshotCallCount++;
+			return { tokens: [1, 2, 3] };
+		});
+		const handle = await mock.saveCheckpoint("conv-1", "pre-draft");
+		expect(snapshotCallCount).toBe(1);
+		await mock.restoreCheckpoint(handle);
+		await mock.restoreCheckpoint(handle);
+		expect(mock.operations.filter((op) => op.kind === "restore")).toHaveLength(
+			2,
+		);
+		// Handle still live.
+		expect(mock.liveHandleCount()).toBe(1);
+	});
+
+	it("rejects restore/discard for unknown or already-discarded handles", async () => {
+		const mock = new MockCheckpointManager();
+		const handle = await mock.saveCheckpoint("conv-1", "pre-draft");
+		await mock.discardCheckpoint(handle);
+		await expect(mock.restoreCheckpoint(handle)).rejects.toBeInstanceOf(
+			CheckpointHandleInvalidError,
+		);
+		await expect(mock.discardCheckpoint(handle)).rejects.toBeInstanceOf(
+			CheckpointHandleInvalidError,
+		);
+	});
+
+	it("defaults to capturing currentTokens at save time when no snapshotSource is provided", async () => {
+		const mock = new MockCheckpointManager();
+		mock.currentTokens = [7, 8, 9];
+		const handle = await mock.saveCheckpoint("conv-1", "pre-draft");
+		mock.currentTokens = [1];
+		await mock.restoreCheckpoint(handle);
+		expect(mock.currentTokens).toEqual([7, 8, 9]);
+	});
+});
+
+describe("prefillOptimistic", () => {
+	it("delegates to the checkpoint manager and returns the post-prefill handle", async () => {
+		const mock = new MockCheckpointManager(() => ({ tokens: [1, 2, 3] }));
+		const result = await prefillOptimistic(
+			{
+				baseUrl: "http://localhost:8080",
+				slotId: "conv-1",
+				partialText: "hello there",
+				eotProb: 0.7,
+			},
+			{ checkpointManager: mock, fetchImpl: makePrefillFetch() },
+		);
+		expect(result.backend).toBe("slot-save-emulation");
+		expect(result.eotProb).toBe(0.7);
+		expect(result.checkpointHandle.slotId).toBe("conv-1");
+		// The handle should be live and restorable.
+		await mock.restoreCheckpoint(result.checkpointHandle);
+		expect(mock.operations.map((o) => o.kind)).toEqual([
+			"save",
+			"save",
+			"restore",
+		]);
+	});
+
+	it("rejects empty partialText and out-of-range eotProb", async () => {
+		const mock = new MockCheckpointManager();
+		await expect(
+			prefillOptimistic(
+				{
+					baseUrl: "http://localhost:8080",
+					slotId: "conv-1",
+					partialText: "  ",
+					eotProb: 0.5,
+				},
+				{ checkpointManager: mock, fetchImpl: makePrefillFetch() },
+			),
+		).rejects.toThrow(/partialText/);
+		await expect(
+			prefillOptimistic(
+				{
+					baseUrl: "http://localhost:8080",
+					slotId: "conv-1",
+					partialText: "hi",
+					eotProb: 1.5,
+				},
+				{ checkpointManager: mock, fetchImpl: makePrefillFetch() },
+			),
+		).rejects.toThrow(/eotProb/);
+	});
+});

package/src/services/voice/__tests__/checkpoint-policy.test.ts

@@ -0,0 +1,270 @@
+/**
+ * Unit tests for `CheckpointPolicy`. The policy is a pure VAD-event →
+ * checkpoint-op translator with no I/O of its own — every test injects a
+ * fake `GatedCheckpointManager` and asserts on the recorded ops.
+ *
+ * NB: per the scaffold task envelope, this test must NOT spawn a real
+ * llama-server or load a real model. Everything is mocked at the JS layer.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type {
+	CheckpointHandle,
+	GatedCheckpointManager,
+	SseDisconnectFn,
+} from "../../checkpoint-manager";
+import { CheckpointPolicy, checkpointNameFor } from "../checkpoint-policy";
+
+/** Op the fake manager recorded — flat tuple for easy `expect(...).toEqual`. */
+type RecordedOp =
+	| { kind: "save"; slotId: number; name: string }
+	| { kind: "restore"; slotId: number; nameOrHandle: string }
+	| { kind: "erase"; slotId: number; nameOrHandle: string }
+	| { kind: "cancel"; slotId: number };
+
+interface FakeManagerOptions {
+	flagOn?: boolean;
+	capabilityOn?: boolean;
+	saveReturns?: CheckpointHandle | null | "throw";
+	restoreReturns?: boolean | "throw";
+	eraseThrows?: boolean;
+	cancelThrows?: boolean;
+}
+
+/**
+ * Build a fake `GatedCheckpointManager`. Records every call into `ops`
+ * and exposes the registry via `getNamedHandle`. The default behavior is
+ * "happy path" — feature flag on, capability on, save returns a handle.
+ */
+function makeFakeManager(opts: FakeManagerOptions = {}): {
+	mgr: GatedCheckpointManager;
+	ops: RecordedOp[];
+	registry: Map<string, CheckpointHandle>;
+} {
+	const ops: RecordedOp[] = [];
+	const registry = new Map<string, CheckpointHandle>();
+	const flagOn = opts.flagOn ?? true;
+	const capabilityOn = opts.capabilityOn ?? true;
+
+	const makeHandle = (slotId: number, name: string): CheckpointHandle => ({
+		slotId: `s${slotId}`,
+		name,
+		id: ops.length + 1,
+		createdAt: new Date(0).toISOString(),
+		backendRef: null,
+	});
+
+	// Cast to the real type via a structural fake — production callers only
+	// touch the methods listed below.
+	const fake: Partial<GatedCheckpointManager> = {
+		isFeatureFlagOn: () => flagOn,
+		isEnabled: () => flagOn && capabilityOn,
+		async save(slotId, name) {
+			ops.push({ kind: "save", slotId, name });
+			if (opts.saveReturns === "throw") {
+				throw new Error("save boom");
+			}
+			if (opts.saveReturns === null) return null;
+			const h = opts.saveReturns ?? makeHandle(slotId, name);
+			registry.set(name, h);
+			return h;
+		},
+		async restore(slotId, handleOrName) {
+			const key =
+				typeof handleOrName === "string" ? handleOrName : handleOrName.name;
+			ops.push({ kind: "restore", slotId, nameOrHandle: key });
+			if (opts.restoreReturns === "throw") {
+				throw new Error("restore boom");
+			}
+			if (opts.restoreReturns === false) return false;
+			return registry.has(key);
+		},
+		async erase(slotId, handleOrName) {
+			const key =
+				typeof handleOrName === "string" ? handleOrName : handleOrName.name;
+			ops.push({ kind: "erase", slotId, nameOrHandle: key });
+			registry.delete(key);
+			if (opts.eraseThrows) throw new Error("erase boom");
+		},
+		async cancel(slotId, sseDisconnect: SseDisconnectFn) {
+			ops.push({ kind: "cancel", slotId });
+			if (opts.cancelThrows) throw new Error("cancel boom");
+			if (!flagOn || !capabilityOn) sseDisconnect(slotId);
+		},
+		getNamedHandle: (name) => registry.get(name) ?? null,
+	};
+
+	return { mgr: fake as GatedCheckpointManager, ops, registry };
+}
+
+describe("checkpointNameFor", () => {
+	it("encodes the turn id as `pre-speculative-T<id>`", () => {
+		expect(checkpointNameFor("123")).toBe("pre-speculative-T123");
+	});
+
+	it("sanitizes turn ids that contain non-filename chars", () => {
+		expect(checkpointNameFor("conv:42/turn-7")).toBe(
+			"pre-speculative-Tconv_42_turn-7",
+		);
+	});
+});
+
+describe("CheckpointPolicy — gate ON", () => {
+	let warn: ReturnType<typeof vi.spyOn>;
+	beforeEach(() => {
+		// Silence the policy's own warn logs — they're not what we're asserting.
+		// The logger import resolves to `@elizaos/core`'s logger; spying on
+		// `console.warn` covers the underlying transport.
+		warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+	});
+	afterEach(() => {
+		warn.mockRestore();
+	});
+
+	it("onSpeechPause issues save with the per-turn name", async () => {
+		const { mgr, ops } = makeFakeManager();
+		const policy = new CheckpointPolicy({ manager: mgr });
+		await policy.onSpeechPause("T1", 3);
+		expect(ops).toEqual([
+			{ kind: "save", slotId: 3, name: "pre-speculative-TT1" },
+		]);
+	});
+
+	it("onSpeechResume restores when speculativeFired=true", async () => {
+		const { mgr, ops } = makeFakeManager();
+		const policy = new CheckpointPolicy({ manager: mgr });
+		await policy.onSpeechPause("T2", 5);
+		await policy.onSpeechResume("T2", 5, { speculativeFired: true });
+		expect(ops).toEqual([
+			{ kind: "save", slotId: 5, name: "pre-speculative-TT2" },
+			{
+				kind: "restore",
+				slotId: 5,
+				nameOrHandle: "pre-speculative-TT2",
+			},
+		]);
+	});
+
+	it("onSpeechResume no-ops when speculativeFired=false", async () => {
+		const { mgr, ops } = makeFakeManager();
+		const noopSink = vi.fn();
+		const policy = new CheckpointPolicy({
+			manager: mgr,
+			events: { onNoop: noopSink },
+		});
+		await policy.onSpeechPause("T3", 1);
+		await policy.onSpeechResume("T3", 1, { speculativeFired: false });
+		expect(ops).toHaveLength(1); // only the save
+		expect(noopSink).toHaveBeenCalledWith("restore", "T3", "no-speculative");
+	});
+
+	it("onSpeechResume emits onNoop=registry-miss when manager.restore returns false", async () => {
+		const { mgr, ops } = makeFakeManager({ restoreReturns: false });
+		const noopSink = vi.fn();
+		const policy = new CheckpointPolicy({
+			manager: mgr,
+			events: { onNoop: noopSink },
+		});
+		await policy.onSpeechResume("T4", 2, { speculativeFired: true });
+		expect(ops).toEqual([
+			{
+				kind: "restore",
+				slotId: 2,
+				nameOrHandle: "pre-speculative-TT4",
+			},
+		]);
+		expect(noopSink).toHaveBeenCalledWith("restore", "T4", "registry-miss");
+	});
+
+	it("onSpeechEndCommit erases the per-turn checkpoint", async () => {
+		const { mgr, ops } = makeFakeManager();
+		const policy = new CheckpointPolicy({ manager: mgr });
+		await policy.onSpeechPause("T5", 4);
+		await policy.onSpeechEndCommit("T5", 4);
+		expect(ops.at(-1)).toEqual({
+			kind: "erase",
+			slotId: 4,
+			nameOrHandle: "pre-speculative-TT5",
+		});
+	});
+
+	it("onHardStop with existing C1 restores then erases (no cancel)", async () => {
+		const { mgr, ops } = makeFakeManager();
+		const sse = vi.fn();
+		const policy = new CheckpointPolicy({ manager: mgr });
+		await policy.onSpeechPause("T6", 7);
+		await policy.onHardStop("T6", 7, sse);
+		const kinds = ops.map((o) => o.kind);
+		expect(kinds).toEqual(["save", "restore", "erase"]);
+		expect(sse).not.toHaveBeenCalled();
+	});
+
+	it("onHardStop with no C1 falls through to manager.cancel", async () => {
+		const { mgr, ops } = makeFakeManager();
+		const sse = vi.fn();
+		const policy = new CheckpointPolicy({ manager: mgr });
+		await policy.onHardStop("T7", 9, sse);
+		expect(ops).toEqual([{ kind: "cancel", slotId: 9 }]);
+	});
+
+	it("emits onError when manager.save throws", async () => {
+		const { mgr } = makeFakeManager({ saveReturns: "throw" });
+		const onError = vi.fn();
+		const policy = new CheckpointPolicy({ manager: mgr, events: { onError } });
+		await policy.onSpeechPause("T8", 1);
+		expect(onError).toHaveBeenCalledWith("save", expect.any(Error), "T8");
+	});
+
+	it("emits onError when manager.restore throws but policy does not rethrow", async () => {
+		const { mgr } = makeFakeManager({ restoreReturns: "throw" });
+		const onError = vi.fn();
+		const policy = new CheckpointPolicy({ manager: mgr, events: { onError } });
+		await expect(
+			policy.onSpeechResume("T9", 2, { speculativeFired: true }),
+		).resolves.toBeUndefined();
+		expect(onError).toHaveBeenCalledWith("restore", expect.any(Error), "T9");
+	});
+
+	it("emits onSaved with the returned handle", async () => {
+		const { mgr } = makeFakeManager();
+		const onSaved = vi.fn();
+		const policy = new CheckpointPolicy({ manager: mgr, events: { onSaved } });
+		await policy.onSpeechPause("T10", 1);
+		expect(onSaved).toHaveBeenCalledWith(
+			"T10",
+			expect.objectContaining({ name: "pre-speculative-TT10" }),
+		);
+	});
+});
+
+describe("CheckpointPolicy — gate OFF (no-op path)", () => {
+	it("onSpeechPause does not call manager.save", async () => {
+		const { mgr, ops } = makeFakeManager({ flagOn: false });
+		const policy = new CheckpointPolicy({ manager: mgr });
+		await policy.onSpeechPause("T1", 3);
+		expect(ops).toHaveLength(0);
+	});
+
+	it("onSpeechResume does not call manager.restore", async () => {
+		const { mgr, ops } = makeFakeManager({ flagOn: false });
+		const policy = new CheckpointPolicy({ manager: mgr });
+		await policy.onSpeechResume("T2", 3, { speculativeFired: true });
+		expect(ops).toHaveLength(0);
+	});
+
+	it("onSpeechEndCommit does not call manager.erase", async () => {
+		const { mgr, ops } = makeFakeManager({ flagOn: false });
+		const policy = new CheckpointPolicy({ manager: mgr });
+		await policy.onSpeechEndCommit("T3", 3);
+		expect(ops).toHaveLength(0);
+	});
+
+	it("onHardStop invokes SSE-disconnect callback synchronously", async () => {
+		const { mgr, ops } = makeFakeManager({ flagOn: false });
+		const sse = vi.fn();
+		const policy = new CheckpointPolicy({ manager: mgr });
+		await policy.onHardStop("T4", 11, sse);
+		expect(sse).toHaveBeenCalledWith(11);
+		expect(ops).toHaveLength(0);
+	});
+});