@iowarp/clio-coder 0.3.1 → 0.3.2

package/src/domains/providers/runtimes/local-native/lmstudio-native.ts

@@ -1,491 +0,0 @@
-import { performance } from "node:perf_hooks";
-import { LMStudioClient } from "@lmstudio/sdk";
-import { CLIO_MIN_CONTEXT_WINDOW, CLIO_MIN_MAX_OUTPUT_TOKENS } from "../../../../core/context-floor.js";
-import type { Api, Model } from "../../../../engine/types.js";
-import { mergeCapabilities } from "../../capabilities.js";
-import { probeJson } from "../../probe/http.js";
-import { type CapabilityFlags, EMPTY_CAPABILITIES } from "../../types/capability-flags.js";
-import type { KnowledgeBaseHit } from "../../types/knowledge-base.js";
-import { extractLocalModelQuirks } from "../../types/local-model-quirks.js";
-import type { ProbeContext, ProbeModelStatus, ProbeResult, RuntimeDescriptor } from "../../types/runtime-descriptor.js";
-import type { TargetDescriptor } from "../../types/target-descriptor.js";
-import { lmStudioQuietLogger } from "../common/lmstudio-logger.js";
-import { type ClioLocalModelMetadata, stripTrailingSlash, targetLifecycle } from "../common/local-synth.js";
-
-const defaultCapabilities: CapabilityFlags = {
-	...EMPTY_CAPABILITIES,
-	chat: true,
-	tools: true,
-	toolCallFormat: "openai",
-	vision: true,
-	structuredOutputs: "json-schema",
-	contextWindow: CLIO_MIN_CONTEXT_WINDOW,
-	maxTokens: CLIO_MIN_MAX_OUTPUT_TOKENS,
-};
-
-function toWebSocketUrl(url: string): string {
-	const trimmed = stripTrailingSlash(url);
-	if (trimmed.startsWith("ws://") || trimmed.startsWith("wss://")) return trimmed;
-	if (trimmed.startsWith("https://")) return `wss://${trimmed.slice("https://".length)}`;
-	if (trimmed.startsWith("http://")) return `ws://${trimmed.slice("http://".length)}`;
-	return `ws://${trimmed}`;
-}
-
-function toHttpUrl(url: string): string {
-	const trimmed = stripTrailingSlash(url);
-	if (trimmed.startsWith("ws://")) return `http://${trimmed.slice("ws://".length)}`;
-	if (trimmed.startsWith("wss://")) return `https://${trimmed.slice("wss://".length)}`;
-	if (trimmed.startsWith("http://") || trimmed.startsWith("https://")) return trimmed;
-	return `http://${trimmed}`;
-}
-
-function buildClient(target: TargetDescriptor, ctx: ProbeContext): LMStudioClient | { error: string } {
-	if (!target.url) return { error: "target has no url" };
-	try {
-		const opts: ConstructorParameters<typeof LMStudioClient>[0] = {
-			baseUrl: toWebSocketUrl(target.url),
-			logger: lmStudioQuietLogger,
-		};
-		const auth = target.auth;
-		const envName = auth?.apiKeyEnvVar;
-		if (envName && ctx.credentialsPresent.has(envName)) {
-			const value = process.env[envName];
-			if (value) opts.clientPasskey = value;
-		}
-		return new LMStudioClient(opts);
-	} catch (err) {
-		return { error: err instanceof Error ? err.message : String(err) };
-	}
-}
-
-async function withTimeout<T>(task: Promise<T>, timeoutMs: number, signal?: AbortSignal): Promise<T> {
-	return new Promise<T>((resolve, reject) => {
-		const timer = setTimeout(() => reject(new Error(`timeout after ${timeoutMs}ms`)), timeoutMs);
-		const onAbort = () => {
-			clearTimeout(timer);
-			reject(new Error("aborted by caller"));
-		};
-		if (signal) {
-			if (signal.aborted) {
-				clearTimeout(timer);
-				reject(new Error("aborted by caller"));
-				return;
-			}
-			signal.addEventListener("abort", onAbort, { once: true });
-		}
-		task
-			.then((value) => {
-				clearTimeout(timer);
-				if (signal) signal.removeEventListener("abort", onAbort);
-				resolve(value);
-			})
-			.catch((err) => {
-				clearTimeout(timer);
-				if (signal) signal.removeEventListener("abort", onAbort);
-				reject(err);
-			});
-	});
-}
-
-interface LmStudioV0ModelsResponse {
-	data?: unknown;
-}
-
-interface LmStudioV0ModelEntry {
-	id?: unknown;
-	state?: unknown;
-	loaded_context_length?: unknown;
-	max_context_length?: unknown;
-	type?: unknown;
-	capabilities?: unknown;
-}
-
-interface LmStudioV1ModelsResponse {
-	models?: unknown;
-}
-
-interface LmStudioV1ModelEntry {
-	key?: unknown;
-	type?: unknown;
-	loaded_instances?: unknown;
-	max_context_length?: unknown;
-	capabilities?: unknown;
-}
-
-interface LmStudioModelSummary {
-	id: string;
-	loaded?: boolean;
-	loadedContextLength?: number;
-	maxContextLength?: number;
-	vision?: boolean;
-	tools?: boolean;
-	reasoning?: boolean;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
-function v0ModelEntries(payload: LmStudioV0ModelsResponse | undefined): LmStudioV0ModelEntry[] {
-	if (!Array.isArray(payload?.data)) return [];
-	return payload.data.filter((row): row is LmStudioV0ModelEntry => isRecord(row));
-}
-
-function v1ModelEntries(payload: LmStudioV1ModelsResponse | undefined): LmStudioV1ModelEntry[] {
-	if (!Array.isArray(payload?.models)) return [];
-	return payload.models.filter((row): row is LmStudioV1ModelEntry => isRecord(row));
-}
-
-function positiveNumber(value: unknown): number | undefined {
-	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
-}
-
-function loadedContextFromV1Instance(value: unknown): number | undefined {
-	if (!isRecord(value) || !isRecord(value.config)) return undefined;
-	return positiveNumber(value.config.context_length);
-}
-
-function firstLoadedContextFromV1(entry: LmStudioV1ModelEntry): number | undefined {
-	if (!Array.isArray(entry.loaded_instances)) return undefined;
-	for (const instance of entry.loaded_instances) {
-		const contextLength = loadedContextFromV1Instance(instance);
-		if (contextLength !== undefined) return contextLength;
-	}
-	return undefined;
-}
-
-function capabilityObject(entry: LmStudioV1ModelEntry): Record<string, unknown> | null {
-	return isRecord(entry.capabilities) ? entry.capabilities : null;
-}
-
-function v1Tools(entry: LmStudioV1ModelEntry): boolean | undefined {
-	const caps = capabilityObject(entry);
-	if (!caps) return undefined;
-	return caps.trained_for_tool_use === true;
-}
-
-function v1Vision(entry: LmStudioV1ModelEntry): boolean | undefined {
-	const caps = capabilityObject(entry);
-	if (caps && typeof caps.vision === "boolean") return caps.vision;
-	if (typeof entry.type === "string") return entry.type === "vlm";
-	return undefined;
-}
-
-function v1Reasoning(entry: LmStudioV1ModelEntry): boolean | undefined {
-	const caps = capabilityObject(entry);
-	if (!caps || !("reasoning" in caps)) return undefined;
-	const reasoning = caps.reasoning;
-	if (typeof reasoning === "boolean") return reasoning;
-	return isRecord(reasoning);
-}
-
-function summaryFromV1(entry: LmStudioV1ModelEntry): LmStudioModelSummary | null {
-	if (typeof entry.key !== "string" || entry.key.trim().length === 0) return null;
-	const summary: LmStudioModelSummary = { id: entry.key };
-	if (Array.isArray(entry.loaded_instances)) summary.loaded = entry.loaded_instances.length > 0;
-	const loadedContextLength = firstLoadedContextFromV1(entry);
-	if (loadedContextLength !== undefined) summary.loadedContextLength = loadedContextLength;
-	const maxContextLength = positiveNumber(entry.max_context_length);
-	if (maxContextLength !== undefined) summary.maxContextLength = maxContextLength;
-	const vision = v1Vision(entry);
-	if (vision !== undefined) summary.vision = vision;
-	const tools = v1Tools(entry);
-	if (tools !== undefined) summary.tools = tools;
-	const reasoning = v1Reasoning(entry);
-	if (reasoning !== undefined) summary.reasoning = reasoning;
-	return summary;
-}
-
-function summaryFromV0(entry: LmStudioV0ModelEntry): LmStudioModelSummary | null {
-	if (typeof entry.id !== "string" || entry.id.trim().length === 0) return null;
-	const summary: LmStudioModelSummary = { id: entry.id };
-	const loadedContextLength = positiveNumber(entry.loaded_context_length);
-	if (typeof entry.state === "string") summary.loaded = entry.state === "loaded";
-	else if (loadedContextLength !== undefined) summary.loaded = true;
-	if (loadedContextLength !== undefined) summary.loadedContextLength = loadedContextLength;
-	const maxContextLength = positiveNumber(entry.max_context_length);
-	if (maxContextLength !== undefined) summary.maxContextLength = maxContextLength;
-	if (typeof entry.type === "string") summary.vision = entry.type === "vlm";
-	if (Array.isArray(entry.capabilities)) {
-		summary.tools = entry.capabilities.some((capability) => capability === "tool_use");
-	}
-	return summary;
-}
-
-/**
- * Fold rows that share a wire model id into one summary.
- *
- * LM Studio lists one row per downloaded copy, so two quantizations of the same
- * weights appear twice under the same `key` and only one of them is resident.
- * Keyed by id with last-write-wins, the unloaded copy answers for the model: the
- * per-model view then reports `unloaded` at `max_context_length` while an
- * instance is serving at a smaller loaded window, which is a false residency
- * warning and a planner budgeting against a window the backend does not have.
- * The resident row wins field by field; the other fills what it left blank.
- */
-function foldDuplicateSummaries(entries: ReadonlyArray<LmStudioModelSummary>): LmStudioModelSummary[] {
-	const byId = new Map<string, LmStudioModelSummary>();
-	for (const entry of entries) {
-		const previous = byId.get(entry.id);
-		byId.set(entry.id, previous ? mergeSummaries(previous, entry) : entry);
-	}
-	return [...byId.values()];
-}
-
-function mergeSummaries(first: LmStudioModelSummary, second: LmStudioModelSummary): LmStudioModelSummary {
-	const [primary, secondary] = second.loaded === true && first.loaded !== true ? [second, first] : [first, second];
-	const merged: LmStudioModelSummary = { id: primary.id };
-	const loaded = primary.loaded ?? secondary.loaded;
-	if (loaded !== undefined) merged.loaded = loaded;
-	const loadedContextLength = primary.loadedContextLength ?? secondary.loadedContextLength;
-	if (loadedContextLength !== undefined) merged.loadedContextLength = loadedContextLength;
-	const maxContextLength = primary.maxContextLength ?? secondary.maxContextLength;
-	if (maxContextLength !== undefined) merged.maxContextLength = maxContextLength;
-	const vision = primary.vision ?? secondary.vision;
-	if (vision !== undefined) merged.vision = vision;
-	const tools = primary.tools ?? secondary.tools;
-	if (tools !== undefined) merged.tools = tools;
-	const reasoning = primary.reasoning ?? secondary.reasoning;
-	if (reasoning !== undefined) merged.reasoning = reasoning;
-	return merged;
-}
-
-function selectCapabilityEntry(
-	entries: ReadonlyArray<LmStudioModelSummary>,
-	target: TargetDescriptor,
-): LmStudioModelSummary | null {
-	const configured = target.defaultModel?.trim();
-	if (configured) {
-		return entries.find((entry) => entry.id === configured) ?? null;
-	}
-	return (
-		entries.find((entry) => entry.loadedContextLength !== undefined) ??
-		entries.find((entry) => entry.maxContextLength !== undefined) ??
-		entries[0] ??
-		null
-	);
-}
-
-function capabilitiesFromModelEntry(entry: LmStudioModelSummary | null): Partial<CapabilityFlags> | undefined {
-	if (!entry) return undefined;
-	const caps: Partial<CapabilityFlags> = {};
-	if (entry.vision !== undefined) caps.vision = entry.vision;
-	if (entry.tools !== undefined) caps.tools = entry.tools;
-	if (entry.reasoning !== undefined) caps.reasoning = entry.reasoning;
-	const contextWindow = entry.loadedContextLength ?? entry.maxContextLength;
-	if (contextWindow !== undefined) caps.contextWindow = contextWindow;
-	return Object.keys(caps).length > 0 ? caps : undefined;
-}
-
-function modelCapabilitiesFromSummaries(
-	entries: ReadonlyArray<LmStudioModelSummary>,
-): Record<string, Partial<CapabilityFlags>> {
-	const out: Record<string, Partial<CapabilityFlags>> = {};
-	for (const entry of entries) {
-		const caps = capabilitiesFromModelEntry(entry);
-		if (!caps) continue;
-		out[entry.id] = caps;
-	}
-	return out;
-}
-
-function modelStatesFromSummaries(
-	entries: ReadonlyArray<LmStudioModelSummary>,
-): Record<string, ProbeModelStatus> | undefined {
-	const out: Record<string, ProbeModelStatus> = {};
-	for (const entry of entries) {
-		if (entry.loaded === undefined) continue;
-		const status: ProbeModelStatus = { state: entry.loaded ? "loaded" : "unloaded" };
-		// The window the resident instance was opened with, carried alongside the
-		// load state so the planner and the residency notice read one view.
-		if (entry.loaded && entry.loadedContextLength !== undefined) status.contextLength = entry.loadedContextLength;
-		out[entry.id] = status;
-	}
-	return Object.keys(out).length > 0 ? out : undefined;
-}
-
-function modelsProbeHeaders(target: TargetDescriptor, ctx: ProbeContext): Record<string, string> | undefined {
-	const headers: Record<string, string> = { ...(target.auth?.headers ?? {}) };
-	const envName = target.auth?.apiKeyEnvVar;
-	if (envName && ctx.credentialsPresent.has(envName)) {
-		const key = process.env[envName]?.trim();
-		if (key) headers.authorization = `Bearer ${key}`;
-	}
-	return Object.keys(headers).length > 0 ? headers : undefined;
-}
-
-async function probeApiModels(target: TargetDescriptor, ctx: ProbeContext): Promise<ProbeResult> {
-	if (!target.url) return { ok: false, error: "target has no url" };
-	const headers = modelsProbeHeaders(target, ctx);
-	const v1 = await probeApiV1Models(target, ctx, headers);
-	if (v1.ok) return v1;
-	const v0 = await probeApiV0Models(target, ctx, headers);
-	return v0.ok ? v0 : v1;
-}
-
-async function probeApiV1Models(
-	target: TargetDescriptor,
-	ctx: ProbeContext,
-	headers: Record<string, string> | undefined,
-): Promise<ProbeResult> {
-	const opts: { url: string; timeoutMs: number; headers?: Record<string, string> } = {
-		url: `${toHttpUrl(target.url ?? "")}/api/v1/models`,
-		timeoutMs: ctx.httpTimeoutMs,
-	};
-	if (headers) opts.headers = headers;
-	const result = await (ctx.signal
-		? probeJson<LmStudioV1ModelsResponse>({ ...opts, signal: ctx.signal })
-		: probeJson<LmStudioV1ModelsResponse>(opts));
-	if (!result.ok) return result;
-	return probeResultFromV1Models(result.data, target, result.latencyMs);
-}
-
-/**
- * The pure parse of an `/api/v1/models` payload, exported so the fold over
- * duplicate model keys is testable against the shape LM Studio actually serves.
- */
-export function probeResultFromV1Models(data: unknown, target: TargetDescriptor, latencyMs?: number): ProbeResult {
-	const entries = v1ModelEntries(data as LmStudioV1ModelsResponse | undefined)
-		.map(summaryFromV1)
-		.filter((entry): entry is LmStudioModelSummary => entry !== null);
-	return probeResultFromSummaries(entries, target, latencyMs);
-}
-
-async function probeApiV0Models(
-	target: TargetDescriptor,
-	ctx: ProbeContext,
-	headers: Record<string, string> | undefined,
-): Promise<ProbeResult> {
-	const opts: { url: string; timeoutMs: number; headers?: Record<string, string> } = {
-		url: `${toHttpUrl(target.url ?? "")}/api/v0/models`,
-		timeoutMs: ctx.httpTimeoutMs,
-	};
-	if (headers) opts.headers = headers;
-	const result = await (ctx.signal
-		? probeJson<LmStudioV0ModelsResponse>({ ...opts, signal: ctx.signal })
-		: probeJson<LmStudioV0ModelsResponse>(opts));
-	if (!result.ok) return result;
-	const entries = v0ModelEntries(result.data)
-		.map(summaryFromV0)
-		.filter((entry): entry is LmStudioModelSummary => entry !== null);
-	return probeResultFromSummaries(entries, target, result.latencyMs);
-}
-
-function probeResultFromSummaries(
-	rows: ReadonlyArray<LmStudioModelSummary>,
-	target: TargetDescriptor,
-	latencyMs: number | undefined,
-): ProbeResult {
-	const entries = foldDuplicateSummaries(rows);
-	const models = entries.map((entry) => entry.id);
-	const capabilityEntry = selectCapabilityEntry(entries, target);
-	const discoveredCapabilities = capabilitiesFromModelEntry(capabilityEntry);
-	const modelCapabilities = modelCapabilitiesFromSummaries(entries);
-	const modelStates = modelStatesFromSummaries(entries);
-	const out: ProbeResult = { ok: true, models };
-	if (typeof latencyMs === "number") out.latencyMs = latencyMs;
-	if (modelStates) out.modelStates = modelStates;
-	if (Object.keys(modelCapabilities).length > 0) out.modelCapabilities = modelCapabilities;
-	if (discoveredCapabilities) {
-		out.discoveredCapabilities = discoveredCapabilities;
-		if (capabilityEntry) out.capabilityModelId = capabilityEntry.id;
-	}
-	return out;
-}
-
-const lmstudioNativeRuntime: RuntimeDescriptor = {
-	id: "lmstudio-native",
-	displayName: "LM Studio (native SDK)",
-	kind: "http",
-	tier: "local-native",
-	apiFamily: "lmstudio-native",
-	auth: "api-key",
-	defaultCapabilities,
-	async probe(target, ctx): Promise<ProbeResult> {
-		const built = buildClient(target, ctx);
-		if ("error" in built) return { ok: false, error: built.error };
-		const client = built;
-		const started = performance.now();
-		try {
-			const [version, apiModels] = await Promise.all([
-				withTimeout(client.system.getLMStudioVersion(), ctx.httpTimeoutMs, ctx.signal),
-				probeApiModels(target, ctx),
-			]);
-			const latencyMs = Math.round(performance.now() - started);
-			const result: ProbeResult = { ok: true, latencyMs, serverVersion: version.version };
-			if (apiModels.ok) {
-				if (apiModels.models) result.models = apiModels.models;
-				if (apiModels.modelStates) result.modelStates = apiModels.modelStates;
-				if (apiModels.discoveredCapabilities) result.discoveredCapabilities = apiModels.discoveredCapabilities;
-				if (apiModels.modelCapabilities) result.modelCapabilities = apiModels.modelCapabilities;
-				if (apiModels.capabilityModelId) result.capabilityModelId = apiModels.capabilityModelId;
-			}
-			return result;
-		} catch (err) {
-			return {
-				ok: false,
-				latencyMs: Math.round(performance.now() - started),
-				error: err instanceof Error ? err.message : String(err),
-			};
-		}
-	},
-	async probeModels(target, ctx): Promise<string[]> {
-		const built = buildClient(target, ctx);
-		if ("error" in built) return [];
-		const client = built;
-		try {
-			const [downloaded, loaded] = await Promise.all([
-				withTimeout(client.system.listDownloadedModels("llm"), ctx.httpTimeoutMs, ctx.signal),
-				withTimeout(client.llm.listLoaded(), ctx.httpTimeoutMs, ctx.signal),
-			]);
-			const keys = new Set<string>();
-			for (const info of downloaded) keys.add(info.modelKey);
-			for (const llm of loaded) keys.add(llm.modelKey);
-			return [...keys];
-		} catch {
-			return [];
-		}
-	},
-	synthesizeModel(target: TargetDescriptor, wireModelId: string, kb: KnowledgeBaseHit | null): Model<Api> {
-		const caps = mergeCapabilities(
-			defaultCapabilities,
-			kb?.entry.capabilities ?? null,
-			null,
-			target.capabilities ?? null,
-		);
-		const baseUrl = target.url ? toWebSocketUrl(target.url) : "";
-		const pricing = target.pricing;
-		const quirks = extractLocalModelQuirks(kb?.entry.quirks);
-		const lifecycle = targetLifecycle(target);
-		const model: Model<Api> & ClioLocalModelMetadata = {
-			id: wireModelId,
-			name: `${wireModelId} (${target.id})`,
-			api: "lmstudio-native",
-			provider: "lmstudio",
-			baseUrl,
-			reasoning: caps.reasoning,
-			input: caps.vision ? ["text", "image"] : ["text"],
-			cost: {
-				input: pricing?.input ?? 0,
-				output: pricing?.output ?? 0,
-				cacheRead: pricing?.cacheRead ?? 0,
-				cacheWrite: pricing?.cacheWrite ?? 0,
-			},
-			contextWindow: caps.contextWindow,
-			maxTokens: caps.maxTokens,
-			clio: {
-				targetId: target.id,
-				runtimeId: target.runtime,
-				...(lifecycle ? { lifecycle } : {}),
-				...(target.gateway === true ? { gateway: true } : {}),
-				...(kb?.entry.family ? { family: kb.entry.family } : {}),
-				...(quirks ? { quirks } : {}),
-			},
-		};
-		const headers = target.auth?.headers;
-		if (headers) model.headers = headers;
-		return model;
-	},
-};
-
-export default lmstudioNativeRuntime;