@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/engine/apis/llamacpp-residency.ts

@@ -0,0 +1,292 @@
+import { performance } from "node:perf_hooks";
+import { sleep } from "../../core/timers.js";
+import {
+	type ResidencyAdapter,
+	ResidencyPreconditionError,
+	reconcileResidency,
+	resetResidencyState,
+	residencyManaged,
+	residentTagProtected,
+} from "./residency.js";
+
+/**
+ * llama.cpp router adapter for the shared residency reconciler
+ * (residency.ts). The router is a multi-model server: `/v1/models` reports
+ * per-model load state and tags, `/props` advertises `max_instances`, and
+ * models load/unload through explicit POSTs. This module maps that surface
+ * onto the reconciler's "router" strategy so co-residency, capacity math,
+ * protection tiers, opt-outs, TTL dedupe, and the cross-process lock all come
+ * from the one shared policy. Plain llama-server builds without router load
+ * states are never managed.
+ */
+
+export interface LlamaCppResidencyInput {
+	/** OpenAI-compatible base URL, e.g. http://host:8080/v1. */
+	baseUrl: string;
+	targetId: string;
+	runtimeId: string;
+	keepModelId: string;
+	/**
+	 * Combined env + target lifecycle opt-out verdict from the caller
+	 * (residencyManagedFor). Defaults to the env-only switch.
+	 */
+	managed?: boolean;
+	fetchImpl?: typeof fetch;
+	now?: () => number;
+	ttlMs?: number;
+	/** Probe timeout; a residency probe must never stall a turn. */
+	timeoutMs?: number;
+	/** Test-only override for the cross-process mutation lock. */
+	withLock?<T>(targetKey: string, fn: () => Promise<T>): Promise<T>;
+}
+
+const LOAD_TIMEOUT_MS = 120_000;
+const POLL_INTERVAL_MS = 500;
+
+/**
+ * `sleeping` is a resident state, not an unloaded one. A router started with
+ * `--sleep-idle-seconds` parks an idle model's compute while it keeps the slot
+ * and its weights, and wakes it on the next inference request. Reading it as
+ * anything else costs twice: the model drops out of the resident set, so
+ * capacity math sees a free slot that does not exist, and the load path stops
+ * short-circuiting and re-requests a model the router is already running.
+ */
+type LlamaCppModelState = "loaded" | "loading" | "sleeping" | "unloaded" | "failed" | "unknown";
+
+/** Router states that hold the model's slot on the server. */
+function isResidentState(state: LlamaCppModelState): boolean {
+	return state === "loaded" || state === "loading" || state === "sleeping";
+}
+
+interface LlamaCppResidentModel {
+	id: string;
+	tags: string[];
+}
+
+interface LlamaCppRouterModel extends LlamaCppResidentModel {
+	state: LlamaCppModelState;
+}
+
+interface LlamaCppRouterProps {
+	maxInstances?: number;
+}
+
+/** Test-only: clear the reconciler's TTL cache and Clio-loaded registry. */
+export function resetLlamaCppResidencyState(): void {
+	resetResidencyState();
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function routerModelState(entry: Record<string, unknown>): LlamaCppModelState {
+	const status = entry.status;
+	const state = isRecord(status) ? status.value : status;
+	if (state === "loaded" || state === "loading" || state === "sleeping" || state === "unloaded" || state === "failed") {
+		return state;
+	}
+	return "unknown";
+}
+
+function parseRouterModels(payload: unknown): LlamaCppRouterModel[] {
+	if (!isRecord(payload)) return [];
+	const data = payload.data;
+	if (!Array.isArray(data)) return [];
+	const models: LlamaCppRouterModel[] = [];
+	for (const entry of data) {
+		if (!isRecord(entry) || typeof entry.id !== "string") continue;
+		const tags = Array.isArray(entry.tags) ? entry.tags.filter((tag): tag is string => typeof tag === "string") : [];
+		models.push({ id: entry.id, state: routerModelState(entry), tags });
+	}
+	return models;
+}
+
+function residentModel(model: LlamaCppRouterModel): boolean {
+	return isResidentState(model.state);
+}
+
+/** Extract resident (loaded, loading, or sleeping) model records from a /v1/models payload. */
+export function parseLlamaCppResidentModels(payload: unknown): LlamaCppResidentModel[] {
+	return parseRouterModels(payload)
+		.filter(residentModel)
+		.map((entry) => ({ id: entry.id, tags: entry.tags }));
+}
+
+/** Extract resident (loaded or loading) model ids from a /v1/models payload. */
+export function parseLlamaCppResident(payload: unknown): string[] {
+	return parseLlamaCppResidentModels(payload).map((entry) => entry.id);
+}
+
+export function parseLlamaCppRouterProps(payload: unknown): LlamaCppRouterProps {
+	if (!isRecord(payload)) return {};
+	const maxInstances = payload.max_instances;
+	return typeof maxInstances === "number" && Number.isFinite(maxInstances) && maxInstances > 0
+		? { maxInstances: Math.floor(maxInstances) }
+		: {};
+}
+
+function rootUrl(baseUrl: string): string {
+	return baseUrl.replace(/\/+$/, "").replace(/\/v1$/, "");
+}
+
+function modelsUrl(baseUrl: string): string {
+	return `${baseUrl.replace(/\/+$/, "")}/models`;
+}
+
+function propsUrl(baseUrl: string): string {
+	return `${rootUrl(baseUrl)}/props`;
+}
+
+function loadUrl(baseUrl: string): string {
+	return `${rootUrl(baseUrl)}/models/load`;
+}
+
+function unloadUrl(baseUrl: string): string {
+	return `${rootUrl(baseUrl)}/models/unload`;
+}
+
+async function fetchRouterProps(input: LlamaCppResidencyInput, fetchImpl: typeof fetch): Promise<LlamaCppRouterProps> {
+	try {
+		const response = await fetchImpl(propsUrl(input.baseUrl), {
+			signal: AbortSignal.timeout(input.timeoutMs ?? 1500),
+		});
+		if (!response.ok) return {};
+		return parseLlamaCppRouterProps(await response.json());
+	} catch {
+		return {};
+	}
+}
+
+async function fetchRouterModels(
+	input: LlamaCppResidencyInput,
+	fetchImpl: typeof fetch,
+): Promise<LlamaCppRouterModel[]> {
+	const response = await fetchImpl(modelsUrl(input.baseUrl), {
+		signal: AbortSignal.timeout(input.timeoutMs ?? 1500),
+	});
+	if (!response.ok) throw new Error(`HTTP ${response.status}`);
+	return parseRouterModels(await response.json());
+}
+
+async function postRouterModel(fetchImpl: typeof fetch, url: string, modelId: string): Promise<void> {
+	const response = await fetchImpl(url, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({ model: modelId }),
+		signal: AbortSignal.timeout(LOAD_TIMEOUT_MS),
+	});
+	if (response.ok) return;
+	throw new Error(`llama.cpp router rejected ${url}: HTTP ${response.status}`);
+}
+
+async function waitForLoaded(input: LlamaCppResidencyInput, fetchImpl: typeof fetch, modelId: string): Promise<void> {
+	const started = performance.now();
+	while (performance.now() - started < LOAD_TIMEOUT_MS) {
+		const models = await fetchRouterModels(input, fetchImpl);
+		const model = models.find((entry) => entry.id === modelId);
+		// A model that goes straight back to sleep between polls is resident and
+		// serves the next request; waiting for it to read `loaded` would spin out
+		// the whole load timeout on an idle router.
+		if (model?.state === "loaded" || model?.state === "sleeping") return;
+		if (model?.state === "failed") throw new Error(`llama.cpp router reports '${modelId}' failed to load`);
+		await sleep(POLL_INTERVAL_MS);
+	}
+	throw new Error(`timed out waiting for '${modelId}' to load`);
+}
+
+async function ensureModelLoaded(
+	input: LlamaCppResidencyInput,
+	fetchImpl: typeof fetch,
+	modelId: string,
+	knownState: LlamaCppModelState | undefined,
+): Promise<void> {
+	// A sleeping model is already running and the router wakes it on the next
+	// inference request. Posting a load for it is not merely redundant: the
+	// router answers `400 model is already running`, which fails the turn before
+	// it reaches the model.
+	if (knownState === "loaded" || knownState === "sleeping") return;
+	if (knownState !== "loading") await postRouterModel(fetchImpl, loadUrl(input.baseUrl), modelId);
+	await waitForLoaded(input, fetchImpl, modelId);
+}
+
+/**
+ * A router whose capacity Clio could not read may satisfy a load by
+ * displacing an LRU resident. Reload any tag-pinned resident the load
+ * displaced (one bounded pass), then verify the restore did not displace the
+ * keep model in turn.
+ */
+async function restoreDisplacedPinned(
+	input: LlamaCppResidencyInput,
+	fetchImpl: typeof fetch,
+	before: ReadonlyArray<LlamaCppRouterModel>,
+): Promise<void> {
+	const pinned = before.filter(
+		(entry) => residentModel(entry) && entry.id !== input.keepModelId && residentTagProtected(entry.tags),
+	);
+	if (pinned.length === 0) return;
+	const current = await fetchRouterModels(input, fetchImpl);
+	let changed = false;
+	for (const model of pinned) {
+		const state = current.find((entry) => entry.id === model.id)?.state;
+		if (state !== undefined && isResidentState(state)) continue;
+		changed = true;
+		await ensureModelLoaded(input, fetchImpl, model.id, state);
+	}
+	if (!changed) return;
+	const finalModels = await fetchRouterModels(input, fetchImpl);
+	const keep = finalModels.find((entry) => entry.id === input.keepModelId);
+	if (keep === undefined || !isResidentState(keep.state)) {
+		throw new Error(`pinned-resident restore displaced '${input.keepModelId}'`);
+	}
+}
+
+/** Ensure the selected llama.cpp router model is resident before inference. */
+export async function ensureLlamaCppResidency(input: LlamaCppResidencyInput): Promise<void> {
+	const fetchImpl = input.fetchImpl ?? fetch;
+	let snapshot: LlamaCppRouterModel[] = [];
+	const adapter: ResidencyAdapter = {
+		targetKey: `llamacpp|${input.baseUrl}`,
+		targetId: input.targetId,
+		runtimeId: input.runtimeId,
+		keepModelId: input.keepModelId,
+		managed: input.managed ?? residencyManaged(),
+		strategy: "router",
+		listResident: async () => {
+			const models = await fetchRouterModels(input, fetchImpl);
+			if (!models.some((entry) => entry.state !== "unknown")) {
+				throw new Error("not a llama.cpp router: /v1/models reports no load states");
+			}
+			snapshot = models;
+			return models.filter(residentModel).map((entry) => ({ modelId: entry.id, tags: entry.tags }));
+		},
+		// The router enumerates every configured preset, resident or not, so a keep
+		// model missing from that listing is one this server cannot load at all.
+		// Reported from the snapshot listResident already fetched, so the check
+		// costs no extra round trip.
+		assertLoadable: async () => {
+			if (snapshot.some((entry) => entry.id === input.keepModelId)) return;
+			throw new ResidencyPreconditionError(
+				`llama.cpp router on '${input.targetId}' does not serve '${input.keepModelId}'; it lists ${snapshot.length} model(s). Residency left the target untouched. Fix the wire model id in settings, or add the preset to the server.`,
+			);
+		},
+		capacity: async () => (await fetchRouterProps(input, fetchImpl)).maxInstances,
+		keepModelTags: async () => snapshot.find((entry) => entry.id === input.keepModelId)?.tags,
+		unload: (modelId) => postRouterModel(fetchImpl, unloadUrl(input.baseUrl), modelId),
+		load: async (modelId) => {
+			const state = snapshot.find((entry) => entry.id === modelId)?.state;
+			if (state !== undefined && isResidentState(state) && state !== "loading") return;
+			await ensureModelLoaded(input, fetchImpl, modelId, state);
+			await restoreDisplacedPinned(input, fetchImpl, snapshot);
+		},
+		// `snapshot` predates the eviction and still calls this model resident, so
+		// the state is deliberately not read here: the reload has to be forced.
+		reloadEvicted: async (modelId) => {
+			await ensureModelLoaded(input, fetchImpl, modelId, undefined);
+		},
+	};
+	if (input.withLock) adapter.withLock = input.withLock;
+	if (input.now) adapter.now = input.now;
+	if (input.ttlMs !== undefined) adapter.ttlMs = input.ttlMs;
+	await reconcileResidency(adapter);
+}

package/src/engine/apis/lmstudio-residency.ts

@@ -0,0 +1,76 @@
+/**
+ * LM Studio-specific residency arithmetic, kept pure so the fit and duplicate
+ * rules are testable without a server connection.
+ *
+ * LM Studio's `/api/v1/models` response exposes no total or free GPU memory,
+ * and a GPU offload cap does not prove that a load fits
+ * rather than failing an oversized load, so a request that does not fit is
+ * served from CPU at a fraction of the speed instead of erroring. Fit therefore
+ * cannot be computed from memory arithmetic; it is bounded by evidence.
+ *
+ * The evidence rule: while another model is resident on the same server, an
+ * explicit load is capped at {@link CO_RESIDENT_CONTEXT_CEILING} tokens.
+ * The KV cache of a long context is what actually overflows the card (measured
+ * on an RTX 5090: a 27B Q4 model loaded at its 262,144-token default beside a
+ * resident 26B model produced 25 tokens in 2m18s, and the same model at 131,072
+ * answered a 9,019-token prompt in 9.7s). Operators who know their card holds
+ * more raise the ceiling with CLIO_CODER_LMSTUDIO_CORESIDENT_CONTEXT; a target
+ * serving one model alone is never clamped.
+ */
+
+/**
+ * Largest automatic load context Clio requests while another model is resident
+ * on the same LM Studio server.
+ */
+export const CO_RESIDENT_CONTEXT_CEILING = 131_072;
+
+/** Operator override for {@link CO_RESIDENT_CONTEXT_CEILING}; 0 or `off` disables clamping. */
+export function coResidentContextCeiling(env: NodeJS.ProcessEnv = process.env): number | undefined {
+	const raw = (env.CLIO_CODER_LMSTUDIO_CORESIDENT_CONTEXT ?? "").trim().toLowerCase();
+	if (raw.length === 0) return CO_RESIDENT_CONTEXT_CEILING;
+	if (raw === "off" || raw === "0" || raw === "false") return undefined;
+	const parsed = Number.parseInt(raw, 10);
+	if (!Number.isFinite(parsed) || parsed <= 0) return CO_RESIDENT_CONTEXT_CEILING;
+	return parsed;
+}
+
+/** One loaded instance as LM Studio reports it: a model key plus its instance identity. */
+export interface LmStudioResidentInstance {
+	modelKey: string;
+	/** Per-instance identifier. Two instances of one model key differ here. */
+	identifier?: string;
+	sizeBytes?: number;
+}
+
+export interface ContextFitInput {
+	/** Context length the load would otherwise request. */
+	requested: number;
+	/** Instances already resident on the target, including the requested model. */
+	resident: ReadonlyArray<LmStudioResidentInstance>;
+	/** Requested model's wire id, so its own instances are not counted as neighbours. */
+	keepModelId: string;
+	ceiling?: number | undefined;
+}
+
+export interface ContextFitResult {
+	/** Context length to load with. */
+	contextLength: number;
+	/** Set when the ceiling lowered the request; carries the original value. */
+	clampedFrom?: number;
+	/** Model keys resident alongside the requested model. */
+	neighbours: string[];
+}
+
+/**
+ * Clamp a just-in-time load's context length to what the target has evidence of
+ * holding. Only co-residency triggers the clamp: a server with nothing else
+ * loaded gets the full requested window.
+ */
+export function fitLoadContextLength(input: ContextFitInput): ContextFitResult {
+	const neighbours = [...new Set(input.resident.filter((e) => e.modelKey !== input.keepModelId).map((e) => e.modelKey))];
+	const ceiling = input.ceiling;
+	if (neighbours.length === 0 || ceiling === undefined || input.requested <= ceiling) {
+		return { contextLength: input.requested, neighbours };
+	}
+	return { contextLength: ceiling, clampedFrom: input.requested, neighbours };
+}

package/src/engine/apis/lmstudio.ts

@@ -0,0 +1,243 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+
+import {
+	type LmStudioCatalog,
+	type LmStudioLoadedInstance,
+	type LmStudioModelInfo,
+	listLmStudioModels,
+	lmStudioRootUrl,
+	requestLmStudioJson,
+	resolveLmStudioInstance,
+} from "../../domains/providers/runtimes/common/lmstudio-http.js";
+import type { TargetDescriptor } from "../../domains/providers/types/target-descriptor.js";
+import { coResidentContextCeiling, fitLoadContextLength } from "./lmstudio-residency.js";
+import { emitResidencyNotice, reconcileResidency, residencyManagedFor } from "./residency.js";
+import { withResidencyLock } from "./residency-lock.js";
+
+interface LmStudioModelMetadata {
+	clio?: {
+		targetId: string;
+		runtimeId: string;
+		lifecycle?: "user-managed" | "clio-managed";
+		lmstudio?: TargetDescriptor["lmstudio"];
+		lmstudioDefaultModel?: string;
+	};
+}
+
+const ownedInstancesByTarget = new Map<string, Set<string>>();
+
+function ownedInstances(targetKey: string): Set<string> {
+	let owned = ownedInstancesByTarget.get(targetKey);
+	if (!owned) {
+		owned = new Set<string>();
+		ownedInstancesByTarget.set(targetKey, owned);
+	}
+	return owned;
+}
+
+function responseInstanceId(data: unknown): string | undefined {
+	if (!data || typeof data !== "object" || Array.isArray(data)) return undefined;
+	const id = (data as { instance_id?: unknown }).instance_id;
+	return typeof id === "string" && id.trim().length > 0 ? id.trim() : undefined;
+}
+
+function metadata(model: Model<Api>): NonNullable<LmStudioModelMetadata["clio"]> | undefined {
+	return (model as Model<Api> & LmStudioModelMetadata).clio;
+}
+
+function targetForModel(model: Model<"openai-completions">): TargetDescriptor | null {
+	const info = metadata(model);
+	if (info?.runtimeId !== "lmstudio" || !model.baseUrl) return null;
+	return {
+		id: info.targetId,
+		runtime: "lmstudio",
+		url: lmStudioRootUrl(model.baseUrl),
+		defaultModel: info.lmstudioDefaultModel ?? model.id,
+		...(model.headers ? { auth: { headers: model.headers } } : {}),
+		...(info.lifecycle ? { lifecycle: info.lifecycle } : {}),
+		...(info.lmstudio ? { lmstudio: info.lmstudio } : {}),
+	};
+}
+
+function resolveModel(
+	catalog: LmStudioCatalog,
+	id: string,
+): { model: LmStudioModelInfo; instance?: LmStudioLoadedInstance } | null {
+	for (const model of catalog.models) {
+		if (model.key === id) return { model, ...(model.loadedInstances[0] ? { instance: model.loadedInstances[0] } : {}) };
+		const instance = model.loadedInstances.find((entry) => entry.id === id);
+		if (instance) return { model, instance };
+	}
+	return null;
+}
+
+function lmStudioLoadBody(
+	modelKey: string,
+	settings: NonNullable<NonNullable<TargetDescriptor["lmstudio"]>["load"]>,
+): Record<string, unknown> {
+	const body: Record<string, unknown> = { model: modelKey, echo_load_config: true };
+	if (settings.contextLength !== undefined) body.context_length = settings.contextLength;
+	if (settings.flashAttention !== undefined) body.flash_attention = settings.flashAttention;
+	if (settings.evalBatchSize !== undefined) body.eval_batch_size = settings.evalBatchSize;
+	if (settings.numExperts !== undefined) body.num_experts = settings.numExperts;
+	if (settings.offloadKvCacheToGpu !== undefined) body.offload_kv_cache_to_gpu = settings.offloadKvCacheToGpu;
+	return body;
+}
+
+async function post(
+	target: TargetDescriptor,
+	path: string,
+	body: Record<string, unknown>,
+	apiKey: string | undefined,
+	signal: AbortSignal | undefined,
+): Promise<unknown> {
+	const headers: Record<string, string> = { "content-type": "application/json", ...(target.auth?.headers ?? {}) };
+	if (apiKey?.trim()) headers.authorization = `Bearer ${apiKey.trim()}`;
+	const response = await requestLmStudioJson(
+		`${lmStudioRootUrl(target.url ?? "")}${path}`,
+		{ method: "POST", headers, body: JSON.stringify(body) },
+		5_000,
+		signal,
+	);
+	if (!response.ok) throw new Error(response.error ?? `LM Studio ${path} returned HTTP ${response.status}`);
+	return response.data;
+}
+
+async function unloadOwnedInstance(
+	target: TargetDescriptor,
+	targetKey: string,
+	instanceId: string,
+	apiKey: string | undefined,
+	signal: AbortSignal | undefined,
+): Promise<boolean> {
+	const owned = ownedInstances(targetKey);
+	if (!owned.has(instanceId)) return false;
+	await post(target, "/api/v1/models/unload", { instance_id: instanceId }, apiKey, signal);
+	owned.delete(instanceId);
+	return true;
+}
+
+async function loadOwnedInstance(
+	target: TargetDescriptor,
+	targetKey: string,
+	body: Record<string, unknown>,
+	apiKey: string | undefined,
+	signal: AbortSignal | undefined,
+): Promise<string | undefined> {
+	const data = await post(target, "/api/v1/models/load", body, apiKey, signal);
+	const instanceId = responseInstanceId(data);
+	if (instanceId) ownedInstances(targetKey).add(instanceId);
+	return instanceId;
+}
+
+export async function ensureLmStudioResidency(
+	model: Model<"openai-completions">,
+	options: { apiKey?: string; signal?: AbortSignal } = {},
+): Promise<string> {
+	const target = targetForModel(model);
+	if (!target) return model.id;
+	const info = metadata(model);
+	if (!info) return model.id;
+	const load = target.lmstudio?.load;
+	const ctx = {
+		credentialsPresent: new Set<string>(),
+		httpTimeoutMs: 5_000,
+		...(options.apiKey ? { authToken: options.apiKey } : {}),
+		...(options.signal ? { signal: options.signal } : {}),
+	};
+	const catalog = await listLmStudioModels(target, ctx);
+	if (!catalog.ok) throw new Error(catalog.error ?? "LM Studio model listing failed");
+	const resolution = resolveLmStudioInstance(target, catalog.models, model.id, info.lmstudioDefaultModel);
+	if (resolution.state === "unknown") {
+		const resident = catalog.models.flatMap((entry) => entry.loadedInstances.map((instance) => instance.id));
+		throw new Error(
+			`LM Studio target '${info.targetId}' does not advertise model '${model.id}'. Resident instances: ${resident.length > 0 ? resident.join(", ") : "none"}. Configure an explicit LM Studio load before requesting an unlisted model.`,
+		);
+	}
+	if (resolution.wireModelId !== model.id) {
+		emitResidencyNotice({
+			kind: "co-resident",
+			level: "info",
+			targetId: info.targetId,
+			runtimeId: "lmstudio",
+			model: model.id,
+			message: `LM Studio resolved '${model.id}' to loaded instance '${resolution.wireModelId}' on target '${info.targetId}'.`,
+			detail: { requestedModel: model.id, wireModel: resolution.wireModelId },
+		});
+	}
+	if (resolution.peerTargets.length > 0) {
+		emitResidencyNotice({
+			kind: "co-resident",
+			level: "warning",
+			targetId: info.targetId,
+			runtimeId: "lmstudio",
+			model: resolution.wireModelId,
+			message: `LM Studio instance '${resolution.wireModelId}' is also loaded on ${resolution.peerTargets.join(", ")}; this request may be served by that LM Link peer.`,
+			detail: { peerTargets: resolution.peerTargets.join(", ") },
+		});
+	}
+	if (!load || Object.keys(load).length === 0 || resolution.instance) return resolution.wireModelId;
+	if (catalog.tier !== "0.4+") return resolution.wireModelId;
+	const selected = resolveModel(catalog, model.id);
+	const modelKey = selected?.model.key ?? model.id;
+	let instances = catalog.models.flatMap((entry) =>
+		entry.loadedInstances.map((instance) => ({ modelKey: entry.key, identifier: instance.id, instance })),
+	);
+	const managed = residencyManagedFor(info.lifecycle);
+	const targetKey = `lmstudio|${lmStudioRootUrl(target.url ?? model.baseUrl)}`;
+	const contextLength = target.lmstudio?.load?.contextLength;
+	const plan = await reconcileResidency({
+		targetKey,
+		targetId: info.targetId,
+		runtimeId: "lmstudio",
+		keepModelId: modelKey,
+		managed,
+		strategy: "jit",
+		...(contextLength !== undefined ? { contextLength } : {}),
+		...(model.contextWindow > 0 ? { modelMaxContext: model.contextWindow } : {}),
+		listResident: async () => [...new Set(instances.map((entry) => entry.modelKey))].map((modelId) => ({ modelId })),
+		unload: async (id) => {
+			const released = new Set<string>();
+			for (const entry of instances.filter((resident) => resident.modelKey === id)) {
+				if (await unloadOwnedInstance(target, targetKey, entry.identifier, options.apiKey, options.signal)) {
+					released.add(entry.identifier);
+				}
+			}
+			instances = instances.filter((resident) => !released.has(resident.identifier));
+		},
+	});
+	let body = lmStudioLoadBody(modelKey, load);
+	if (load.contextLength !== undefined) {
+		const fit = fitLoadContextLength({
+			requested: load.contextLength,
+			resident: instances,
+			keepModelId: modelKey,
+			ceiling: coResidentContextCeiling(),
+		});
+		body = { ...body, context_length: fit.contextLength };
+		if (fit.clampedFrom !== undefined) {
+			emitResidencyNotice({
+				kind: "stress",
+				level: "warning",
+				targetId: info.targetId,
+				runtimeId: "lmstudio",
+				model: model.id,
+				message: `loading '${model.id}' alongside ${fit.neighbours.join(", ")}: context clamped ${fit.clampedFrom} to ${fit.contextLength} tokens`,
+				detail: { requestedContext: fit.clampedFrom, loadContext: fit.contextLength },
+			});
+		}
+	}
+	try {
+		return (await loadOwnedInstance(target, targetKey, body, options.apiKey, options.signal)) ?? model.id;
+	} catch (error) {
+		if (plan.decision === "observe" || plan.fallbackEvict.length === 0) throw error;
+		return withResidencyLock(targetKey, async () => {
+			for (const candidate of plan.fallbackEvict) {
+				for (const entry of instances.filter((resident) => resident.modelKey === candidate.modelId)) {
+					await unloadOwnedInstance(target, targetKey, entry.identifier, options.apiKey, options.signal);
+				}
+			}
+			return (await loadOwnedInstance(target, targetKey, body, options.apiKey, options.signal)) ?? model.id;
+		});
+	}
+}