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

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);
+	});
+});

package/src/services/voice/__tests__/eager-context-builder.test.ts

@@ -0,0 +1,257 @@
+/**
+ * Unit tests for `EagerContextBuilder` (C3 — eager provider context split).
+ *
+ * Invariants under test:
+ *   1. `prebuildDeterministic` runs on speech-start and caches the result.
+ *   2. `complete()` uses the cached deterministic part without rebuilding.
+ *   3. A stale cache (> staleCutoffMs) triggers a rebuild inside `complete()`.
+ *   4. Concurrent `prebuildDeterministic` calls collapse into one build.
+ *   5. `invalidate()` clears the cache so the next `complete()` rebuilds.
+ *   6. `mergeContext` assembles systemText + history in the correct order.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+	type ContextPartial,
+	EagerContextBuilder,
+	mergeContext,
+} from "../eager-context-builder";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makePartial(label: string): ContextPartial {
+	return {
+		systemBlocks: [`[${label}-system]`],
+		historyBlocks: [{ role: "assistant", content: `[${label}-history]` }],
+		meta: { label },
+	};
+}
+
+function makeBuilder(
+	opts: {
+		detCallCount?: { n: number };
+		msgCallCount?: { n: number };
+		staleCutoffMs?: number;
+		now?: () => number;
+	} = {},
+) {
+	const detCalls = opts.detCallCount ?? { n: 0 };
+	const msgCalls = opts.msgCallCount ?? { n: 0 };
+
+	const builder = new EagerContextBuilder({
+		buildDeterministic: async () => {
+			detCalls.n += 1;
+			return makePartial("det");
+		},
+		buildMessageDependent: async (msg: string) => {
+			msgCalls.n += 1;
+			return {
+				systemBlocks: [],
+				historyBlocks: [{ role: "user", content: msg }],
+			};
+		},
+		staleCutoffMs: opts.staleCutoffMs ?? 30_000,
+		now: opts.now,
+	});
+
+	return { builder, detCalls, msgCalls };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("EagerContextBuilder", () => {
+	it("prebuildDeterministic runs once and caches the result", async () => {
+		const detCalls = { n: 0 };
+		const { builder } = makeBuilder({ detCallCount: detCalls });
+
+		// Trigger prebuild.
+		builder.prebuildDeterministic();
+		// Wait for the internal promise to settle.
+		await new Promise((r) => setTimeout(r, 10));
+		expect(detCalls.n).toBe(1);
+		expect(builder.isStale()).toBe(false);
+	});
+
+	it("complete() uses the cached deterministic part without rebuilding", async () => {
+		const detCalls = { n: 0 };
+		const { builder } = makeBuilder({ detCallCount: detCalls });
+
+		builder.prebuildDeterministic();
+		await new Promise((r) => setTimeout(r, 10));
+		expect(detCalls.n).toBe(1);
+
+		const ctx = await builder.complete("hello world");
+		// No rebuild — still only one deterministic call.
+		expect(detCalls.n).toBe(1);
+		expect(ctx.deterministicWasStale).toBe(false);
+		// Deterministic system block is present.
+		expect(ctx.systemText).toContain("[det-system]");
+		// User message is last history entry.
+		expect(ctx.history.at(-1)).toEqual({
+			role: "user",
+			content: "hello world",
+		});
+	});
+
+	it("complete() rebuilds when the cache is stale (> staleCutoffMs)", async () => {
+		let fakeNow = 0;
+		const detCalls = { n: 0 };
+		const { builder } = makeBuilder({
+			detCallCount: detCalls,
+			staleCutoffMs: 1_000,
+			now: () => fakeNow,
+		});
+
+		builder.prebuildDeterministic();
+		await new Promise((r) => setTimeout(r, 10));
+		expect(detCalls.n).toBe(1);
+
+		// Advance fake clock past staleness threshold.
+		fakeNow = 1_001;
+		expect(builder.isStale()).toBe(true);
+
+		const ctx = await builder.complete("stale message");
+		// Should have rebuilt.
+		expect(detCalls.n).toBe(2);
+		// deterministicWasStale is true because there WAS a cached value that was stale.
+		expect(ctx.deterministicWasStale).toBe(true);
+	});
+
+	it("complete() without any prebuild rebuilds and marks deterministicWasStale=false (never built)", async () => {
+		const detCalls = { n: 0 };
+		const { builder } = makeBuilder({ detCallCount: detCalls });
+
+		// No prebuild at all.
+		const ctx = await builder.complete("first message");
+		// Built inline.
+		expect(detCalls.n).toBe(1);
+		// Never built before → not stale, just absent.
+		expect(ctx.deterministicWasStale).toBe(false);
+	});
+
+	it("concurrent prebuildDeterministic calls collapse into a single build", async () => {
+		const detCalls = { n: 0 };
+		const { builder } = makeBuilder({ detCallCount: detCalls });
+
+		// Fire three times without awaiting.
+		builder.prebuildDeterministic();
+		builder.prebuildDeterministic();
+		builder.prebuildDeterministic();
+		await new Promise((r) => setTimeout(r, 20));
+
+		// Only one build should have run.
+		expect(detCalls.n).toBe(1);
+	});
+
+	it("invalidate() clears the cache so the next complete() rebuilds", async () => {
+		const detCalls = { n: 0 };
+		const { builder } = makeBuilder({ detCallCount: detCalls });
+
+		builder.prebuildDeterministic();
+		await new Promise((r) => setTimeout(r, 10));
+		expect(detCalls.n).toBe(1);
+
+		builder.invalidate();
+		expect(builder.isStale()).toBe(true);
+
+		await builder.complete("fresh message");
+		expect(detCalls.n).toBe(2);
+	});
+
+	it("complete() awaits an in-flight prebuild before merging", async () => {
+		let resolveDetBuild!: (v: ContextPartial) => void;
+		const slowDet = new Promise<ContextPartial>((res) => {
+			resolveDetBuild = res;
+		});
+
+		let detCallCount = 0;
+		const builder = new EagerContextBuilder({
+			buildDeterministic: async () => {
+				detCallCount += 1;
+				return slowDet;
+			},
+			buildMessageDependent: async (msg: string) => ({
+				systemBlocks: [],
+				historyBlocks: [{ role: "user" as const, content: msg }],
+			}),
+		});
+
+		// Start prebuild (won't finish until we resolve `slowDet`).
+		builder.prebuildDeterministic();
+
+		// complete() should wait for the prebuild.
+		const completePromise = builder.complete("concurrent user message");
+		// Let the microtask queue drain without resolving the build.
+		await new Promise((r) => setTimeout(r, 5));
+
+		// Resolve the prebuild.
+		resolveDetBuild(makePartial("slow-det"));
+
+		const ctx = await completePromise;
+		// Only one deterministic build ran.
+		expect(detCallCount).toBe(1);
+		expect(ctx.systemText).toContain("[slow-det-system]");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// mergeContext
+// ---------------------------------------------------------------------------
+
+describe("mergeContext", () => {
+	it("joins system blocks with double-newline (det before msg-dep)", () => {
+		const det: ContextPartial = {
+			systemBlocks: ["SYSTEM_A", "SYSTEM_B"],
+			historyBlocks: [{ role: "assistant", content: "HIST_A" }],
+		};
+		const msgDep: ContextPartial = {
+			systemBlocks: ["SYSTEM_C"],
+			historyBlocks: [{ role: "user", content: "USER_MSG" }],
+		};
+		const ts = {
+			deterministicBuiltAt: "2026-01-01T00:00:00.000Z",
+			completedAt: "2026-01-01T00:00:01.000Z",
+			deterministicWasStale: false,
+		};
+		const full = mergeContext(det, msgDep, ts);
+		expect(full.systemText).toBe("SYSTEM_A\n\nSYSTEM_B\n\nSYSTEM_C");
+		expect(full.history).toEqual([
+			{ role: "assistant", content: "HIST_A" },
+			{ role: "user", content: "USER_MSG" },
+		]);
+		expect(full.deterministicWasStale).toBe(false);
+	});
+
+	it("handles empty system blocks gracefully", () => {
+		const det: ContextPartial = { systemBlocks: [], historyBlocks: [] };
+		const msgDep: ContextPartial = {
+			systemBlocks: [],
+			historyBlocks: [{ role: "user", content: "only user" }],
+		};
+		const full = mergeContext(det, msgDep, {
+			deterministicBuiltAt: "",
+			completedAt: "",
+			deterministicWasStale: false,
+		});
+		expect(full.systemText).toBe("");
+		expect(full.history).toEqual([{ role: "user", content: "only user" }]);
+	});
+
+	it("filters out empty string blocks from systemText", () => {
+		const det: ContextPartial = {
+			systemBlocks: ["", "REAL"],
+			historyBlocks: [],
+		};
+		const msgDep: ContextPartial = { systemBlocks: [""], historyBlocks: [] };
+		const full = mergeContext(det, msgDep, {
+			deterministicBuiltAt: "",
+			completedAt: "",
+			deterministicWasStale: false,
+		});
+		expect(full.systemText).toBe("REAL");
+	});
+});