@iowarp/clio-coder 0.3.1 → 0.3.3

package/src/engine/api-registry.ts

@@ -0,0 +1,223 @@
+import type {
+	Api,
+	AssistantMessage,
+	AssistantMessageEventStream,
+	Context,
+	Model,
+	ProviderStreams,
+	SimpleStreamOptions,
+	StreamOptions,
+} from "@earendil-works/pi-ai";
+import { anthropicMessagesApi } from "@earendil-works/pi-ai/api/anthropic-messages.lazy";
+import { azureOpenAIResponsesApi } from "@earendil-works/pi-ai/api/azure-openai-responses.lazy";
+import { bedrockConverseStreamApi } from "@earendil-works/pi-ai/api/bedrock-converse-stream.lazy";
+import { googleGenerativeAIApi } from "@earendil-works/pi-ai/api/google-generative-ai.lazy";
+import { googleVertexApi } from "@earendil-works/pi-ai/api/google-vertex.lazy";
+import { mistralConversationsApi } from "@earendil-works/pi-ai/api/mistral-conversations.lazy";
+import { openAICodexResponsesApi } from "@earendil-works/pi-ai/api/openai-codex-responses.lazy";
+import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
+import { openAIResponsesApi } from "@earendil-works/pi-ai/api/openai-responses.lazy";
+import { piMessagesApi } from "@earendil-works/pi-ai/api/pi-messages.lazy";
+import {
+	createFauxCore,
+	type FauxProviderRegistration,
+	type RegisterFauxProviderOptions,
+} from "@earendil-works/pi-ai/providers/faux";
+import "@earendil-works/pi-ai/providers/images/register-builtins";
+
+import { getEngineEnvApiKey } from "./env-api-keys.js";
+import { engineModels } from "./models.js";
+
+export interface EngineRegisteredApiProvider extends ProviderStreams {
+	api: Api;
+}
+
+interface RegistryEntry {
+	provider: EngineRegisteredApiProvider;
+	sourceId?: string;
+}
+
+interface CompatUniverse {
+	registerApiProvider(provider: EngineRegisteredApiProvider, sourceId?: string): void;
+	unregisterApiProviders(sourceId: string): void;
+	stream(model: Model<Api>, context: Context, options?: StreamOptions): AssistantMessageEventStream;
+	streamSimple(model: Model<Api>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;
+}
+
+const registry = new Map<Api, RegistryEntry>();
+const builtinInstances = new Map<Api, EngineRegisteredApiProvider>();
+let compatUniverse: CompatUniverse | undefined;
+let compatUniversePromise: Promise<void> | undefined;
+let builtinsRegistered = false;
+
+function wrappedProvider(provider: EngineRegisteredApiProvider): EngineRegisteredApiProvider {
+	const { api } = provider;
+	return {
+		api,
+		stream(model, context, options) {
+			if (model.api !== api) throw new Error(`Mismatched api: ${model.api} expected ${api}`);
+			return provider.stream(model, context, options);
+		},
+		streamSimple(model, context, options) {
+			if (model.api !== api) throw new Error(`Mismatched api: ${model.api} expected ${api}`);
+			return provider.streamSimple(model, context, options);
+		},
+	};
+}
+
+export function registerEngineApiProvider(provider: EngineRegisteredApiProvider, sourceId?: string): void {
+	const wrapped = wrappedProvider(provider);
+	registry.set(provider.api, { provider: wrapped, ...(sourceId === undefined ? {} : { sourceId }) });
+	compatUniverse?.registerApiProvider(provider, sourceId);
+}
+
+function unregisterEngineApiProviders(sourceId: string): void {
+	for (const [api, entry] of registry) {
+		if (entry.sourceId === sourceId) registry.delete(api);
+	}
+	compatUniverse?.unregisterApiProviders(sourceId);
+}
+
+export function getEngineApiProvider(api: Api): EngineRegisteredApiProvider | undefined {
+	return registry.get(api)?.provider;
+}
+
+const BUILTIN_APIS: readonly (readonly [Api, ProviderStreams])[] = [
+	["anthropic-messages", anthropicMessagesApi()],
+	["openai-completions", openAICompletionsApi()],
+	["openai-responses", openAIResponsesApi()],
+	["openai-codex-responses", openAICodexResponsesApi()],
+	["azure-openai-responses", azureOpenAIResponsesApi()],
+	["google-generative-ai", googleGenerativeAIApi()],
+	["google-vertex", googleVertexApi()],
+	["mistral-conversations", mistralConversationsApi()],
+	["bedrock-converse-stream", bedrockConverseStreamApi()],
+	["pi-messages", piMessagesApi()],
+];
+
+export function registerEngineBuiltins(): void {
+	if (builtinsRegistered) return;
+	builtinsRegistered = true;
+	for (const [api, streams] of BUILTIN_APIS) {
+		if (!getEngineApiProvider(api)) registerEngineApiProvider({ api, ...streams });
+		const registered = getEngineApiProvider(api);
+		if (registered) builtinInstances.set(api, registered);
+	}
+}
+
+function withEnvApiKey<T extends StreamOptions | SimpleStreamOptions>(
+	model: Model<Api>,
+	options: T | undefined,
+): T | undefined {
+	if (typeof options?.apiKey === "string" && options.apiKey.trim().length > 0) return options;
+	const apiKey = getEngineEnvApiKey(model.provider, options?.env);
+	if (!apiKey || apiKey === "<authenticated>") return options;
+	return { ...options, apiKey } as T;
+}
+
+function builtinProvider(model: Model<Api>) {
+	if (getEngineApiProvider(model.api) !== builtinInstances.get(model.api)) return undefined;
+	const provider = engineModels.getProvider(model.provider);
+	return provider?.getModels().some((candidate) => candidate.api === model.api) ? provider : undefined;
+}
+
+function resolved(api: Api): EngineRegisteredApiProvider {
+	const provider = getEngineApiProvider(api);
+	if (!provider) throw new Error(`No API provider registered for api: ${api}`);
+	return provider;
+}
+
+function hasCloudflareAuth(options?: StreamOptions): boolean {
+	return (
+		(typeof options?.apiKey === "string" && options.apiKey.trim().length > 0) ||
+		typeof options?.headers?.["cf-aig-authorization"] === "string"
+	);
+}
+
+export function engineStream(
+	model: Model<Api>,
+	context: Context,
+	options?: StreamOptions,
+): AssistantMessageEventStream {
+	registerEngineBuiltins();
+	if (compatUniverse) return compatUniverse.stream(model, context, options);
+	const provider = builtinProvider(model);
+	if (provider) {
+		if (model.provider.startsWith("cloudflare-") && !hasCloudflareAuth(options)) {
+			return engineModels.stream(model, context, options);
+		}
+		return provider.stream(model, context, withEnvApiKey(model, options));
+	}
+	return resolved(model.api).stream(model, context, withEnvApiKey(model, options));
+}
+
+export function engineStreamSimple(
+	model: Model<Api>,
+	context: Context,
+	options?: SimpleStreamOptions,
+): AssistantMessageEventStream {
+	registerEngineBuiltins();
+	if (compatUniverse) return compatUniverse.streamSimple(model, context, options);
+	const provider = builtinProvider(model);
+	if (provider) {
+		if (model.provider.startsWith("cloudflare-") && !hasCloudflareAuth(options)) {
+			return engineModels.streamSimple(model, context, options);
+		}
+		return provider.streamSimple(model, context, withEnvApiKey(model, options));
+	}
+	return resolved(model.api).streamSimple(model, context, withEnvApiKey(model, options));
+}
+
+export async function completeEngineSimple(
+	model: Model<Api>,
+	context: Context,
+	options?: SimpleStreamOptions,
+): Promise<AssistantMessage> {
+	return engineStreamSimple(model, context, options).result();
+}
+
+export function registerEngineFauxProvider(options: RegisterFauxProviderOptions = {}): FauxProviderRegistration {
+	registerEngineBuiltins();
+	const core = createFauxCore(options);
+	const sourceId = `faux-provider-${Math.random().toString(36).slice(2, 10)}`;
+	registerEngineApiProvider({ api: core.api, stream: core.stream, streamSimple: core.streamSimple }, sourceId);
+	return {
+		api: core.api,
+		models: core.models,
+		getModel: core.getModel,
+		state: core.state,
+		setResponses: core.setResponses,
+		appendResponses: core.appendResponses,
+		getPendingResponseCount: core.getPendingResponseCount,
+		unregister() {
+			unregisterEngineApiProviders(sourceId);
+		},
+	};
+}
+
+/**
+ * Join Pi's process-global registry before importing an external runtime.
+ * This is intentionally the only dynamic /compat edge: no configured plugin,
+ * no aggregate module. Existing Clio overrides are mirrored before plugin
+ * evaluation so plugin registrations retain their historical last-writer wins.
+ */
+export async function activateExternalPluginApiBridge(): Promise<void> {
+	if (compatUniverse) return;
+	compatUniversePromise ??= (async () => {
+		registerEngineBuiltins();
+		const compat = (await import("@earendil-works/pi-ai/compat")) as CompatUniverse;
+		for (const [api, entry] of registry) {
+			// Pi's compat import has already installed its own built-ins and must keep
+			// those identities so provider-owned auth/header dispatch remains active.
+			if (entry.provider === builtinInstances.get(api)) continue;
+			compat.registerApiProvider(entry.provider, entry.sourceId);
+		}
+		compatUniverse = compat;
+	})().catch((error: unknown) => {
+		compatUniversePromise = undefined;
+		throw error;
+	});
+	await compatUniversePromise;
+}
+
+registerEngineBuiltins();

package/src/engine/apis/index.ts

@@ -1,10 +1,7 @@
-import { registerApiProvider } from "@earendil-works/pi-ai/compat";
-
-import { lmstudioNativeApiProvider } from "./lmstudio-native.js";
+import { registerEngineApiProvider } from "../api-registry.js";
 import { ollamaNativeApiProvider } from "./ollama-native.js";
 import { openAICompletionsApiProvider } from "./openai-completions.js";
 
-export { lmstudioNativeApiProvider } from "./lmstudio-native.js";
 export { ollamaNativeApiProvider } from "./ollama-native.js";
 export { openAICompletionsApiProvider } from "./openai-completions.js";
 export { setGlobalDefaultMaxOutputTokens } from "./output-budget.js";
@@ -14,7 +11,6 @@ let registered = false;
 export function registerClioApiProviders(): void {
 	if (registered) return;
 	registered = true;
-	registerApiProvider(openAICompletionsApiProvider, "clio");
-	registerApiProvider(ollamaNativeApiProvider, "clio");
-	registerApiProvider(lmstudioNativeApiProvider, "clio");
+	registerEngineApiProvider(openAICompletionsApiProvider, "clio");
+	registerEngineApiProvider(ollamaNativeApiProvider, "clio");
 }

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

@@ -2,6 +2,7 @@ import { performance } from "node:perf_hooks";
 import { sleep } from "../../core/timers.js";
 import {
 	type ResidencyAdapter,
+	ResidencyPreconditionError,
 	reconcileResidency,
 	resetResidencyState,
 	residencyManaged,
@@ -42,7 +43,20 @@ export interface LlamaCppResidencyInput {
 const LOAD_TIMEOUT_MS = 120_000;
 const POLL_INTERVAL_MS = 500;
 
-type LlamaCppModelState = "loaded" | "loading" | "unloaded" | "failed" | "unknown";
+/**
+ * `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;
@@ -69,7 +83,9 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 function routerModelState(entry: Record<string, unknown>): LlamaCppModelState {
 	const status = entry.status;
 	const state = isRecord(status) ? status.value : status;
-	if (state === "loaded" || state === "loading" || state === "unloaded" || state === "failed") return state;
+	if (state === "loaded" || state === "loading" || state === "sleeping" || state === "unloaded" || state === "failed") {
+		return state;
+	}
 	return "unknown";
 }
 
@@ -87,10 +103,10 @@ function parseRouterModels(payload: unknown): LlamaCppRouterModel[] {
 }
 
 function residentModel(model: LlamaCppRouterModel): boolean {
-	return model.state === "loaded" || model.state === "loading";
+	return isResidentState(model.state);
 }
 
-/** Extract resident (loaded or loading) model records from a /v1/models payload. */
+/** Extract resident (loaded, loading, or sleeping) model records from a /v1/models payload. */
 export function parseLlamaCppResidentModels(payload: unknown): LlamaCppResidentModel[] {
 	return parseRouterModels(payload)
 		.filter(residentModel)
@@ -169,7 +185,10 @@ async function waitForLoaded(input: LlamaCppResidencyInput, fetchImpl: typeof fe
 	while (performance.now() - started < LOAD_TIMEOUT_MS) {
 		const models = await fetchRouterModels(input, fetchImpl);
 		const model = models.find((entry) => entry.id === modelId);
-		if (model?.state === "loaded") return;
+		// 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);
 	}
@@ -182,7 +201,11 @@ async function ensureModelLoaded(
 	modelId: string,
 	knownState: LlamaCppModelState | undefined,
 ): Promise<void> {
-	if (knownState === "loaded") return;
+	// 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);
 }
@@ -206,14 +229,16 @@ async function restoreDisplacedPinned(
 	let changed = false;
 	for (const model of pinned) {
 		const state = current.find((entry) => entry.id === model.id)?.state;
-		if (state === "loaded") continue;
+		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?.state !== "loaded") throw new Error(`pinned-resident restore displaced '${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. */
@@ -235,15 +260,30 @@ export async function ensureLlamaCppResidency(input: LlamaCppResidencyInput): Pr
 			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 === "loaded") return;
+			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;

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

@@ -1,15 +1,15 @@
 /**
  * LM Studio-specific residency arithmetic, kept pure so the fit and duplicate
- * rules are testable without a server or an SDK socket.
+ * rules are testable without a server connection.
  *
- * LM Studio exposes no VRAM telemetry: neither the SDK nor `/api/v1/models`
- * reports total or free GPU memory, and `gpuStrictVramCap` caps GPU offload
+ * 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, a
- * just-in-time load is capped at {@link CO_RESIDENT_CONTEXT_CEILING} tokens.
+ * 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
@@ -74,19 +74,3 @@ export function fitLoadContextLength(input: ContextFitInput): ContextFitResult {
 	}
 	return { contextLength: ceiling, clampedFrom: input.requested, neighbours };
 }
-
-/**
- * Instances of `keepModelId` beyond the one Clio will use. LM Studio's load path
- * happily creates a second instance of an already-resident model key (observed:
- * `google/gemma-4-26b-a4b-qat:2`), and each instance holds a full weight copy
- * and KV cache. The extras are the same model, so releasing them never takes a
- * role's model away: whatever pointed at that key is still served by the
- * survivor.
- */
-export function duplicateInstances<T extends LmStudioResidentInstance>(
-	resident: ReadonlyArray<T>,
-	keepModelId: string,
-): T[] {
-	const instances = resident.filter((entry) => entry.modelKey === keepModelId);
-	return instances.slice(1);
-}

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