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

package/src/services/voice/cancellation-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancellation-coordinator.d.ts","sourceRoot":"","sources":["cancellation-coordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EACN,KAAK,uBAAuB,EAC5B,yBAAyB,EACzB,KAAK,sBAAsB,EAC3B,MAAM,iBAAiB,CAAC;AAEzB;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,eAAe,EAAE;QAChB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QACnD,OAAO,CACN,QAAQ,EAAE,CAAC,KAAK,EAAE;YACjB,IAAI,EACD,SAAS,GACT,WAAW,GACX,SAAS,GACT,SAAS,GACT,iBAAiB,CAAC;YACrB,MAAM,EAAE,MAAM,CAAC;YACf,MAAM,CAAC,EAAE,MAAM,CAAC;SAChB,KAAK,IAAI,GACR,MAAM,IAAI,CAAC;KACd,CAAC;CACF;AAED,MAAM,WAAW,mCAAmC;IACnD,8BAA8B;IAC9B,OAAO,EAAE,kBAAkB,CAAC;IAC5B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,uBAAuB,KAAK,IAAI,CAAC;IACtE;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,uBAAuB,KAAK,IAAI,CAAC;IACpD;;;OAGG;IACH,QAAQ,CAAC,EAAE,yBAAyB,CAAC;CACrC;AAgBD,qBAAa,4BAA4B;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmD;IAC7E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiD;IACzE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,kDAAkD;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;gBAE1C,IAAI,EAAE,mCAAmC;IAOrD;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE;QACb,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;KACd,GAAG,sBAAsB;IA8D1B,2DAA2D;IAC3D,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,sBAAsB,GAAG,IAAI;IAItD,kCAAkC;IAClC,YAAY,IAAI,MAAM,EAAE;IAIxB;;;OAGG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,uBAAuB,GAAG,OAAO;IAI/D;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIhC;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIlC;;;;;;;;;OASG;IACH,qBAAqB,CACpB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE;QACX,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;KACnE,GACC,MAAM,IAAI;IAQb;;;OAGG;IACH,OAAO,IAAI,IAAI;CASf"}

package/src/services/voice/cancellation-coordinator.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, it, vi } from "vitest";
+import { BargeInController } from "./barge-in";
+import {
+	type CoordinatorRuntime,
+	VoiceCancellationCoordinator,
+} from "./cancellation-coordinator";
+
+type RuntimeEvent = Parameters<
+	Parameters<CoordinatorRuntime["turnControllers"]["onEvent"]>[0]
+>[0];
+
+/** Tiny fake matching the runtime structural surface. */
+function makeFakeRuntime(): CoordinatorRuntime & {
+	emitEvent(event: RuntimeEvent): void;
+	abortCalls: Array<{ roomId: string; reason: string }>;
+} {
+	const listeners = new Set<(e: RuntimeEvent) => void>();
+	const abortCalls: Array<{ roomId: string; reason: string }> = [];
+	return {
+		turnControllers: {
+			abortTurn(roomId, reason) {
+				abortCalls.push({ roomId, reason });
+				return true;
+			},
+			onEvent(listener) {
+				listeners.add(listener);
+				return () => listeners.delete(listener);
+			},
+		},
+		emitEvent(event) {
+			for (const l of listeners) l(event);
+		},
+		abortCalls,
+	};
+}
+
+describe("VoiceCancellationCoordinator — barge-in fan-out", () => {
+	it("arming a turn returns a live token tied to the room", () => {
+		const rt = makeFakeRuntime();
+		const c = new VoiceCancellationCoordinator({ runtime: rt });
+		const token = c.armTurn({ roomId: "r1", runId: "t1" });
+		expect(token.aborted).toBe(false);
+		expect(c.current("r1")).toBe(token);
+		expect(c.armedRoomIds()).toEqual(["r1"]);
+	});
+
+	it("bargeIn aborts the token, fires runtime.abortTurn, slotAbort, ttsStop", () => {
+		const rt = makeFakeRuntime();
+		const slotAbort = vi.fn();
+		const ttsStop = vi.fn();
+		const c = new VoiceCancellationCoordinator({
+			runtime: rt,
+			slotAbort,
+			ttsStop,
+		});
+		const token = c.armTurn({ roomId: "r1", runId: "t1", slot: 3 });
+
+		const ok = c.bargeIn("r1");
+		expect(ok).toBe(true);
+		expect(token.aborted).toBe(true);
+		expect(token.reason).toBe("barge-in");
+		expect(rt.abortCalls).toEqual([{ roomId: "r1", reason: "barge-in" }]);
+		expect(slotAbort).toHaveBeenCalledWith(3, "barge-in");
+		expect(ttsStop).toHaveBeenCalledWith("barge-in");
+	});
+
+	it("does NOT call slotAbort when no slot was registered on the turn", () => {
+		const rt = makeFakeRuntime();
+		const slotAbort = vi.fn();
+		const c = new VoiceCancellationCoordinator({ runtime: rt, slotAbort });
+		c.armTurn({ roomId: "r1", runId: "t1" });
+		c.bargeIn("r1");
+		expect(slotAbort).not.toHaveBeenCalled();
+	});
+
+	it("revokeEot aborts with reason=eot-revoked", () => {
+		const rt = makeFakeRuntime();
+		const c = new VoiceCancellationCoordinator({ runtime: rt });
+		const token = c.armTurn({ roomId: "r1", runId: "t1" });
+		c.revokeEot("r1");
+		expect(token.reason).toBe("eot-revoked");
+		expect(rt.abortCalls).toEqual([{ roomId: "r1", reason: "eot-revoked" }]);
+	});
+
+	it("re-arming a room aborts the previous token (reason=external)", () => {
+		const rt = makeFakeRuntime();
+		const c = new VoiceCancellationCoordinator({ runtime: rt });
+		const first = c.armTurn({ roomId: "r1", runId: "t1" });
+		const second = c.armTurn({ roomId: "r1", runId: "t2" });
+		expect(first.aborted).toBe(true);
+		expect(first.reason).toBe("external");
+		expect(second.aborted).toBe(false);
+	});
+
+	it("propagates runtime-driven aborts into the voice token", () => {
+		const rt = makeFakeRuntime();
+		const c = new VoiceCancellationCoordinator({ runtime: rt });
+		const token = c.armTurn({ roomId: "r1", runId: "t1" });
+		rt.emitEvent({ type: "aborted", roomId: "r1", reason: "app-pause" });
+		expect(token.aborted).toBe(true);
+		expect(token.reason).toBe("external");
+	});
+
+	it("propagates runtime aborts with known voice reasons preserving the reason", () => {
+		const rt = makeFakeRuntime();
+		const c = new VoiceCancellationCoordinator({ runtime: rt });
+		const token = c.armTurn({ roomId: "r1", runId: "t1" });
+		rt.emitEvent({ type: "aborted", roomId: "r1", reason: "voice-barge-in" });
+		expect(token.reason).toBe("barge-in");
+	});
+
+	it("ignores runtime aborts for other rooms", () => {
+		const rt = makeFakeRuntime();
+		const c = new VoiceCancellationCoordinator({ runtime: rt });
+		const tokenA = c.armTurn({ roomId: "rA", runId: "tA" });
+		const tokenB = c.armTurn({ roomId: "rB", runId: "tB" });
+		rt.emitEvent({ type: "aborted", roomId: "rA", reason: "x" });
+		expect(tokenA.aborted).toBe(true);
+		expect(tokenB.aborted).toBe(false);
+	});
+
+	it("dispose tears down every active turn", () => {
+		const rt = makeFakeRuntime();
+		const c = new VoiceCancellationCoordinator({ runtime: rt });
+		const a = c.armTurn({ roomId: "rA", runId: "tA" });
+		const b = c.armTurn({ roomId: "rB", runId: "tB" });
+		c.dispose();
+		expect(a.aborted).toBe(true);
+		expect(b.aborted).toBe(true);
+		expect(c.armedRoomIds()).toEqual([]);
+	});
+
+	it("idempotent abort — second bargeIn is a no-op", () => {
+		const rt = makeFakeRuntime();
+		const slotAbort = vi.fn();
+		const c = new VoiceCancellationCoordinator({ runtime: rt, slotAbort });
+		c.armTurn({ roomId: "r1", runId: "t1", slot: 0 });
+		expect(c.bargeIn("r1")).toBe(true);
+		expect(c.bargeIn("r1")).toBe(false);
+		// slotAbort called exactly once for the first abort
+		expect(slotAbort).toHaveBeenCalledTimes(1);
+	});
+
+	it("bindBargeInController translates hard-stop into coordinator.bargeIn", () => {
+		const rt = makeFakeRuntime();
+		const slotAbort = vi.fn();
+		const ttsStop = vi.fn();
+		const c = new VoiceCancellationCoordinator({
+			runtime: rt,
+			slotAbort,
+			ttsStop,
+		});
+		const bic = new BargeInController();
+		const token = c.armTurn({ roomId: "r1", runId: "t1", slot: 9 });
+		const unsub = c.bindBargeInController("r1", bic);
+
+		// Simulate the agent speaking + an authoritative ASR word event so the
+		// controller's onWordsDetected promotes pause-tts into hard-stop.
+		bic.setAgentSpeaking(true);
+		// Pretend VAD just reported speech-active (sets the deadline window).
+		// We dispatch directly via `hardStop` for a deterministic test —
+		// barge-in.test.ts covers the VAD→words ladder.
+		bic.hardStop("barge-in-words");
+		expect(token.aborted).toBe(true);
+		expect(token.reason).toBe("barge-in");
+		expect(rt.abortCalls).toEqual([{ roomId: "r1", reason: "barge-in" }]);
+		expect(slotAbort).toHaveBeenCalledWith(9, "barge-in");
+		expect(ttsStop).toHaveBeenCalledWith("barge-in");
+
+		unsub();
+		// Subsequent hard-stops on a torn-down binding are inert.
+		const second = c.armTurn({ roomId: "r1", runId: "t2", slot: 9 });
+		bic.reset();
+		bic.hardStop("manual");
+		expect(second.aborted).toBe(false);
+	});
+
+	it("listener errors do not block fan-out", () => {
+		const rt = makeFakeRuntime();
+		// First fan-out callback throws; ttsStop must still fire.
+		const ttsStop = vi.fn();
+		const slotAbort = vi.fn(() => {
+			throw new Error("slot-abort transport failed");
+		});
+		const c = new VoiceCancellationCoordinator({
+			runtime: rt,
+			slotAbort,
+			ttsStop,
+		});
+		c.armTurn({ roomId: "r1", runId: "t1", slot: 4 });
+		c.bargeIn("r1");
+		expect(slotAbort).toHaveBeenCalled();
+		expect(ttsStop).toHaveBeenCalled();
+		expect(rt.abortCalls.length).toBe(1);
+	});
+});

package/src/services/voice/cancellation-coordinator.ts

@@ -0,0 +1,269 @@
+/**
+ * Voice cancellation coordinator — Wave 3 W3-9.
+ *
+ * Single brain that owns one `VoiceCancellationToken` per active voice turn
+ * and binds every cancellation source into it:
+ *
+ *   1. VAD start-of-speech while the agent is speaking (barge-in).
+ *   2. `BargeInController.hardStop` (ASR-confirmed barge-in words).
+ *   3. Turn-detector EOT revocation (user resumed mid-tentative-pause).
+ *   4. Runtime turn abort (`TurnControllerRegistry` "aborted" event).
+ *
+ * On any cancel, it fans out to:
+ *
+ *   1. The voice token's `AbortSignal` — every fetch / model call wired to
+ *      `signal` aborts at the next yield point.
+ *   2. `runtime.turnControllers.abortTurn(roomId, reason)` — the runtime's
+ *      planner-loop / action handlers see the abort within one tick
+ *      (between model calls / between actions / between provider calls).
+ *   3. Optional `slotAbort(slotId)` — invokes the registered LM
+ *      slot-abort callback (typically `MtpLlamaServer.abortSlot` which
+ *      either aborts in-flight HTTP fetches against that slot or, on a
+ *      capable fork, calls the slot-cancel REST route).
+ *   4. Optional `ttsStop()` — invokes the registered TTS-stop callback
+ *      (typically `EngineVoiceBridge.triggerBargeIn` which drains the
+ *      audio sink + cancels the FFI/HTTP synthesis path).
+ *
+ * The coordinator is intentionally a plain class — no engine coupling. The
+ * engine bridge (and tests) construct one with the structural runtime + the
+ * appropriate callbacks.
+ */
+
+import {
+	type VoiceCancellationReason,
+	VoiceCancellationRegistry,
+	type VoiceCancellationToken,
+} from "@elizaos/shared";
+
+/**
+ * Minimum runtime surface this coordinator needs. Matches a subset of
+ * `AgentRuntime.turnControllers`. Structural so unit tests can pass a fake.
+ */
+export interface CoordinatorRuntime {
+	turnControllers: {
+		abortTurn(roomId: string, reason: string): boolean;
+		onEvent(
+			listener: (event: {
+				type:
+					| "started"
+					| "completed"
+					| "errored"
+					| "aborted"
+					| "aborted-cleanup";
+				roomId: string;
+				reason?: string;
+			}) => void,
+		): () => void;
+	};
+}
+
+export interface VoiceCancellationCoordinatorOptions {
+	/** The runtime to bind to. */
+	runtime: CoordinatorRuntime;
+	/**
+	 * Abort the inference server slot. Wired to `MtpLlamaServer.abortSlot`
+	 * in production. Async — the coordinator does NOT await it (the slot
+	 * abort path is best-effort; the AbortSignal closure on the fetch is the
+	 * authoritative cancel).
+	 */
+	slotAbort?: (slotId: number, reason: VoiceCancellationReason) => void;
+	/**
+	 * Hard-stop the TTS pipeline (audio sink drain + FFI/HTTP synthesis
+	 * cancel). Wired to `EngineVoiceBridge.triggerBargeIn`. Synchronous —
+	 * the audio sink drain MUST happen within one tick of `abort()`.
+	 */
+	ttsStop?: (reason: VoiceCancellationReason) => void;
+	/**
+	 * Optional pre-existing registry. Tests inject one to inspect token
+	 * lifecycle directly. Production creates a fresh registry per session.
+	 */
+	registry?: VoiceCancellationRegistry;
+}
+
+/**
+ * Per-turn metadata. Recorded when `armTurn` is called so that the
+ * coordinator can map a generic `runtime.turnControllers` "aborted" event
+ * for a room back to the voice token (and so the slot-abort path knows
+ * which slot to target).
+ */
+interface ArmedTurn {
+	roomId: string;
+	runId: string;
+	slot?: number;
+	token: VoiceCancellationToken;
+	unsubRuntime: () => void;
+}
+
+export class VoiceCancellationCoordinator {
+	private readonly runtime: CoordinatorRuntime;
+	private readonly slotAbort: VoiceCancellationCoordinatorOptions["slotAbort"];
+	private readonly ttsStop: VoiceCancellationCoordinatorOptions["ttsStop"];
+	private readonly registry: VoiceCancellationRegistry;
+	/** Active turns keyed by roomId. One per room. */
+	private readonly armed = new Map<string, ArmedTurn>();
+
+	constructor(opts: VoiceCancellationCoordinatorOptions) {
+		this.runtime = opts.runtime;
+		this.slotAbort = opts.slotAbort;
+		this.ttsStop = opts.ttsStop;
+		this.registry = opts.registry ?? new VoiceCancellationRegistry();
+	}
+
+	/**
+	 * Begin a new voice turn for `roomId`. If a previous turn was active,
+	 * it is aborted with `"external"` (the regular replace-on-arm semantics
+	 * inherited from `VoiceCancellationRegistry`).
+	 */
+	armTurn(args: {
+		roomId: string;
+		runId: string;
+		slot?: number;
+	}): VoiceCancellationToken {
+		// Tear down any previous arming for the same room before reusing it.
+		const prior = this.armed.get(args.roomId);
+		if (prior) {
+			prior.unsubRuntime();
+			this.armed.delete(args.roomId);
+		}
+
+		const token = this.registry.arm(args.roomId, {
+			runId: args.runId,
+			...(args.slot !== undefined ? { slot: args.slot } : {}),
+		});
+
+		// Fan out: when the token aborts, abort the runtime turn + slot + TTS.
+		token.onAbort((reason) => {
+			// Runtime turn abort — fires the planner-loop / action-handler
+			// abort signal merged into StreamingContext.
+			try {
+				this.runtime.turnControllers.abortTurn(args.roomId, reason);
+			} catch {
+				// Telemetry shouldn't fail cancellation.
+			}
+			if (args.slot !== undefined && this.slotAbort) {
+				try {
+					this.slotAbort(args.slot, reason);
+				} catch {
+					// Slot abort is best-effort.
+				}
+			}
+			if (this.ttsStop) {
+				try {
+					this.ttsStop(reason);
+				} catch {
+					// TTS hard-stop is best-effort; the audio sink owns the SIGKILL.
+				}
+			}
+		});
+
+		// Reverse direction: when the runtime aborts the turn (e.g. APP_PAUSE,
+		// orchestrator-initiated cancel), trip the voice token. This is the
+		// "runtime → voice" leg the R11 audit called out as missing.
+		const unsubRuntime = this.runtime.turnControllers.onEvent((event) => {
+			if (event.roomId !== args.roomId) return;
+			if (event.type === "aborted" || event.type === "aborted-cleanup") {
+				const reason = mapRuntimeReason(event.reason);
+				if (!token.aborted) {
+					token.abort(reason);
+				}
+			}
+		});
+
+		this.armed.set(args.roomId, {
+			roomId: args.roomId,
+			runId: args.runId,
+			...(args.slot !== undefined ? { slot: args.slot } : {}),
+			token,
+			unsubRuntime,
+		});
+
+		return token;
+	}
+
+	/** Fetch the current voice token for `roomId`, or null. */
+	current(roomId: string): VoiceCancellationToken | null {
+		return this.registry.current(roomId);
+	}
+
+	/** Snapshot of armed room ids. */
+	armedRoomIds(): string[] {
+		return Array.from(this.armed.keys());
+	}
+
+	/**
+	 * Abort the active turn for `roomId` with the given reason. Idempotent.
+	 * Returns true when a live token was aborted.
+	 */
+	abort(roomId: string, reason: VoiceCancellationReason): boolean {
+		return this.registry.abort(roomId, reason);
+	}
+
+	/**
+	 * Trip the active token because VAD reported start-of-speech while the
+	 * agent was speaking. Equivalent to `abort(roomId, "barge-in")` but
+	 * keeps the call-site grep-able as the canonical barge-in entry point.
+	 */
+	bargeIn(roomId: string): boolean {
+		return this.abort(roomId, "barge-in");
+	}
+
+	/**
+	 * Trip the active token because the turn detector revoked the previous
+	 * EOT decision (user resumed within the rollback window).
+	 */
+	revokeEot(roomId: string): boolean {
+		return this.abort(roomId, "eot-revoked");
+	}
+
+	/**
+	 * Wire a `BargeInController.onSignal` listener into this coordinator.
+	 * The controller emits `hard-stop` when ASR confirms barge-in words;
+	 * this glue translates it into `coordinator.bargeIn(roomId)` so the
+	 * canonical token (and every downstream consumer) sees the abort.
+	 *
+	 * Returns the unsubscribe function from `onSignal`. Production callers
+	 * (the engine bridge) call this once per `BargeInController` per
+	 * room and keep the handle until session teardown.
+	 */
+	bindBargeInController(
+		roomId: string,
+		controller: {
+			onSignal(listener: (signal: { type: string }) => void): () => void;
+		},
+	): () => void {
+		return controller.onSignal((signal) => {
+			if (signal.type === "hard-stop") {
+				this.bargeIn(roomId);
+			}
+		});
+	}
+
+	/**
+	 * Tear down. Cancels every armed turn and unsubscribes from the
+	 * runtime. Safe to call multiple times.
+	 */
+	dispose(): void {
+		for (const arm of Array.from(this.armed.values())) {
+			arm.unsubRuntime();
+			if (!arm.token.aborted) {
+				arm.token.abort("external");
+			}
+		}
+		this.armed.clear();
+	}
+}
+
+/**
+ * Map a freeform runtime-abort reason string into a `VoiceCancellationReason`.
+ * Conservative: anything that looks like a known voice reason stays as-is,
+ * everything else is `"external"` (the runtime decided independently of the
+ * voice loop).
+ */
+function mapRuntimeReason(reason: string | undefined): VoiceCancellationReason {
+	if (!reason) return "external";
+	if (reason === "barge-in" || reason === "voice-barge-in") return "barge-in";
+	if (reason === "eot-revoked") return "eot-revoked";
+	if (reason === "user-cancel") return "user-cancel";
+	if (reason === "timeout") return "timeout";
+	return "external";
+}

package/src/services/voice/checkpoint-manager.d.ts

@@ -0,0 +1,199 @@
+/**
+ * CheckpointManager — high-level slot-agnostic KV-cache checkpoint primitive
+ * used by the voice state machine (`voice-state-machine.ts`) to implement the
+ * optimistic-rollback path described in `docs/eliza-1-optimistic-rollback.md`.
+ *
+ * Why a manager on top of `CheckpointClient`?
+ *
+ *   - `CheckpointClient` (in `checkpoint-client.ts`) is a thin REST
+ *     adapter. It is keyed by `(slotId, filename)` because that is what the
+ *     fork's `POST /slots/<id>/save?filename=<n>` REST API expects.
+ *   - Callers (the voice state machine, voice-bench drivers) don't want to
+ *     mint filenames, track active handles, or know about the upstream URL
+ *     scheme. They want `save("pre-draft") → handle`, `restore(handle)`,
+ *     `discard(handle)` and an in-memory mock for unit tests.
+ *   - Backend reference shape is isolated here: the voice state machine keeps
+ *     the same public interface (`saveCheckpoint`, `restoreCheckpoint`,
+ *     `discardCheckpoint`) while this module owns how the REST backend stores
+ *     and addresses the snapshot.
+ *
+ * The handle returned from `saveCheckpoint` carries enough information to
+ * `restore` and `discard` the same snapshot later even after the underlying
+ * URL scheme changes. The current backend reference points at
+ * `(slotId, filename)` and can evolve without changing callers.
+ *
+ * **MockCheckpointManager** stores a caller-supplied snapshot (token sequence
+ * + arbitrary metadata) in memory keyed by the handle. Tests use it to drive
+ * the voice state machine deterministically without spinning up a real
+ * checkpoint runtime.
+ */
+import { type CheckpointFetch, type CheckpointHandle as RestCheckpointHandle } from "../checkpoint-client";
+/**
+ * Opaque-to-callers handle returned by `saveCheckpoint`. The fields are
+ * exposed so tests can assert on them but callers should treat the handle
+ * as an opaque blob.
+ */
+export interface CheckpointHandle {
+    /**
+     * Caller-supplied conversation/turn-scoped slot id. Maps onto the REST
+     * `slotId` today; on v1 it maps onto the upstream checkpoint-server's
+     * session id.
+     */
+    slotId: string;
+    /**
+     * Human-readable name passed to `saveCheckpoint`. Used as part of the
+     * REST filename today (`C1-<slotId>-<name>`).
+     */
+    name: string;
+    /**
+     * Monotonically increasing per-manager id. Lets tests assert that two
+     * checkpoints from the same `(slotId, name)` are distinct.
+     */
+    id: number;
+    /** ISO timestamp of the save call. */
+    createdAt: string;
+    /**
+     * Backend-specific reference. For the REST-backed manager this is the
+     * `CheckpointClient` handle (`{slotId: number, filename: string,
+     * createdAt: string}`). For the mock manager this is `null` (the mock
+     * is keyed by the handle's `id` field).
+     */
+    readonly backendRef: RestCheckpointHandle | null;
+}
+/**
+ * Common interface implemented by both `CheckpointManager` (REST-backed)
+ * and `MockCheckpointManager` (in-memory). The voice state machine accepts
+ * this interface so tests can substitute the mock.
+ */
+export interface CheckpointManagerLike {
+    /**
+     * Snapshot the slot's KV state. Returns a handle the caller passes back
+     * to `restoreCheckpoint` / `discardCheckpoint`. Each call returns a new
+     * handle; identical `(slotId, name)` pairs do NOT alias.
+     */
+    saveCheckpoint(slotId: string, name: string): Promise<CheckpointHandle>;
+    /**
+     * Restore a previously-saved snapshot. After `restore`, the handle is
+     * still valid — the same checkpoint can be restored again (e.g. for two
+     * consecutive barge-ins against the same C1).
+     */
+    restoreCheckpoint(handle: CheckpointHandle): Promise<void>;
+    /**
+     * Free server-side storage for `handle`. After `discard`, the handle is
+     * invalid; subsequent restore/discard calls reject with
+     * `CheckpointHandleInvalidError`.
+     */
+    discardCheckpoint(handle: CheckpointHandle): Promise<void>;
+}
+/**
+ * Raised when a caller passes a handle that this manager did not create,
+ * or that has already been `discardCheckpoint`-ed. Distinct from REST
+ * errors (which surface as `CheckpointHttpError` from the client).
+ */
+export declare class CheckpointHandleInvalidError extends Error {
+    constructor(message: string);
+}
+export interface CheckpointManagerOptions {
+    /**
+     * Base URL of the checkpoint runtime. Same shape as
+     * `CheckpointClient` — `http://host:port`.
+     */
+    baseUrl: string;
+    /**
+     * Slot-id-string → numeric slot-id mapping. The REST layer takes a
+     * non-negative integer; voice callers prefer string ids that travel
+     * with the conversation/turn id. Defaults to a hash of the string.
+     */
+    resolveSlotId?: (slotIdString: string) => number;
+    /** Optional custom fetch (mostly for unit-testing the REST surface). */
+    fetchImpl?: CheckpointFetch;
+    /**
+     * Default per-request timeout (ms). Forwarded to `CheckpointClient`. The
+     * REST checkpoint REST surface is latency-critical on the restore path —
+     * keep this short.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Source of monotonically increasing ids. Injected for deterministic
+     * tests; defaults to a per-manager counter.
+     */
+    now?: () => Date;
+}
+/**
+ * REST-backed `CheckpointManager`. Wraps `CheckpointClient` and exposes
+ * the slot-agnostic save/restore/discard contract. The class is stateful
+ * only in so far as it tracks which handles are still live so a double-
+ * `discard` is detected; the actual snapshot lives in the runtime's
+ * `--slot-save-path` directory.
+ */
+export declare class CheckpointManager implements CheckpointManagerLike {
+    private readonly client;
+    private readonly resolveSlotId;
+    private readonly now;
+    private nextId;
+    private readonly live;
+    constructor(opts: CheckpointManagerOptions);
+    saveCheckpoint(slotId: string, name: string): Promise<CheckpointHandle>;
+    restoreCheckpoint(handle: CheckpointHandle): Promise<void>;
+    discardCheckpoint(handle: CheckpointHandle): Promise<void>;
+    /**
+     * Probe the underlying runtime for checkpoint support. Forwarded
+     * from `CheckpointClient.probeSupported`. Callers gate the feature flag
+     * on this.
+     */
+    probeSupported(signal?: AbortSignal): Promise<boolean>;
+    private assertLive;
+}
+/**
+ * Caller-supplied snapshot the mock stores against a handle. The voice
+ * state machine tests use this to record the token sequence at the
+ * `speech-pause` instant and assert that a barge-in restores the same
+ * sequence.
+ */
+export interface MockCheckpointSnapshot {
+    /** Token ids at the time of `saveCheckpoint`. */
+    tokens: readonly number[];
+    /** Free-form metadata (partial transcript, turn id, etc.). */
+    metadata?: Record<string, unknown>;
+}
+export type MockSnapshotSource = (slotId: string, name: string) => MockCheckpointSnapshot;
+/**
+ * In-memory `CheckpointManager` for tests. Records every save / restore /
+ * discard call so tests can assert on them, and stores a snapshot of the
+ * token sequence keyed by handle.
+ */
+export declare class MockCheckpointManager implements CheckpointManagerLike {
+    private readonly snapshotSource?;
+    private nextId;
+    private readonly snapshots;
+    /**
+     * Operations recorded in arrival order. Useful for assertions like
+     * "discard happened after restore".
+     */
+    readonly operations: Array<{
+        kind: "save";
+        slotId: string;
+        name: string;
+        handleId: number;
+    } | {
+        kind: "restore";
+        handleId: number;
+    } | {
+        kind: "discard";
+        handleId: number;
+    }>;
+    /**
+     * Token sequence the active "slot" most recently restored to. Lets
+     * tests assert that a restore actually replayed the saved tokens.
+     */
+    currentTokens: readonly number[];
+    constructor(snapshotSource?: MockSnapshotSource | undefined);
+    saveCheckpoint(slotId: string, name: string): Promise<CheckpointHandle>;
+    restoreCheckpoint(handle: CheckpointHandle): Promise<void>;
+    discardCheckpoint(handle: CheckpointHandle): Promise<void>;
+    /** Live handles count — for leak assertions. */
+    liveHandleCount(): number;
+    /** Look up the snapshot saved against `handle.id`. */
+    snapshotFor(handle: CheckpointHandle): MockCheckpointSnapshot | undefined;
+}
+//# sourceMappingURL=checkpoint-manager.d.ts.map

package/src/services/voice/checkpoint-manager.d.ts.map

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