@iowarp/clio-coder 0.3.9 → 0.4.1

package/src/domains/providers/models/local-models/{clio-local-coding-targets.yaml → clio-coder-local-coding-targets.yaml}

@@ -308,7 +308,7 @@
     measuredUnder:
       hardware: unknown
       runtime: lmstudio
-      build: "unknown; the host was the operator's `dynamo` LM Studio machine, whose bundled build string was not recorded on this date"
+      build: "unknown; the host was a Windows LM Studio machine whose bundled build string was not recorded on this date"
       llamaCpp: "unknown; the measurement went through LM Studio's OpenAI-compatible port, which does not expose the underlying server argv"
       date: "2026-08-08"
       source: "commit b3db3b82 (fix(providers): thinking off reaches the wire for models that reason by default)"
@@ -884,12 +884,12 @@
     measuredUnder:
       hardware: unknown
       runtime: "lmstudio and its OpenAI-compatible port for the reasoning findings; an unrecorded llama.cpp host for the presence-penalty finding"
-      build: "unknown for both dates; the operator's `dynamo` host is a Windows LM Studio machine whose bundled build string was first recorded on 2026-08-29 as llama.cpp-win-x86_64-nvidia-cuda12-avx2, which is three weeks after the reasoning measurement and cannot be backdated to it"
+      build: "unknown for both dates; the Windows LM Studio measurement host's bundled build string was first recorded on 2026-08-29 as llama.cpp-win-x86_64-nvidia-cuda12-avx2, which is three weeks after the reasoning measurement and cannot be backdated to it"
       llamaCpp: "unknown; the reasoning measurement went through LM Studio's HTTP port, which does not expose the underlying server argv, and no argv survives for the dispatch that produced the presence-penalty value"
       date: "2026-08-08 (reasoning_effort and enable_thinking), 2026-07-06 (presence penalty)"
       source: "commits b3db3b82 and f7d76bf4"
       note: |
-        Three numbers here are measurements. On 2026-08-08 on `dynamo` this
+        Three numbers here are measurements. On 2026-08-08 on that host this
         model spent 98 of 103 completion tokens reasoning on "what is 17+25"
         with no thinking field set; chat_template_kwargs enable_thinking was
         inert, re-checked with unique prompts to rule out prompt-cache hits;
@@ -1268,7 +1268,7 @@
     maxTokens: 32768
   quirks:
     measuredUnder:
-      hardware: "unknown; the host was the operator's `dynamo` LM Studio machine"
+      hardware: "unknown; the host was a Windows LM Studio machine"
       runtime: "lmstudio, SDK 1.5.0 and its OpenAI-compatible port"
       build: "unknown; LM Studio's bundled llama.cpp build string was not recorded on this date"
       llamaCpp: "unknown; the measurement went through LM Studio, which does not expose the underlying server argv"

package/src/domains/providers/plugins.ts

@@ -4,7 +4,7 @@
  *   1. `~/.config/clio-coder/runtimes/`: any `.js` file whose default export is a valid
  *      RuntimeDescriptor. Resolved from `clioConfigDir()` so CLIO_CODER_HOME /
  *      CLIO_CODER_CONFIG_DIR overrides flow through.
- *   2. npm packages listed under `settings.runtimePlugins` (optional field).
+ *   2. npm packages listed under `settings.integrations.runtimePlugins`.
  *      Each package must export a `clioRuntimes: RuntimeDescriptor[]` array.
  *
  * Missing directories, import failures, and descriptor conflicts are logged

package/src/domains/providers/resolver.ts

@@ -117,7 +117,7 @@ function buildResult(
  *
  * Trailing `:low`/`:medium`/`:high`/`:xhigh`/`:minimal`/`:off` is parsed off
  * before matching and surfaced on the returned ref so callers can apply it
- * to settings.orchestrator.thinkingLevel.
+ * to settings.chat.thinkingLevel.
  */
 export function resolveModelReference(rawPattern: string, providers: ProvidersContract): ResolveModelResult {
 	const trimmed = rawPattern.trim();

package/src/domains/providers/runtimes/boot-manifest.ts

@@ -42,6 +42,7 @@ export const BUILTIN_RUNTIME_BOOT_MANIFEST: ReadonlyArray<RuntimeBootMetadata> =
 	{ id: "lmstudio", aliases: ["lmstudio-native"], kind: "http", tier: "local-native", auth: "api-key" },
 	{ id: "ollama-native", kind: "http", tier: "local-native", auth: "none" },
 	{ id: "anthropic-compat", kind: "http", tier: "protocol", auth: "api-key" },
+	{ id: "litellm", kind: "http", tier: "protocol", auth: "api-key" },
 	{ id: "openai-compat", kind: "http", tier: "protocol", auth: "api-key" },
 	{ id: "sglang", kind: "http", tier: "local-native", auth: "api-key" },
 	{ id: "vllm", kind: "http", tier: "local-native", auth: "api-key" },

package/src/domains/providers/runtimes/builtins.ts

@@ -36,6 +36,7 @@ import ollamaNative from "./local-native/ollama-native.js";
 import sglang from "./local-native/sglang.js";
 import vllm from "./local-native/vllm.js";
 import anthropicCompat from "./protocol/anthropic-compat.js";
+import litellm from "./protocol/litellm.js";
 import openaiCompat from "./protocol/openai-compat.js";
 
 const BUILTIN_RUNTIMES: ReadonlyArray<RuntimeDescriptor> = [
@@ -60,6 +61,7 @@ const BUILTIN_RUNTIMES: ReadonlyArray<RuntimeDescriptor> = [
 	lmstudio,
 	ollamaNative,
 	anthropicCompat,
+	litellm,
 	openaiCompat,
 	sglang,
 	vllm,

package/src/domains/providers/runtimes/cloud/alcf.ts

@@ -35,13 +35,13 @@ const KNOWN_MODELS: string[] = [
 
 type AlcfCluster = string;
 
-export function clusterFromUrl(url: string | undefined): AlcfCluster | null {
+function clusterFromUrl(url: string | undefined): AlcfCluster | null {
 	if (!url) return null;
 	const match = /\/resource_server\/([^/]+)\//.exec(url);
 	return match ? (match[1] ?? null) : null;
 }
 
-export function frameworkForCluster(cluster: AlcfCluster): string {
+function frameworkForCluster(cluster: AlcfCluster): string {
 	return cluster === "metis" ? "api" : "vllm";
 }
 
@@ -59,7 +59,7 @@ export function catalogModels(payload: CatalogPayload, cluster: string, framewor
 	return models.map((model) => String(model).trim()).filter((model) => model.length > 0);
 }
 
-export function runningModels(payload: JobsPayload): string[] {
+function runningModels(payload: JobsPayload): string[] {
 	const out: string[] = [];
 	for (const job of payload.running ?? []) {
 		for (const raw of String(job.Models ?? "").split(",")) {
@@ -162,7 +162,7 @@ const alcfRuntime: RuntimeDescriptor = {
 			provider: "alcf",
 			baseUrlForTarget: withAsIs,
 		});
-		const meta = (model as Model<Api> & { clio?: { chatTemplateKwargsUnsupported?: boolean } }).clio;
+		const meta = (model as Model<Api> & { clioCoder?: { chatTemplateKwargsUnsupported?: boolean } }).clioCoder;
 		if (meta) meta.chatTemplateKwargsUnsupported = true;
 		return model;
 	},

package/src/domains/providers/runtimes/common/lmstudio-http.ts

@@ -169,7 +169,7 @@ function reasoningOptions(capabilities: unknown): string[] | undefined {
 	return options.length > 0 ? options : undefined;
 }
 
-export function parseLmStudioV1Models(data: unknown): LmStudioModelInfo[] | null {
+function parseLmStudioV1Models(data: unknown): LmStudioModelInfo[] | null {
 	if (!isRecord(data) || !Array.isArray(data.models)) return null;
 	const models: LmStudioModelInfo[] = [];
 	for (const raw of data.models) {
@@ -285,10 +285,6 @@ export function resolveLmStudioInstance(
 	return { requestedId, wireModelId: requestedId, peerTargets: [], state: "unknown" };
 }
 
-export function resetLmStudioHostCatalogs(): void {
-	catalogsByHost.clear();
-}
-
 export function lmStudioReasoningLevels(options: ReadonlyArray<string> | undefined): ThinkingLevel[] {
 	if (!options || options.length === 0) return [...THINKING_LEVELS];
 	if (options.includes("on") && !options.includes("low") && !options.includes("medium") && !options.includes("high")) {

package/src/domains/providers/runtimes/common/local-synth.ts

@@ -7,10 +7,10 @@ import { extractLocalModelQuirks, type LocalModelQuirks } from "../../types/loca
 import type { RuntimeApiFamily } from "../../types/runtime-descriptor.js";
 import type { TargetDescriptor } from "../../types/target-descriptor.js";
 
-export type LocalModelLifecycle = "user-managed" | "clio-managed";
+export type LocalModelLifecycle = "user-managed" | "clio-coder-managed";
 
 export interface ClioLocalModelMetadata {
-	clio?: {
+	clioCoder?: {
 		targetId: string;
 		runtimeId: string;
 		/**
@@ -101,7 +101,7 @@ export function synthLocalModel(input: LocalSynthesisInput): Model<Api> {
 		},
 		contextWindow: caps.contextWindow,
 		maxTokens: caps.maxTokens,
-		clio: {
+		clioCoder: {
 			targetId: target.id,
 			runtimeId: target.runtime,
 			...(target.lifecycle ? { lifecycle: target.lifecycle } : {}),

package/src/domains/providers/runtimes/common/probe-helpers.ts

@@ -357,7 +357,7 @@ export interface LlamaCppRequestContextWindow {
  * 25% (issue #187). With `--kv-unified` every slot shares one sequence and
  * the total is the window.
  */
-export function llamaCppRequestContextWindow(flags: LlamaCppServerFlags): LlamaCppRequestContextWindow | undefined {
+function llamaCppRequestContextWindow(flags: LlamaCppServerFlags): LlamaCppRequestContextWindow | undefined {
 	const total = positiveNumber(flags.contextSize);
 	if (total === undefined) return undefined;
 	const parallel = positiveNumber(flags.parallel);
@@ -423,7 +423,7 @@ function booleanFlag(args: ReadonlyArray<string>, ...flags: ReadonlyArray<string
 	return undefined;
 }
 
-export function parseLlamaCppServerFlags(args: ReadonlyArray<string>): LlamaCppServerFlags {
+function parseLlamaCppServerFlags(args: ReadonlyArray<string>): LlamaCppServerFlags {
 	const flags: LlamaCppServerFlags = {};
 	const ctxSize = numberFlag(args, "--ctx-size", "-c");
 	if (ctxSize !== undefined) flags.contextSize = ctxSize;

package/src/domains/providers/runtimes/local-native/llamacpp-completion.ts

@@ -100,7 +100,7 @@ async function* streamSse(body: ReadableStream<Uint8Array>): AsyncGenerator<Comp
 		}
 	} finally {
 		if (droppedFrames > 0) {
-			process.stderr.write(`[clio:llamacpp] dropped ${droppedFrames} malformed stream frame(s)\n`);
+			process.stderr.write(`[clio-coder:llamacpp] dropped ${droppedFrames} malformed stream frame(s)\n`);
 		}
 		reader.releaseLock();
 	}

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

@@ -13,7 +13,6 @@ import {
 	listLmStudioModels,
 	lmStudioReasoningLevels,
 	loadedContextLength,
-	parseLmStudioV1Models,
 	resolveLmStudioInstance,
 } from "../common/lmstudio-http.js";
 import { synthLocalModel, withV1 } from "../common/local-synth.js";
@@ -181,12 +180,6 @@ function probeFromCatalog(catalog: LmStudioCatalog, target: TargetDescriptor): P
 	return result;
 }
 
-export function probeResultFromV1Models(data: unknown, target: TargetDescriptor, latencyMs?: number): ProbeResult {
-	const models = parseLmStudioV1Models(data);
-	if (!models) return { ok: false, error: "LM Studio /api/v1/models response has no models array" };
-	return probeFromCatalog({ ok: true, models, tier: "0.4+", ...(latencyMs !== undefined ? { latencyMs } : {}) }, target);
-}
-
 const lmstudioRuntime: RuntimeDescriptor = {
 	id: "lmstudio",
 	aliases: ["lmstudio-native"],
@@ -224,13 +217,13 @@ const lmstudioRuntime: RuntimeDescriptor = {
 		});
 		const metadata = (
 			model as Model<Api> & {
-				clio?: {
+				clioCoder?: {
 					chatTemplateKwargsUnsupported?: boolean;
 					lmstudioReasoningOptions?: ReadonlyArray<string>;
 					lmstudioDefaultModel?: string;
 				};
 			}
-		).clio;
+		).clioCoder;
 		if (metadata) {
 			metadata.chatTemplateKwargsUnsupported = true;
 			if (target.defaultModel) metadata.lmstudioDefaultModel = target.defaultModel;

package/src/domains/providers/runtimes/protocol/litellm.ts

@@ -0,0 +1,285 @@
+/**
+ * LiteLLM proxy: an OpenAI-compatible gateway that fronts a fleet.
+ *
+ * This is a separate runtime from `openai-compat` rather than a target flag on
+ * it, because a gateway answers two questions the generic protocol cannot.
+ *
+ * First, capability discovery. A gateway publishes semantic aliases: the client
+ * asks for `code` and the proxy decides that means `katcoder2.5-35b-moe` on one
+ * particular host. LiteLLM's `/v1/models` is the plain OpenAI listing, so every
+ * row flattens to a bare id and the context window, tool support, and modality
+ * of the model actually behind the alias are all erased. Reached over
+ * `openai-compat`, a 262k tool-calling coder is indistinguishable from a 4k
+ * chat toy, and Clio plans the session against its own assumed floor. LiteLLM
+ * publishes the real numbers on `/v1/model/info` instead, which is what this
+ * probe reads.
+ *
+ * Structured output is the one property worth stating explicitly, because
+ * getting it wrong is silent. `src/core/response-schema.ts` deliberately keys
+ * the schema dialect on runtime id and not on api family, since a generic
+ * OpenAI-compatible gateway answers HTTP 200 to a `response_format` spelling it
+ * does not implement and returns unconstrained JSON. LiteLLM earns its entry in
+ * that table by measurement rather than by assumption: against the homelab
+ * gateway on 2026-08-30, `{"type":"json_schema", json_schema:{...}}` was
+ * grammar-enforced end to end on both a llama.cpp upstream and an LM Studio
+ * upstream, `{"type":"json_object", schema:{...}}` was enforced on llama.cpp
+ * and rejected HTTP 400 by LM Studio, and the same prompt with no
+ * `response_format` returned plain prose. `drop_params: true` did not strip
+ * either spelling. The standard `json_schema` dialect is therefore the one that
+ * holds across every upstream, and it is what this runtime declares.
+ */
+
+import { CLIO_MIN_CONTEXT_WINDOW, CLIO_MIN_MAX_OUTPUT_TOKENS } from "../../../../core/context-floor.js";
+import type { Api, Model } from "../../../../engine/types.js";
+import { probeJson } from "../../probe/http.js";
+import type { CapabilityFlags } from "../../types/capability-flags.js";
+import type { KnowledgeBaseHit } from "../../types/knowledge-base.js";
+import type { ProbeContext, ProbeModelStatus, ProbeResult, RuntimeDescriptor } from "../../types/runtime-descriptor.js";
+import type { TargetDescriptor } from "../../types/target-descriptor.js";
+import { stripTrailingSlash, synthLocalModel, withV1 } from "../common/local-synth.js";
+
+const LITELLM_PROVIDER = "litellm";
+
+/**
+ * Conservative until the probe answers. A gateway that does not publish
+ * `model_info` has told Clio nothing, and claiming tools on a target whose tool
+ * surface is unknown produces a worker that fails on its first tool call rather
+ * than one that is never admitted.
+ */
+const defaultCapabilities: CapabilityFlags = {
+	chat: true,
+	tools: false,
+	reasoning: false,
+	vision: false,
+	audio: false,
+	embeddings: false,
+	rerank: false,
+	fim: false,
+	structuredOutputs: "json-schema",
+	contextWindow: CLIO_MIN_CONTEXT_WINDOW,
+	maxTokens: CLIO_MIN_MAX_OUTPUT_TOKENS,
+};
+
+/** The server root. This runtime's own paths carry `/v1` where they need it. */
+function rootUrl(target: TargetDescriptor): string | null {
+	if (!target.url) return null;
+	const trimmed = stripTrailingSlash(target.url);
+	return trimmed.endsWith("/v1") ? trimmed.slice(0, -"/v1".length) : trimmed;
+}
+
+function bearerHeaders(target: TargetDescriptor, ctx: ProbeContext): Record<string, string> {
+	const headers: Record<string, string> = { ...(target.auth?.headers ?? {}) };
+	const envName = target.auth?.apiKeyEnvVar;
+	const fromEnv = envName && ctx.credentialsPresent.has(envName) ? process.env[envName]?.trim() : undefined;
+	const token = ctx.authToken?.trim() || fromEnv;
+	if (token) headers.authorization = `Bearer ${token}`;
+	return headers;
+}
+
+interface LiteLLMModelInfoRow {
+	model_name?: unknown;
+	litellm_params?: { model?: unknown; api_base?: unknown };
+	model_info?: Record<string, unknown>;
+}
+
+interface LiteLLMModelInfoResponse {
+	data?: ReadonlyArray<LiteLLMModelInfoRow>;
+}
+
+interface LiteLLMModelsResponse {
+	data?: ReadonlyArray<{ id?: unknown }>;
+}
+
+function positiveInteger(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : undefined;
+}
+
+function boolean(value: unknown): boolean | undefined {
+	return typeof value === "boolean" ? value : undefined;
+}
+
+/**
+ * Project one LiteLLM `model_info` block onto Clio's capability flags.
+ *
+ * Only fields the gateway actually filled in are returned. A `model_info` that
+ * declares nothing leaves the whole record empty rather than reporting zeros,
+ * so the caller can tell "the gateway says this model has no vision" apart from
+ * "the gateway did not say", and merge accordingly.
+ */
+function capabilitiesFromLiteLLMModelInfo(info: Record<string, unknown>): Partial<CapabilityFlags> {
+	const caps: Partial<CapabilityFlags> = {};
+	const contextWindow = positiveInteger(info.max_input_tokens) ?? positiveInteger(info.max_tokens);
+	if (contextWindow !== undefined) caps.contextWindow = contextWindow;
+	const maxTokens = positiveInteger(info.max_output_tokens);
+	if (maxTokens !== undefined) caps.maxTokens = maxTokens;
+	const tools = boolean(info.supports_function_calling);
+	if (tools !== undefined) caps.tools = tools;
+	const vision = boolean(info.supports_vision);
+	if (vision !== undefined) caps.vision = vision;
+	const reasoning = boolean(info.supports_reasoning);
+	if (reasoning !== undefined) caps.reasoning = reasoning;
+	const audio = boolean(info.supports_audio_input);
+	if (audio !== undefined) caps.audio = audio;
+	// `mode` is LiteLLM's own surface discriminator. An embedding deployment is
+	// not a chat deployment, and admitting it as one produces a run that fails
+	// at the first completion rather than at selection.
+	if (info.mode === "embedding") {
+		caps.chat = false;
+		caps.embeddings = true;
+	}
+	if (info.mode === "rerank") {
+		caps.chat = false;
+		caps.rerank = true;
+	}
+	if (info.mode === "chat") caps.chat = true;
+	// Measured, not inferred: see the module header.
+	if (boolean(info.supports_response_schema) === true) caps.structuredOutputs = "json-schema";
+	return caps;
+}
+
+interface LiteLLMCatalog {
+	models: string[];
+	modelCapabilities: Record<string, Partial<CapabilityFlags>>;
+	modelStates: Record<string, ProbeModelStatus>;
+	/** Physical deployment behind each alias, for display. */
+	deployments: Record<string, { model: string; apiBase?: string }>;
+}
+
+const EMPTY_CATALOG: LiteLLMCatalog = { models: [], modelCapabilities: {}, modelStates: {}, deployments: {} };
+
+/**
+ * Read the catalog from `/v1/model/info`, falling back to `/v1/models`.
+ *
+ * The detail endpoint is the only one that carries capabilities, but it can be
+ * refused for a virtual key with narrower permissions than the master key. A
+ * gateway that answers the plain listing and refuses the detail is still usable;
+ * it just cannot tell Clio anything beyond which aliases exist, so the target
+ * falls back to its declared capabilities exactly as `openai-compat` would.
+ */
+async function fetchCatalog(base: string, ctx: ProbeContext, headers: Record<string, string>): Promise<LiteLLMCatalog> {
+	const detailOpts = { url: `${base}/v1/model/info`, timeoutMs: ctx.httpTimeoutMs, headers } as const;
+	const detail = await (ctx.signal
+		? probeJson<LiteLLMModelInfoResponse>({ ...detailOpts, signal: ctx.signal })
+		: probeJson<LiteLLMModelInfoResponse>(detailOpts));
+
+	if (detail.ok && Array.isArray(detail.data?.data)) {
+		const catalog: LiteLLMCatalog = { models: [], modelCapabilities: {}, modelStates: {}, deployments: {} };
+		for (const row of detail.data.data) {
+			if (typeof row?.model_name !== "string" || row.model_name.length === 0) continue;
+			const alias = row.model_name;
+			// One alias can carry several deployments. They share a name and Clio
+			// addresses them as one model, so the first row establishes the entry
+			// and later rows for the same alias are the load-balancing pool behind
+			// it rather than separate models.
+			if (catalog.deployments[alias] !== undefined) continue;
+			catalog.models.push(alias);
+			const caps = row.model_info ? capabilitiesFromLiteLLMModelInfo(row.model_info) : {};
+			if (Object.keys(caps).length > 0) catalog.modelCapabilities[alias] = caps;
+			const upstream = row.litellm_params?.model;
+			const apiBase = row.litellm_params?.api_base;
+			catalog.deployments[alias] = {
+				model: typeof upstream === "string" ? upstream : alias,
+				...(typeof apiBase === "string" ? { apiBase } : {}),
+			};
+		}
+		if (catalog.models.length > 0) return catalog;
+	}
+
+	const listOpts = { url: `${base}/v1/models`, timeoutMs: ctx.httpTimeoutMs, headers } as const;
+	const list = await (ctx.signal
+		? probeJson<LiteLLMModelsResponse>({ ...listOpts, signal: ctx.signal })
+		: probeJson<LiteLLMModelsResponse>(listOpts));
+	if (!list.ok || !Array.isArray(list.data?.data)) return EMPTY_CATALOG;
+	const models = list.data.data
+		.map((row) => (typeof row?.id === "string" ? row.id : null))
+		.filter((id): id is string => id !== null && id.length > 0);
+	return { models, modelCapabilities: {}, modelStates: {}, deployments: {} };
+}
+
+const litellmRuntime: RuntimeDescriptor = {
+	id: "litellm",
+	displayName: "LiteLLM gateway",
+	kind: "http",
+	tier: "protocol",
+	apiFamily: "openai-completions",
+	auth: "api-key",
+	defaultCapabilities,
+
+	async probe(target: TargetDescriptor, ctx: ProbeContext): Promise<ProbeResult> {
+		const base = rootUrl(target);
+		if (!base) return { ok: false, error: "target has no url" };
+		const headers = bearerHeaders(target, ctx);
+
+		// Liveness first, and deliberately on the unauthenticated endpoint. A
+		// gateway with authentication enforced answers 401 to `/v1/models` when
+		// credentials are missing or wrong, which is indistinguishable from an
+		// unreachable host if that is the only thing probed. `/health/liveliness`
+		// separates "the gateway is down" from "this key is not valid", and the
+		// two have completely different remedies.
+		const liveOpts = { url: `${base}/health/liveliness`, timeoutMs: ctx.httpTimeoutMs } as const;
+		const live = await (ctx.signal
+			? probeJson<unknown>({ ...liveOpts, signal: ctx.signal })
+			: probeJson<unknown>(liveOpts));
+		if (!live.ok) return { ok: false, error: live.error ?? "gateway is not reachable" };
+
+		const catalog = await fetchCatalog(base, ctx, headers);
+		if (catalog.models.length === 0) {
+			const result: ProbeResult = {
+				ok: false,
+				error: "gateway is live but served no model catalog; check the target's API key",
+			};
+			if (live.latencyMs !== undefined) result.latencyMs = live.latencyMs;
+			return result;
+		}
+
+		const result: ProbeResult = { ok: true, models: catalog.models };
+		if (live.latencyMs !== undefined) result.latencyMs = live.latencyMs;
+		if (Object.keys(catalog.modelCapabilities).length > 0) {
+			result.modelCapabilities = catalog.modelCapabilities;
+			const selected = target.defaultModel?.trim();
+			const selectedCaps = selected ? catalog.modelCapabilities[selected] : undefined;
+			if (selected && selectedCaps) {
+				result.discoveredCapabilities = selectedCaps;
+				result.capabilityModelId = selected;
+			}
+		}
+		const notes: string[] = [];
+		const configured = target.defaultModel?.trim();
+		if (configured && !catalog.models.includes(configured)) {
+			notes.push(`configured model '${configured}' is not in the gateway catalog`);
+		}
+		// Naming the physical model behind each alias is the difference between a
+		// catalog an operator can audit and a list of words.
+		const routed = Object.entries(catalog.deployments)
+			.map(([alias, deployment]) => `${alias}=${deployment.model}`)
+			.sort();
+		if (routed.length > 0) notes.push(`routes: ${routed.join(", ")}`);
+		if (notes.length > 0) result.notes = notes;
+		return result;
+	},
+
+	async probeModels(target: TargetDescriptor, ctx: ProbeContext): Promise<string[]> {
+		const base = rootUrl(target);
+		if (!base) return [];
+		return (await fetchCatalog(base, ctx, bearerHeaders(target, ctx))).models;
+	},
+
+	synthesizeModel(target: TargetDescriptor, wireModelId: string, kb: KnowledgeBaseHit | null): Model<Api> {
+		return synthLocalModel({
+			// A LiteLLM target is a gateway whether or not settings said so. The
+			// residency layer reads this to stay observe-only: the models behind an
+			// alias are the proxy's to load and evict, and a Clio stream that tried
+			// to manage them would be issuing load commands to a host that does not
+			// take them.
+			target: { ...target, gateway: true },
+			wireModelId,
+			kb,
+			defaultCapabilities,
+			apiFamily: "openai-completions",
+			provider: LITELLM_PROVIDER,
+			baseUrlForTarget: withV1,
+		});
+	},
+};
+
+export default litellmRuntime;

package/src/domains/providers/support.ts

@@ -59,6 +59,7 @@ const SUMMARY_BY_RUNTIME_ID: Readonly<Record<string, string>> = {
 	llamacpp: "llama.cpp server (auto-detect surface)",
 	"anthropic-compat": "Generic Anthropic-compatible REST",
 	"openai-compat": "Generic OpenAI-compatible REST",
+	litellm: "LiteLLM gateway with per-alias capability discovery and routed-model attribution",
 };
 
 function groupPriority(group: ProviderSupportGroup): number {

package/src/domains/providers/target-model-cache.ts

@@ -0,0 +1,124 @@
+/**
+ * Disposable per-target model catalogs discovered by provider probes.
+ *
+ * A live endpoint catalog is machine state, not operator policy. Persisting it
+ * in settings.yaml made a three-target config carry hundreds of volatile model
+ * ids. Cache files keep that snapshot available to a new process without
+ * turning the hand-edited settings file into a probe transcript.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { safeResourceWrite } from "../../core/safe-resource-write.js";
+import { clioCacheDir } from "../../core/xdg.js";
+import type { TargetDescriptor } from "./types/target-descriptor.js";
+
+export const TARGET_MODEL_CACHE_TTL_MS = 24 * 60 * 60 * 1_000;
+const TARGET_MODEL_CACHE_VERSION = 1;
+const TARGET_MODEL_CACHE_MAX_MODELS = 4_096;
+const TARGET_MODEL_CACHE_MAX_MODEL_ID_CHARS = 1_024;
+
+export interface TargetModelSnapshot {
+	version: 1;
+	targetId: string;
+	runtimeId: string;
+	url: string | null;
+	models: string[];
+	observedAt: string;
+}
+
+interface TargetModelCacheOptions {
+	cacheDir?: string;
+	nowMs?: number;
+	ttlMs?: number;
+}
+
+function targetCacheKey(targetId: string): string {
+	return createHash("sha256").update(targetId).digest("hex").slice(0, 24);
+}
+
+export function targetModelSnapshotPath(targetId: string, cacheDir = clioCacheDir()): string {
+	return join(cacheDir, "provider-target-models", `${targetCacheKey(targetId)}.json`);
+}
+
+function normalizedModels(models: ReadonlyArray<string>): string[] {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const raw of models) {
+		const model = raw.trim();
+		if (model.length === 0 || model.length > TARGET_MODEL_CACHE_MAX_MODEL_ID_CHARS || seen.has(model)) continue;
+		seen.add(model);
+		out.push(model);
+		if (out.length >= TARGET_MODEL_CACHE_MAX_MODELS) break;
+	}
+	return out;
+}
+
+function parseSnapshot(value: unknown): TargetModelSnapshot | null {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+	const row = value as Partial<TargetModelSnapshot>;
+	if (row.version !== TARGET_MODEL_CACHE_VERSION) return null;
+	if (typeof row.targetId !== "string" || row.targetId.length === 0) return null;
+	if (typeof row.runtimeId !== "string" || row.runtimeId.length === 0) return null;
+	if (row.url !== null && typeof row.url !== "string") return null;
+	if (!Array.isArray(row.models) || row.models.some((model) => typeof model !== "string")) return null;
+	if (typeof row.observedAt !== "string" || !Number.isFinite(Date.parse(row.observedAt))) return null;
+	const models = normalizedModels(row.models);
+	if (models.length !== row.models.length) return null;
+	return {
+		version: TARGET_MODEL_CACHE_VERSION,
+		targetId: row.targetId,
+		runtimeId: row.runtimeId,
+		url: row.url,
+		models,
+		observedAt: row.observedAt,
+	};
+}
+
+/** Read a fresh snapshot only when it still describes this target identity. */
+export function readTargetModelSnapshot(
+	target: Pick<TargetDescriptor, "id" | "runtime" | "url">,
+	options: TargetModelCacheOptions = {},
+): TargetModelSnapshot | null {
+	const path = targetModelSnapshotPath(target.id, options.cacheDir);
+	if (!existsSync(path)) return null;
+	try {
+		const snapshot = parseSnapshot(JSON.parse(readFileSync(path, "utf8")) as unknown);
+		if (snapshot === null) return null;
+		if (snapshot.targetId !== target.id || snapshot.runtimeId !== target.runtime) return null;
+		if (snapshot.url !== (target.url ?? null)) return null;
+		const observedMs = Date.parse(snapshot.observedAt);
+		const nowMs = options.nowMs ?? Date.now();
+		const ttlMs = options.ttlMs ?? TARGET_MODEL_CACHE_TTL_MS;
+		if (observedMs > nowMs || nowMs - observedMs >= ttlMs) return null;
+		return snapshot;
+	} catch {
+		return null;
+	}
+}
+
+/** Best-effort atomic replacement of one target's disposable probe snapshot. */
+export function recordTargetModelSnapshot(
+	target: Pick<TargetDescriptor, "id" | "runtime" | "url">,
+	models: ReadonlyArray<string>,
+	options: Pick<TargetModelCacheOptions, "cacheDir" | "nowMs"> = {},
+): boolean {
+	if (target.id.length === 0 || target.runtime.length === 0) return false;
+	const snapshot: TargetModelSnapshot = {
+		version: TARGET_MODEL_CACHE_VERSION,
+		targetId: target.id,
+		runtimeId: target.runtime,
+		url: target.url ?? null,
+		models: normalizedModels(models),
+		observedAt: new Date(options.nowMs ?? Date.now()).toISOString(),
+	};
+	try {
+		safeResourceWrite(targetModelSnapshotPath(target.id, options.cacheDir), `${JSON.stringify(snapshot, null, 2)}\n`, {
+			encoding: "utf8",
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}