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

package/src/services/cloud-fallback.ts

@@ -0,0 +1,230 @@
+/**
+ * Soft cloud-fallback wrapper for local-inference TEXT_LARGE / TEXT_SMALL.
+ *
+ * Why this exists: on mobile (AOSP / iOS) the local llama backend has very
+ * different failure modes from a desktop process. The model GGUF may not be
+ * staged yet, the FFI dlopen may have failed, the device may be in low-power
+ * mode and refuse to prefill, or the user may have explicitly disabled the
+ * local engine. We do not want any of those states to surface as a
+ * "No handler found for delegate type: TEXT_LARGE" runtime error — when an
+ * Anthropic / OpenAI / Eliza Cloud handler is also registered, the runtime
+ * should transparently fall through to cloud.
+ *
+ * Design constraints (per AGENTS.md):
+ *  - No silent try/catch. The wrapper distinguishes "ran successfully" from
+ *    "ran and decided to fallback" via an EXPLICIT typed return:
+ *      { kind: "ok"; text: string }
+ *      | { kind: "fallback"; reason: FallbackReason }
+ *    Callers branch on `kind`. The wrapper does NOT swallow errors —
+ *    any unhandled throw bubbles up to the runtime.
+ *  - Local errors are CLASSIFIED. Unrecoverable bugs (programming errors,
+ *    out-of-memory, OS kill signals) propagate. Recoverable conditions
+ *    (model not staged, abort, downstream provider transient) trigger
+ *    fallback.
+ *  - Cloud forwarding is registry-driven. We look up the next-highest
+ *    priority handler from the runtime's model registry rather than
+ *    hardcoding "anthropic" or "openai". That keeps the wrapper neutral
+ *    to which cloud is paired.
+ */
+
+import type {
+	GenerateTextParams,
+	IAgentRuntime,
+	JsonValue,
+	ModelTypeName,
+} from "@elizaos/core";
+
+export type FallbackReason =
+	/** Local backend reported it can't serve this request at all (no model, FFI dlopen failed, etc). */
+	| "local-unavailable"
+	/** Local backend was busy, queued past a deadline, or refused (thermal, low-power). */
+	| "local-overloaded"
+	/** Local backend errored during prefill or decode. */
+	| "local-error"
+	/** Caller cancelled before local could finish; cloud may still serve. */
+	| "local-aborted-pre-completion"
+	/** Local handler isn't registered on this runtime build. */
+	| "local-not-registered";
+
+export type LocalGenerateOutcome =
+	| { kind: "ok"; text: string }
+	| { kind: "fallback"; reason: FallbackReason; cause?: Error };
+
+/**
+ * Classify a thrown error as a fallback-eligible failure or a hard bug that
+ * should propagate. The split is conservative: only well-known recoverable
+ * shapes flip to fallback; anything else bubbles up so the operator sees the
+ * real failure instead of a silent rotation to cloud.
+ */
+export function classifyLocalError(err: unknown): {
+	fallback: boolean;
+	reason: FallbackReason;
+} {
+	if (err instanceof Error) {
+		const name = err.name;
+		const msg = err.message.toLowerCase();
+		if (name === "AbortError") {
+			return { fallback: false, reason: "local-aborted-pre-completion" };
+		}
+		// KV-cache spill cannot meet the latency budget on this device — this is
+		// a deliberate hard-fail (packages/inference/AGENTS.md §3): the engine
+		// surfaces it to the UI as a structured error. There is no silent
+		// rotation to cloud and no "load anyway, slowly".
+		if (name === "KvSpillUnsupportedError") {
+			return { fallback: false, reason: "local-error" };
+		}
+		if (
+			msg.includes("no bundled") ||
+			msg.includes("not installed in this build") ||
+			msg.includes("node-llama-cpp is not installed") ||
+			msg.includes("no local model is active") ||
+			msg.includes("dlopen") ||
+			msg.includes("missing libllama")
+		) {
+			return { fallback: true, reason: "local-unavailable" };
+		}
+		if (
+			msg.includes("decode: failed to find a memory slot") ||
+			msg.includes("thermal") ||
+			msg.includes("low-power")
+		) {
+			return { fallback: true, reason: "local-overloaded" };
+		}
+		if (
+			msg.includes("llama_decode") ||
+			msg.includes("llama_tokenize") ||
+			msg.includes("llama_sampler") ||
+			msg.includes("ggml_assert")
+		) {
+			return { fallback: true, reason: "local-error" };
+		}
+	}
+	return { fallback: false, reason: "local-error" };
+}
+
+/**
+ * Locate a cloud TEXT_* handler in the runtime's model registry that is NOT
+ * the supplied `localProvider`. The runtime stores handlers per-modelType
+ * sorted by priority; we walk the list and skip our own provider so we
+ * delegate to cloud instead of recursing into local.
+ */
+export type RuntimeWithModelLookup = IAgentRuntime & {
+	models: Map<
+		string,
+		Array<{
+			provider: string;
+			priority: number;
+			handler: (
+				runtime: IAgentRuntime,
+				params: Record<string, JsonValue | object>,
+			) => Promise<JsonValue | object>;
+		}>
+	>;
+};
+
+export interface CloudCandidate {
+	provider: string;
+	priority: number;
+	handler: (
+		runtime: IAgentRuntime,
+		params: Record<string, JsonValue | object>,
+	) => Promise<JsonValue | object>;
+}
+
+export function findCloudCandidate(
+	runtime: IAgentRuntime,
+	modelType: ModelTypeName | string,
+	excludeProvider: string,
+): CloudCandidate | null {
+	const r = runtime as RuntimeWithModelLookup;
+	const entries = r.models.get(String(modelType));
+	if (!entries || entries.length === 0) return null;
+	// Sorted highest priority first by the runtime's registration. We want
+	// the FIRST non-local provider; that's our cloud candidate.
+	for (const entry of entries) {
+		if (entry.provider !== excludeProvider) {
+			return {
+				provider: entry.provider,
+				priority: entry.priority,
+				handler: entry.handler,
+			};
+		}
+	}
+	return null;
+}
+
+export interface CloudFallbackOptions {
+	/** Provider id of the local handler being wrapped (e.g. "eliza-aosp-llama"). */
+	localProvider: string;
+	/** Model type this wrapper services (TEXT_LARGE, TEXT_SMALL, etc). */
+	modelType: ModelTypeName | string;
+	/**
+	 * The local handler we wrap. Returns `{ kind: "ok" }` on success;
+	 * `{ kind: "fallback", reason }` to delegate to cloud.
+	 */
+	localGenerate: (
+		runtime: IAgentRuntime,
+		params: GenerateTextParams,
+	) => Promise<LocalGenerateOutcome>;
+	/** Optional logger; defaults to `console`-style no-op so we stay framework-free. */
+	log?: (message: string, detail?: Record<string, unknown>) => void;
+}
+
+/**
+ * Build a registered-handler-shape function that:
+ *  1. Calls `localGenerate`.
+ *  2. If `localGenerate` returns `{ kind: "ok" }`, returns that text.
+ *  3. If it returns `{ kind: "fallback" }`, looks up the next-best cloud
+ *     handler for the same modelType and forwards to it. If no cloud
+ *     handler exists, throws a typed error with the fallback reason.
+ *
+ * The returned function is suitable for `runtime.registerModel`.
+ */
+export function makeCloudFallbackHandler(
+	opts: CloudFallbackOptions,
+): (
+	runtime: IAgentRuntime,
+	params: Record<string, JsonValue | object>,
+) => Promise<string> {
+	const log = opts.log ?? (() => undefined);
+	return async (runtime, params) => {
+		const generateParams = params as unknown as GenerateTextParams;
+		const local = await opts.localGenerate(runtime, generateParams);
+		if (local.kind === "ok") {
+			return local.text;
+		}
+		log(
+			`[cloud-fallback] local handler returned fallback (reason=${local.reason})`,
+			{ modelType: String(opts.modelType), reason: local.reason },
+		);
+		const candidate = findCloudCandidate(
+			runtime,
+			opts.modelType,
+			opts.localProvider,
+		);
+		if (!candidate) {
+			const err = new Error(
+				`[cloud-fallback] Local inference reported ${local.reason} and no cloud handler is registered for ${String(opts.modelType)}. Pair Eliza Cloud or install a provider plugin (anthropic/openai) to enable fallback.`,
+			);
+			if (local.cause) {
+				(err as Error & { cause?: unknown }).cause = local.cause;
+			}
+			throw err;
+		}
+		log(
+			`[cloud-fallback] forwarding to ${candidate.provider} @ priority ${candidate.priority}`,
+			{
+				modelType: String(opts.modelType),
+				provider: candidate.provider,
+				reason: local.reason,
+			},
+		);
+		const result = await candidate.handler(runtime, params);
+		if (typeof result !== "string") {
+			throw new Error(
+				`[cloud-fallback] Cloud handler ${candidate.provider} returned non-string result for ${String(opts.modelType)}.`,
+			);
+		}
+		return result;
+	};
+}

package/src/services/conversation-registry.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Conversation registry for the local-inference path.
+ *
+ * Today's slot allocation is purely a hash function: `deriveSlotId` maps a
+ * `promptCacheKey` (or any stable string) to `slot_id` in `[0, parallel)`.
+ * That works for one-shot calls but breaks for long agentic loops:
+ *
+ *   - Two distinct conversations whose cache keys hash to the same slot
+ *     evict each other's KV every turn (slot thrashing).
+ *   - The current high-water mark of concurrent conversations is invisible,
+ *     so `--parallel N` cannot be tuned to fit.
+ *   - There is no notion of an explicit "I am still using this slot" lease,
+ *     so eviction is purely best-effort.
+ *
+ * This registry keeps a per-conversation reservation. `openConversation`
+ * picks the lowest-loaded slot and pins the conversation to it; subsequent
+ * `generateInConversation` calls always land on the same slot. When the
+ * pool is full, slot reuse falls back to the same-as-before hash policy
+ * (two leases on the same slot still serialise correctly via the dispatcher's
+ * generation queue).
+ *
+ * The registry tracks the high-water mark of concurrently-open conversations
+ * so the engine can warn, or later restart llama-server with a higher
+ * --parallel, when the load outgrows the configured slot count.
+ */
+/**
+ * Opaque handle returned by `openConversation`. Callers MUST treat this as
+ * opaque — the registry owns the slot id and lifetime.
+ */
+export interface ConversationHandle {
+    readonly conversationId: string;
+    readonly modelId: string;
+    /**
+     * Pinned slot id in `[0, parallel)`, or `-1` when slot pinning is disabled
+     * (parallel <= 0). Used by both backends as the cache key:
+     *   - llama-server: forwarded as `slot_id` in the request payload.
+     *   - node-llama-cpp: combined with the conversation id to derive the
+     *     session-pool key so identical conversations share a session.
+     */
+    readonly slotId: number;
+    /** Wall-clock ms when the handle was opened. */
+    readonly openedAtMs: number;
+    /** Wall-clock ms when the handle was last touched (open or generate). */
+    lastUsedMs: number;
+    /** TTL after which the registry MAY auto-close on the next sweep. */
+    readonly ttlMs: number;
+    /** True when `closeConversation` has been called; further use is rejected. */
+    closed: boolean;
+}
+export interface OpenConversationArgs {
+    conversationId: string;
+    modelId: string;
+    /** Slot count from the running server (`--parallel N`). Defaults to 1. */
+    parallel?: number;
+    /**
+     * TTL after which the handle is considered idle and may be auto-closed
+     * by `evictIdle`. Defaults to 60 minutes — long enough for an LLM call
+     * to finish even on a slow drafter, short enough to recover from forgotten
+     * close calls within the long-cache window.
+     */
+    ttlMs?: number;
+}
+/**
+ * In-memory registry of open conversation handles. A single instance is
+ * shared by the engine; each backend reads from it on every generate to
+ * decide which slot to pin to.
+ */
+export declare class ConversationRegistry {
+    private readonly handles;
+    /** Per-slot reference count; lowest-loaded slot wins on next open. */
+    private readonly slotLoad;
+    /** Largest concurrent open count seen; the engine reads this for parallel auto-tune. */
+    private highWaterMark;
+    /**
+     * Lookup / open a conversation handle. Idempotent for the same
+     * conversation id + model id; callers can call this on every turn
+     * without leaking handles. When the call is reusing an existing handle,
+     * `lastUsedMs` is bumped for LRU-style eviction tracking.
+     */
+    open(args: OpenConversationArgs): ConversationHandle;
+    /**
+     * Lookup an open handle by conversation+model. Returns null when the
+     * conversation has not been opened or has already been closed. Bumps
+     * `lastUsedMs` so an LRU sweep treats reads as activity.
+     */
+    get(conversationId: string, modelId: string): ConversationHandle | null;
+    /**
+     * Close + drop a handle. Idempotent — closing an unknown / already-closed
+     * handle has no additional effect, so callers can call this from cleanup paths
+     * unconditionally.
+     */
+    close(conversationId: string, modelId: string): void;
+    /**
+     * Sweep handles whose `lastUsedMs` is older than their TTL. Returns the
+     * conversation ids dropped so callers can persist final KV state to
+     * disk, etc. Safe to call on a timer.
+     */
+    evictIdle(now?: number): string[];
+    /**
+     * Snapshot every currently-open handle. Used by the shutdown path to
+     * emit a save-state request per slot.
+     */
+    snapshot(): readonly ConversationHandle[];
+    /** Largest concurrent open count seen since the registry was created. */
+    highWater(): number;
+    /** Number of currently-open handles. */
+    size(): number;
+    /**
+     * Recommended `--parallel` slot count given the observed high-water mark
+     * of concurrently-open conversations plus a small headroom (max(2, 25%)).
+     * The engine's auto-tune (J4) compares this against the running server's
+     * slot count: when this is larger AND there's RAM headroom, it restarts
+     * llama-server with the higher value so new conversations get their own
+     * KV slots instead of thrashing.
+     *
+     * `running` is the currently-configured slot count; when the high-water
+     * mark hasn't outgrown it, this returns `running` (no resize needed) so
+     * callers can compare against equality without a second branch.
+     */
+    recommendedParallel(running: number): number;
+    /**
+     * Drop every handle and reset the high-water mark + slot-load bookkeeping.
+     * Test-only — the module singleton leaks state across files when the suite
+     * runs together; call this in `beforeEach` to isolate. Not part of the
+     * runtime contract.
+     */
+    __resetForTests(): void;
+    /**
+     * Pick the slot with the fewest in-flight handles. Ties are broken by a
+     * deterministic hash of the conversation id, which avoids consistently
+     * loading slot 0 when N concurrent opens race.
+     */
+    private pickLowestLoadedSlot;
+    private compositeKey;
+}
+/**
+ * Module-singleton registry. The engine reads this on every generate; the
+ * conversation lifecycle API (`openConversation`, `closeConversation`)
+ * mutates it.
+ */
+export declare const conversationRegistry: ConversationRegistry;
+//# sourceMappingURL=conversation-registry.d.ts.map

package/src/services/conversation-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-registry.d.ts","sourceRoot":"","sources":["conversation-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAID;;;;GAIG;AACH,qBAAa,oBAAoB;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IACjE,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,wFAAwF;IACxF,OAAO,CAAC,aAAa,CAAK;IAE1B;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,oBAAoB,GAAG,kBAAkB;IAqCpD;;;;OAIG;IACH,GAAG,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAOvE;;;;OAIG;IACH,KAAK,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAcpD;;;;OAIG;IACH,SAAS,CAAC,GAAG,GAAE,MAAmB,GAAG,MAAM,EAAE;IAkB7C;;;OAGG;IACH,QAAQ,IAAI,SAAS,kBAAkB,EAAE;IAIzC,yEAAyE;IACzE,SAAS,IAAI,MAAM;IAInB,wCAAwC;IACxC,IAAI,IAAI,MAAM;IAId;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAM5C;;;;;OAKG;IACH,eAAe,IAAI,IAAI;IAOvB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAqB5B,OAAO,CAAC,YAAY;CAGpB;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,sBAA6B,CAAC"}

package/src/services/conversation-registry.test.ts

@@ -0,0 +1,235 @@
+import { describe, expect, it } from "vitest";
+import {
+	ConversationRegistry,
+	conversationRegistry,
+} from "./conversation-registry";
+
+describe("ConversationRegistry.open", () => {
+	it("returns the same handle for repeated opens of the same conversation", () => {
+		const registry = new ConversationRegistry();
+		const a = registry.open({
+			conversationId: "room-1",
+			modelId: "eliza-1-9b",
+			parallel: 4,
+		});
+		const b = registry.open({
+			conversationId: "room-1",
+			modelId: "eliza-1-9b",
+			parallel: 4,
+		});
+		expect(b).toBe(a);
+		expect(registry.size()).toBe(1);
+	});
+
+	it("treats different model ids as distinct handles", () => {
+		const registry = new ConversationRegistry();
+		const a = registry.open({
+			conversationId: "room-1",
+			modelId: "model-a",
+			parallel: 4,
+		});
+		const b = registry.open({
+			conversationId: "room-1",
+			modelId: "model-b",
+			parallel: 4,
+		});
+		expect(b).not.toBe(a);
+		expect(registry.size()).toBe(2);
+	});
+
+	it("requires non-empty conversationId and modelId", () => {
+		const registry = new ConversationRegistry();
+		expect(() => registry.open({ conversationId: "", modelId: "m" })).toThrow();
+		expect(() => registry.open({ conversationId: "c", modelId: "" })).toThrow();
+	});
+
+	it("pins the handle to slot 0 when parallel <= 1", () => {
+		const registry = new ConversationRegistry();
+		const handle = registry.open({
+			conversationId: "x",
+			modelId: "m",
+			parallel: 1,
+		});
+		expect(handle.slotId).toBe(0);
+	});
+
+	it("spreads concurrent opens across slots, lowest-loaded first", () => {
+		const registry = new ConversationRegistry();
+		const slots = new Set<number>();
+		for (let i = 0; i < 4; i += 1) {
+			const handle = registry.open({
+				conversationId: `room-${i}`,
+				modelId: "m",
+				parallel: 4,
+			});
+			slots.add(handle.slotId);
+		}
+		expect(slots.size).toBe(4);
+	});
+});
+
+describe("ConversationRegistry.close", () => {
+	it("frees the slot and is idempotent", () => {
+		const registry = new ConversationRegistry();
+		const handle = registry.open({
+			conversationId: "x",
+			modelId: "m",
+			parallel: 4,
+		});
+		expect(handle.closed).toBe(false);
+		registry.close("x", "m");
+		registry.close("x", "m"); // idempotent — must not throw
+		expect(registry.get("x", "m")).toBeNull();
+	});
+
+	it("frees a slot for reuse on next open", () => {
+		const registry = new ConversationRegistry();
+		const a = registry.open({
+			conversationId: "a",
+			modelId: "m",
+			parallel: 2,
+		});
+		const b = registry.open({
+			conversationId: "b",
+			modelId: "m",
+			parallel: 2,
+		});
+		expect(a.slotId).not.toBe(b.slotId);
+		registry.close("a", "m");
+		const c = registry.open({
+			conversationId: "c",
+			modelId: "m",
+			parallel: 2,
+		});
+		// c should land on the freed slot (a's slot)
+		expect(c.slotId).toBe(a.slotId);
+	});
+});
+
+describe("ConversationRegistry.get", () => {
+	it("returns null for unknown or closed handles", () => {
+		const registry = new ConversationRegistry();
+		expect(registry.get("nope", "m")).toBeNull();
+		registry.open({ conversationId: "x", modelId: "m", parallel: 4 });
+		registry.close("x", "m");
+		expect(registry.get("x", "m")).toBeNull();
+	});
+});
+
+describe("ConversationRegistry.evictIdle", () => {
+	it("drops handles whose ttl has elapsed", () => {
+		const registry = new ConversationRegistry();
+		registry.open({
+			conversationId: "x",
+			modelId: "m",
+			parallel: 4,
+			ttlMs: 1_000,
+		});
+		expect(registry.size()).toBe(1);
+		const dropped = registry.evictIdle(Date.now() + 5_000);
+		expect(dropped).toEqual(["x"]);
+		expect(registry.size()).toBe(0);
+	});
+
+	it("keeps handles whose ttl has NOT elapsed", () => {
+		const registry = new ConversationRegistry();
+		registry.open({
+			conversationId: "x",
+			modelId: "m",
+			parallel: 4,
+			ttlMs: 60_000,
+		});
+		const dropped = registry.evictIdle(Date.now() + 10_000);
+		expect(dropped).toEqual([]);
+		expect(registry.size()).toBe(1);
+	});
+});
+
+describe("ConversationRegistry.highWater", () => {
+	it("tracks the largest concurrent open count", () => {
+		const registry = new ConversationRegistry();
+		expect(registry.highWater()).toBe(0);
+		registry.open({ conversationId: "a", modelId: "m", parallel: 8 });
+		registry.open({ conversationId: "b", modelId: "m", parallel: 8 });
+		registry.open({ conversationId: "c", modelId: "m", parallel: 8 });
+		expect(registry.highWater()).toBe(3);
+		registry.close("a", "m");
+		registry.close("b", "m");
+		// High-water mark must NOT decrease — it's a max over the lifetime
+		expect(registry.highWater()).toBe(3);
+	});
+});
+
+describe("ConversationRegistry.recommendedParallel (--parallel auto-resize decision)", () => {
+	it("returns the running count when the high-water mark hasn't outgrown it", () => {
+		const registry = new ConversationRegistry();
+		// 2 concurrent, headroom max(2, ceil(2*0.25)=1) = 2 → desired 4.
+		registry.open({ conversationId: "a", modelId: "m", parallel: 4 });
+		registry.open({ conversationId: "b", modelId: "m", parallel: 4 });
+		expect(registry.highWater()).toBe(2);
+		expect(registry.recommendedParallel(4)).toBe(4); // 4 already covers it
+		expect(registry.recommendedParallel(8)).toBe(8); // larger running wins
+	});
+
+	it("recommends high-water + 25%-headroom when it exceeds the running count", () => {
+		const registry = new ConversationRegistry();
+		for (let i = 0; i < 20; i += 1) {
+			registry.open({ conversationId: `c-${i}`, modelId: "m", parallel: 4 });
+		}
+		expect(registry.highWater()).toBe(20);
+		// 20 + max(2, ceil(20*0.25)=5) = 25.
+		expect(registry.recommendedParallel(4)).toBe(25);
+	});
+
+	it("headroom floors at 2 (small high-water marks still get a buffer)", () => {
+		const registry = new ConversationRegistry();
+		for (let i = 0; i < 5; i += 1) {
+			registry.open({ conversationId: `c-${i}`, modelId: "m", parallel: 2 });
+		}
+		expect(registry.highWater()).toBe(5);
+		// ceil(5*0.25) = 2 → headroom 2 → desired 7.
+		expect(registry.recommendedParallel(2)).toBe(7);
+	});
+
+	it("is monotonic: closing conversations does not shrink the recommendation", () => {
+		const registry = new ConversationRegistry();
+		const handles = Array.from({ length: 10 }, (_, i) =>
+			registry.open({ conversationId: `c-${i}`, modelId: "m", parallel: 4 }),
+		);
+		expect(registry.recommendedParallel(4)).toBe(13); // 10 + ceil(10*.25)=3
+		for (const h of handles) registry.close(h.conversationId, h.modelId);
+		expect(registry.size()).toBe(0);
+		expect(registry.recommendedParallel(4)).toBe(13); // unchanged
+	});
+});
+
+describe("ConversationRegistry.__resetForTests", () => {
+	it("drops every handle and resets the high-water mark", () => {
+		const registry = new ConversationRegistry();
+		const a = registry.open({ conversationId: "a", modelId: "m", parallel: 4 });
+		registry.open({ conversationId: "b", modelId: "m", parallel: 4 });
+		expect(registry.size()).toBe(2);
+		expect(registry.highWater()).toBe(2);
+		registry.__resetForTests();
+		expect(registry.size()).toBe(0);
+		expect(registry.highWater()).toBe(0);
+		expect(registry.recommendedParallel(4)).toBe(4);
+		// The dropped handle is marked closed (further use is rejected by the engine).
+		expect(a.closed).toBe(true);
+		// A slot freed by reset is reusable from slot 0 again.
+		const handle = registry.open({
+			conversationId: "c",
+			modelId: "m",
+			parallel: 4,
+		});
+		expect(handle.slotId).toBe(0);
+	});
+
+	it("isolates the module singleton across test files", () => {
+		conversationRegistry.__resetForTests();
+		conversationRegistry.open({ conversationId: "leak", modelId: "m" });
+		expect(conversationRegistry.size()).toBe(1);
+		conversationRegistry.__resetForTests();
+		expect(conversationRegistry.size()).toBe(0);
+	});
+});