@iowarp/clio-coder 0.4.1 → 0.4.3

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

@@ -4,11 +4,11 @@
  * 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
+ * First, capability discovery. A gateway may publish aliases or truthful
+ * physical names such as `dynamo/qwen3.8-27b`. 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 behind it 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
@@ -26,7 +26,8 @@
  * 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.
+ * holds across every measured upstream, and a gateway must publish that fact
+ * explicitly per route in `model_info` before Clio relies on it.
  */
 
 import { CLIO_MIN_CONTEXT_WINDOW, CLIO_MIN_MAX_OUTPUT_TOKENS } from "../../../../core/context-floor.js";
@@ -55,7 +56,7 @@ const defaultCapabilities: CapabilityFlags = {
 	embeddings: false,
 	rerank: false,
 	fim: false,
-	structuredOutputs: "json-schema",
+	structuredOutputs: "none",
 	contextWindow: CLIO_MIN_CONTEXT_WINDOW,
 	maxTokens: CLIO_MIN_MAX_OUTPUT_TOKENS,
 };
@@ -106,8 +107,11 @@ function boolean(value: unknown): boolean | undefined {
  * 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> {
+export function capabilitiesFromLiteLLMModelInfo(info: Record<string, unknown>): Partial<CapabilityFlags> {
 	const caps: Partial<CapabilityFlags> = {};
+	// This is a deployment declaration, never inferred from a URL, port or alias.
+	if (info.runtime === "lm-studio") caps.thinkingControlRuntime = "lmstudio";
+	else if (info.runtime === "llama.cpp") caps.thinkingControlRuntime = "llamacpp";
 	const contextWindow = positiveInteger(info.max_input_tokens) ?? positiveInteger(info.max_tokens);
 	if (contextWindow !== undefined) caps.contextWindow = contextWindow;
 	const maxTokens = positiveInteger(info.max_output_tokens);
@@ -132,20 +136,77 @@ function capabilitiesFromLiteLLMModelInfo(info: Record<string, unknown>): Partia
 		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";
+	// Measured, not inferred: see the module header. An explicit false must
+	// override this runtime's measured default for an upstream that cannot
+	// preserve the schema contract.
+	const responseSchema = boolean(info.supports_response_schema);
+	if (responseSchema !== undefined) caps.structuredOutputs = responseSchema ? "json-schema" : "none";
 	return caps;
 }
 
+const BOOLEAN_CAPABILITIES = [
+	"chat",
+	"tools",
+	"reasoning",
+	"vision",
+	"audio",
+	"embeddings",
+	"rerank",
+	"fim",
+] as const satisfies ReadonlyArray<keyof CapabilityFlags>;
+
+/**
+ * One alias may load-balance across heterogeneous deployments. Clio can only
+ * promise what every possible route supports: numerical limits take the
+ * smallest fully-published value, booleans require unanimous publication, and
+ * one explicit false defeats a true. Missing data never becomes a capability.
+ */
+export function aggregateLiteLLMCapabilities(rows: ReadonlyArray<Partial<CapabilityFlags>>): Partial<CapabilityFlags> {
+	if (rows.length === 0) return {};
+	const aggregate: Partial<CapabilityFlags> = {};
+	for (const key of ["contextWindow", "maxTokens"] as const) {
+		const values = rows.map((row) => row[key]);
+		if (values.every((value): value is number => typeof value === "number")) {
+			aggregate[key] = Math.min(...values);
+		}
+	}
+	for (const key of BOOLEAN_CAPABILITIES) {
+		const values = rows.map((row) => row[key]);
+		if (values.some((value) => value === false)) aggregate[key] = false;
+		else if (values.every((value) => value === true)) aggregate[key] = true;
+	}
+	const controlRuntime = rows[0]?.thinkingControlRuntime;
+	if (controlRuntime !== undefined && rows.every((row) => row.thinkingControlRuntime === controlRuntime)) {
+		aggregate.thinkingControlRuntime = controlRuntime;
+	}
+	const structuredOutputs = rows.map((row) => row.structuredOutputs);
+	if (structuredOutputs.some((value) => value === "none")) aggregate.structuredOutputs = "none";
+	else if (structuredOutputs.every((value) => value === "json-schema")) aggregate.structuredOutputs = "json-schema";
+	return aggregate;
+}
+
 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 }>;
+	deployments: Record<string, Array<{ model: string; apiBase?: string }>>;
+	/** Whether the empty catalog is specifically because the gateway rejected the key. */
+	authFailed: boolean;
 }
 
-const EMPTY_CATALOG: LiteLLMCatalog = { models: [], modelCapabilities: {}, modelStates: {}, deployments: {} };
+const EMPTY_CATALOG: LiteLLMCatalog = {
+	models: [],
+	modelCapabilities: {},
+	modelStates: {},
+	deployments: {},
+	authFailed: false,
+};
+
+/** Whether a failed probe leg failed specifically on the credential, not on reachability. */
+function isAuthError(leg: { ok: boolean; error?: string }): boolean {
+	return !leg.ok && /^HTTP 40[13]\b/u.test(leg.error ?? "");
+}
 
 /**
  * Read the catalog from `/v1/model/info`, falling back to `/v1/models`.
@@ -163,37 +224,50 @@ async function fetchCatalog(base: string, ctx: ProbeContext, headers: Record<str
 		: probeJson<LiteLLMModelInfoResponse>(detailOpts));
 
 	if (detail.ok && Array.isArray(detail.data?.data)) {
-		const catalog: LiteLLMCatalog = { models: [], modelCapabilities: {}, modelStates: {}, deployments: {} };
+		const catalog: LiteLLMCatalog = {
+			models: [],
+			modelCapabilities: {},
+			modelStates: {},
+			deployments: {},
+			authFailed: false,
+		};
+		const capabilityRows: Record<string, Array<Partial<CapabilityFlags>>> = {};
 		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);
+			if (catalog.deployments[alias] === undefined) {
+				catalog.models.push(alias);
+				catalog.deployments[alias] = [];
+				capabilityRows[alias] = [];
+			}
 			const caps = row.model_info ? capabilitiesFromLiteLLMModelInfo(row.model_info) : {};
-			if (Object.keys(caps).length > 0) catalog.modelCapabilities[alias] = caps;
+			capabilityRows[alias]?.push(caps);
 			const upstream = row.litellm_params?.model;
 			const apiBase = row.litellm_params?.api_base;
-			catalog.deployments[alias] = {
+			catalog.deployments[alias]?.push({
 				model: typeof upstream === "string" ? upstream : alias,
 				...(typeof apiBase === "string" ? { apiBase } : {}),
-			};
+			});
+		}
+		for (const alias of catalog.models) {
+			const caps = aggregateLiteLLMCapabilities(capabilityRows[alias] ?? []);
+			if (Object.keys(caps).length > 0) catalog.modelCapabilities[alias] = caps;
 		}
 		if (catalog.models.length > 0) return catalog;
 	}
+	const detailAuthFailed = isAuthError(detail);
 
 	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;
+	if (!list.ok || !Array.isArray(list.data?.data)) {
+		return { ...EMPTY_CATALOG, authFailed: detailAuthFailed || isAuthError(list) };
+	}
 	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: {} };
+	return { models, modelCapabilities: {}, modelStates: {}, deployments: {}, authFailed: false };
 }
 
 const litellmRuntime: RuntimeDescriptor = {
@@ -226,8 +300,11 @@ const litellmRuntime: RuntimeDescriptor = {
 		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",
+				error: catalog.authFailed
+					? "gateway rejected the key"
+					: "gateway is live but served no model catalog; check the target's API key",
 			};
+			if (catalog.authFailed) result.authFailed = true;
 			if (live.latencyMs !== undefined) result.latencyMs = live.latencyMs;
 			return result;
 		}
@@ -248,10 +325,23 @@ const litellmRuntime: RuntimeDescriptor = {
 		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}`)
+		// A node/model catalog already names placement. Summarize those one-to-one
+		// routes instead of flooding target diagnostics with dozens of tautologies;
+		// retain the explicit mapping for genuine aliases and multi-deployments.
+		const routeEntries = Object.entries(catalog.deployments);
+		const physical = routeEntries.filter(([alias, deployments]) => {
+			const slash = alias.indexOf("/");
+			if (slash <= 0 || deployments.length !== 1) return false;
+			const upstream = deployments[0]?.model.replace(/^openai\//u, "");
+			return upstream === alias.slice(slash + 1);
+		});
+		if (physical.length > 0) notes.push(`physical routes: ${physical.length} node/model names map one-to-one`);
+		const routed = routeEntries
+			.filter(([alias]) => !physical.some(([physicalAlias]) => physicalAlias === alias))
+			.map(([alias, deployments]) => {
+				const models = [...new Set(deployments.map((deployment) => deployment.model))];
+				return `${alias}=${models.join("|")}`;
+			})
 			.sort();
 		if (routed.length > 0) notes.push(`routes: ${routed.join(", ")}`);
 		if (notes.length > 0) result.notes = notes;

package/src/domains/providers/support.ts

@@ -5,7 +5,7 @@ import { getRuntimeRegistry } from "./registry.js";
 import type { RuntimeDescriptor } from "./types/runtime-descriptor.js";
 import type { TargetDescriptor } from "./types/target-descriptor.js";
 
-export type ProviderSupportGroup = "featured" | "cloud-api" | "subscription" | "local-http";
+export type ProviderSupportGroup = "featured" | "external-worker" | "cloud-api" | "subscription" | "local-http";
 
 /**
  * Where a runtime's model ids come from, which decides whether their order
@@ -44,6 +44,7 @@ const SUMMARY_BY_RUNTIME_ID: Readonly<Record<string, string>> = {
 	alcf: "ALCF inference gateway (Sophia/Metis) via Globus",
 	anthropic: "Anthropic API",
 	"anthropic-max": "Claude Pro/Max subscription via Anthropic OAuth",
+	"antigravity-code": "Experimental local delegation via the installed Antigravity CLI",
 	bedrock: "Amazon Bedrock",
 	"claude-code": "Claude Code subscription via installed claude CLI",
 	"claude-sdk": "Claude Code subscription via Claude Agent SDK",
@@ -59,19 +60,21 @@ 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",
+	litellm: "LiteLLM gateway with per-route capability discovery and physical-model attribution",
 };
 
 function groupPriority(group: ProviderSupportGroup): number {
 	switch (group) {
 		case "featured":
 			return 0;
-		case "subscription":
+		case "external-worker":
 			return 1;
-		case "cloud-api":
+		case "subscription":
 			return 2;
-		case "local-http":
+		case "cloud-api":
 			return 3;
+		case "local-http":
+			return 4;
 	}
 }
 
@@ -79,6 +82,8 @@ export function supportGroupLabel(group: ProviderSupportGroup): string {
 	switch (group) {
 		case "featured":
 			return "Featured";
+		case "external-worker":
+			return "External delegation";
 		case "subscription":
 			return "Subscriptions";
 		case "cloud-api":
@@ -90,6 +95,7 @@ export function supportGroupLabel(group: ProviderSupportGroup): string {
 
 function classifyGroup(runtime: RuntimeDescriptor): ProviderSupportGroup {
 	if (runtime.id === "openai-codex") return "featured";
+	if (runtime.externalAgentLoop !== undefined) return "external-worker";
 	if (runtime.id === "alcf") return "cloud-api";
 	if (runtime.auth === "oauth" || runtime.auth === "claude-cli") return "subscription";
 	if (catalogProviderForRuntime(runtime.id) || (runtime.auth === "api-key" && !runtime.probe)) {

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

@@ -25,6 +25,7 @@ export interface TargetModelSnapshot {
 	runtimeId: string;
 	url: string | null;
 	models: string[];
+	modelLabels?: Record<string, string>;
 	observedAt: string;
 }
 
@@ -32,6 +33,7 @@ interface TargetModelCacheOptions {
 	cacheDir?: string;
 	nowMs?: number;
 	ttlMs?: number;
+	modelLabels?: Readonly<Record<string, string>>;
 }
 
 function targetCacheKey(targetId: string): string {
@@ -55,6 +57,22 @@ function normalizedModels(models: ReadonlyArray<string>): string[] {
 	return out;
 }
 
+function normalizedLabels(models: ReadonlyArray<string>, labels: unknown): Record<string, string> | undefined {
+	if (typeof labels !== "object" || labels === null || Array.isArray(labels)) return undefined;
+	const source = labels as Record<string, unknown>;
+	const out: Record<string, string> = {};
+	for (const id of models) {
+		const label = source[id];
+		if (typeof label !== "string") continue;
+		const trimmed = label.trim();
+		if (trimmed.length === 0 || trimmed.length > TARGET_MODEL_CACHE_MAX_MODEL_ID_CHARS || /[\r\n\0]/u.test(trimmed)) {
+			continue;
+		}
+		out[id] = trimmed;
+	}
+	return Object.keys(out).length > 0 ? out : undefined;
+}
+
 function parseSnapshot(value: unknown): TargetModelSnapshot | null {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
 	const row = value as Partial<TargetModelSnapshot>;
@@ -66,7 +84,7 @@ function parseSnapshot(value: unknown): TargetModelSnapshot | 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 {
+	const snapshot: TargetModelSnapshot = {
 		version: TARGET_MODEL_CACHE_VERSION,
 		targetId: row.targetId,
 		runtimeId: row.runtimeId,
@@ -74,6 +92,9 @@ function parseSnapshot(value: unknown): TargetModelSnapshot | null {
 		models,
 		observedAt: row.observedAt,
 	};
+	const modelLabels = normalizedLabels(models, row.modelLabels);
+	if (modelLabels !== undefined) snapshot.modelLabels = modelLabels;
+	return snapshot;
 }
 
 /** Read a fresh snapshot only when it still describes this target identity. */
@@ -102,7 +123,7 @@ export function readTargetModelSnapshot(
 export function recordTargetModelSnapshot(
 	target: Pick<TargetDescriptor, "id" | "runtime" | "url">,
 	models: ReadonlyArray<string>,
-	options: Pick<TargetModelCacheOptions, "cacheDir" | "nowMs"> = {},
+	options: Pick<TargetModelCacheOptions, "cacheDir" | "nowMs" | "modelLabels"> = {},
 ): boolean {
 	if (target.id.length === 0 || target.runtime.length === 0) return false;
 	const snapshot: TargetModelSnapshot = {
@@ -113,6 +134,8 @@ export function recordTargetModelSnapshot(
 		models: normalizedModels(models),
 		observedAt: new Date(options.nowMs ?? Date.now()).toISOString(),
 	};
+	const modelLabels = normalizedLabels(snapshot.models, options.modelLabels);
+	if (modelLabels !== undefined) snapshot.modelLabels = modelLabels;
 	try {
 		safeResourceWrite(targetModelSnapshotPath(target.id, options.cacheDir), `${JSON.stringify(snapshot, null, 2)}\n`, {
 			encoding: "utf8",

package/src/domains/providers/types/capability-flags.ts

@@ -20,6 +20,8 @@ export interface CapabilityFlags {
 	toolCallFormat?: ToolCallFormat;
 	reasoning: boolean;
 	thinkingFormat?: ThinkingFormat;
+	/** Probe-declared upstream control dialect only; never changes gateway routing or residency. */
+	thinkingControlRuntime?: "lmstudio" | "llamacpp";
 	structuredOutputs?: StructuredOutputMode;
 	vision: boolean;
 	audio: boolean;

package/src/domains/providers/types/cost-provenance.ts

@@ -5,3 +5,22 @@ export type CostProvenance = "known" | "known_free" | "estimated" | "unknown";
 export function normalizeCostProvenance(value: CostProvenance | undefined): CostProvenance {
 	return value ?? "unknown";
 }
+
+const COST_PROVENANCE_VALUES: ReadonlySet<string> = new Set<CostProvenance>([
+	"known",
+	"known_free",
+	"estimated",
+	"unknown",
+]);
+
+/**
+ * Validate an unvalidated wire value (a dispatch bus payload crossing a
+ * worker process boundary, never runtime-checked against this closed set
+ * before) against the four real provenance values. An unrecognized value
+ * keeps `fallback` rather than being accepted as-is, matching how the
+ * observability projection's run summary already treated this field; the
+ * interactive dispatch board previously accepted any truthy string here.
+ */
+export function resolveCostProvenance(value: unknown, fallback: CostProvenance): CostProvenance {
+	return typeof value === "string" && COST_PROVENANCE_VALUES.has(value) ? (value as CostProvenance) : fallback;
+}

package/src/domains/providers/types/local-model-quirks.ts

@@ -2,7 +2,7 @@
  * Engine-visible quirks extracted from a knowledge-base entry. The catalog YAML
  * keeps free-form `quirks` (gpu tiers, runtime preferences, serving notes), so
  * `KnowledgeBaseEntry.quirks` stays `Record<string, unknown>`. This module
- * narrows the slice the engine consumes (KV cache layout, per-mode sampling)
+ * narrows the slice the engine consumes (per-mode sampling and thinking)
  * into a typed shape that flows through `model.clioCoder.quirks` at synth time.
  *
  * Field naming follows the Hugging Face / model-card terminology so the YAML
@@ -13,19 +13,7 @@
  */
 
 import type { ThinkingBudgetByLevel, ThinkingEffortByLevel } from "../thinking-control-policy.js";
-
-export const KV_CACHE_QUANTS = ["f32", "f16", "q8_0", "q4_0", "q4_1", "iq4_nl", "q5_0", "q5_1"] as const;
-
-export type KvCacheQuant = (typeof KV_CACHE_QUANTS)[number];
-
-export interface KvCacheQuirks {
-	/** Quantization type for the key cache. `false` disables quantization (full precision). */
-	kQuant?: KvCacheQuant | false;
-	/** Quantization type for the value cache. Requires flash attention to take effect. */
-	vQuant?: KvCacheQuant | false;
-	/** Force fp16 KV cache regardless of K/V quant settings. */
-	useFp16?: boolean;
-}
+import { type ThinkingLevel, VALID_THINKING_LEVELS } from "./capability-flags.js";
 
 export interface SamplingProfile {
 	temperature?: number;
@@ -36,7 +24,6 @@ export interface SamplingProfile {
 	repeatPenalty?: number;
 	presencePenalty?: number;
 	frequencyPenalty?: number;
-	maxTokens?: number;
 }
 
 export interface SamplingQuirks {
@@ -59,6 +46,20 @@ export interface SamplingQuirks {
  */
 export type ThinkingMechanism = "effort-levels" | "budget-tokens" | "on-off" | "always-on" | "none";
 
+export type ChatTemplateKwargValue = string | number | boolean;
+
+export interface ChatTemplateKwargsByLevel {
+	key: string;
+	values: Partial<Record<ThinkingLevel, string | number>>;
+	lmstudio?: "unsupported" | string;
+}
+
+export interface ChatTemplateKwargsQuirks {
+	static?: Record<string, ChatTemplateKwargValue>;
+	byLevel?: ChatTemplateKwargsByLevel;
+	lmstudio?: "unsupported" | string | Record<string, string>;
+}
+
 export interface ThinkingQuirks {
 	mechanism: ThinkingMechanism;
 	/** Token budget for budget-tokens mechanism, keyed by Clio's thinking level. */
@@ -67,24 +68,19 @@ export interface ThinkingQuirks {
 	effortByLevel?: ThinkingEffortByLevel;
 	/** 2-5 line free-text guidance rendered into the Runtime prompt block. */
 	guidance?: string;
+	chatTemplateKwargs?: ChatTemplateKwargsQuirks;
 }
 
 export interface LocalModelQuirks {
-	kvCache?: KvCacheQuirks;
 	sampling?: SamplingQuirks;
 	thinking?: ThinkingQuirks;
+	chatTemplateKwargs?: ChatTemplateKwargsQuirks;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-function asKvCacheQuant(value: unknown): KvCacheQuant | false | undefined {
-	if (value === false) return false;
-	if (typeof value !== "string") return undefined;
-	return (KV_CACHE_QUANTS as ReadonlyArray<string>).includes(value) ? (value as KvCacheQuant) : undefined;
-}
-
 function asPositive(value: unknown): number | undefined {
 	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
 }
@@ -98,17 +94,6 @@ function asPenalty(value: unknown): number | undefined {
 	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
 
-function extractKvCache(raw: unknown): KvCacheQuirks | undefined {
-	if (!isRecord(raw)) return undefined;
-	const out: KvCacheQuirks = {};
-	const k = asKvCacheQuant(raw.kQuant);
-	if (k !== undefined) out.kQuant = k;
-	const v = asKvCacheQuant(raw.vQuant);
-	if (v !== undefined) out.vQuant = v;
-	if (typeof raw.useFp16 === "boolean") out.useFp16 = raw.useFp16;
-	return Object.keys(out).length > 0 ? out : undefined;
-}
-
 function extractSamplingProfile(raw: unknown): SamplingProfile | undefined {
 	if (!isRecord(raw)) return undefined;
 	const out: SamplingProfile = {};
@@ -129,8 +114,6 @@ function extractSamplingProfile(raw: unknown): SamplingProfile | undefined {
 	if (pp !== undefined) out.presencePenalty = pp;
 	const fp = asPenalty(raw.frequencyPenalty);
 	if (fp !== undefined) out.frequencyPenalty = fp;
-	const maxTokens = asInteger(raw.maxTokens);
-	if (maxTokens !== undefined) out.maxTokens = maxTokens;
 	return Object.keys(out).length > 0 ? out : undefined;
 }
 
@@ -185,6 +168,66 @@ function extractEffortByLevel(raw: unknown): ThinkingQuirks["effortByLevel"] | u
 	return Object.keys(out).length > 0 ? out : undefined;
 }
 
+function extractChatTemplateKwargs(raw: unknown): ChatTemplateKwargsQuirks | undefined {
+	if (!isRecord(raw)) return undefined;
+	const out: ChatTemplateKwargsQuirks = {};
+
+	if (isRecord(raw.static)) {
+		const staticMap: Record<string, ChatTemplateKwargValue> = {};
+		for (const [k, v] of Object.entries(raw.static)) {
+			if (typeof v === "boolean") {
+				staticMap[k] = v;
+			} else if (typeof v === "number" && Number.isFinite(v)) {
+				staticMap[k] = v;
+			} else if (typeof v === "string" && v.length > 0) {
+				staticMap[k] = v;
+			}
+		}
+		if (Object.keys(staticMap).length > 0) out.static = staticMap;
+	}
+
+	if (isRecord(raw.byLevel)) {
+		const byLevelRaw = raw.byLevel;
+		if (typeof byLevelRaw.key === "string" && byLevelRaw.key.trim().length > 0 && isRecord(byLevelRaw.values)) {
+			const values: Partial<Record<ThinkingLevel, string | number>> = {};
+			for (const level of VALID_THINKING_LEVELS) {
+				const val = byLevelRaw.values[level];
+				if (typeof val === "string" && val.length > 0) {
+					values[level] = val;
+				} else if (typeof val === "number" && Number.isFinite(val)) {
+					values[level] = val;
+				}
+			}
+			if (Object.keys(values).length > 0) {
+				const byLevel: ChatTemplateKwargsByLevel = {
+					key: byLevelRaw.key.trim(),
+					values,
+				};
+				if (typeof byLevelRaw.lmstudio === "string" && byLevelRaw.lmstudio.trim().length > 0) {
+					byLevel.lmstudio = byLevelRaw.lmstudio.trim();
+				}
+				out.byLevel = byLevel;
+			}
+		}
+	}
+
+	if (typeof raw.lmstudio === "string" && raw.lmstudio.trim().length > 0) {
+		out.lmstudio = raw.lmstudio.trim();
+	} else if (isRecord(raw.lmstudio)) {
+		const lmstudioMap: Record<string, string> = {};
+		for (const [k, v] of Object.entries(raw.lmstudio)) {
+			if (typeof v === "string" && v.trim().length > 0) {
+				lmstudioMap[k] = v.trim();
+			}
+		}
+		if (Object.keys(lmstudioMap).length > 0) {
+			out.lmstudio = lmstudioMap;
+		}
+	}
+
+	return Object.keys(out).length > 0 ? out : undefined;
+}
+
 function extractThinkingQuirks(raw: unknown): ThinkingQuirks | undefined {
 	if (!isRecord(raw)) return undefined;
 	const mechanism = asThinkingMechanism(raw.mechanism);
@@ -195,6 +238,8 @@ function extractThinkingQuirks(raw: unknown): ThinkingQuirks | undefined {
 	const effortByLevel = extractEffortByLevel(raw.effortByLevel);
 	if (effortByLevel) out.effortByLevel = effortByLevel;
 	if (typeof raw.guidance === "string" && raw.guidance.length > 0) out.guidance = raw.guidance;
+	const chatTemplateKwargs = extractChatTemplateKwargs(raw.chatTemplateKwargs);
+	if (chatTemplateKwargs) out.chatTemplateKwargs = chatTemplateKwargs;
 	return out;
 }
 
@@ -206,11 +251,14 @@ function extractThinkingQuirks(raw: unknown): ThinkingQuirks | undefined {
 export function extractLocalModelQuirks(raw: unknown): LocalModelQuirks | undefined {
 	if (!isRecord(raw)) return undefined;
 	const out: LocalModelQuirks = {};
-	const kvCache = extractKvCache(raw.kvCache);
-	if (kvCache) out.kvCache = kvCache;
 	const sampling = extractSampling(raw.sampling);
 	if (sampling) out.sampling = sampling;
 	const thinking = extractThinkingQuirks(raw.thinking);
 	if (thinking) out.thinking = thinking;
+	const chatTemplateKwargs =
+		extractChatTemplateKwargs(raw.chatTemplateKwargs) ??
+		extractChatTemplateKwargs(isRecord(raw.thinking) ? raw.thinking.chatTemplateKwargs : undefined) ??
+		extractChatTemplateKwargs(isRecord(raw.request) ? raw.request.chatTemplateKwargs : undefined);
+	if (chatTemplateKwargs) out.chatTemplateKwargs = chatTemplateKwargs;
 	return Object.keys(out).length > 0 ? out : undefined;
 }

package/src/domains/providers/types/runtime-descriptor.ts

@@ -22,7 +22,8 @@ export type RuntimeApiFamily =
 	| "rerank-http"
 	| "embeddings-http"
 	| "claude-agent-sdk"
-	| "claude-code-subprocess";
+	| "claude-code-subprocess"
+	| "external-agent-subprocess";
 
 export type RuntimeAuth = "api-key" | "oauth" | "aws-sdk" | "vertex-adc" | "claude-cli" | "none";
 
@@ -93,8 +94,14 @@ export interface ProbeResult {
 	ok: boolean;
 	latencyMs?: number;
 	error?: string;
+	/** Set when `error` is specifically the server rejecting the credential, not a reachability failure. */
+	authFailed?: boolean;
 	serverVersion?: string;
 	models?: string[];
+	/** Human-readable labels keyed by the exact wire id returned in `models`. */
+	modelLabels?: Record<string, string>;
+	/** Stable cause class for setup UX; `error` remains the redacted human diagnostic. */
+	failureKind?: "missing" | "authentication" | "unsupported-feature" | "catalog-unavailable" | "cancelled" | "generic";
 	/** Probe-only per-model load state when the runtime exposes it. */
 	modelStates?: Record<string, ProbeModelStatus>;
 	discoveredCapabilities?: Partial<CapabilityFlags>;
@@ -155,6 +162,18 @@ export interface RuntimeDescriptor {
 	headlessCommand?: string;
 	outputParser?: string;
 	defaultCapabilities: CapabilityFlags;
+	/**
+	 * Declares a black-box agent loop owned by an external executable. `tools`
+	 * in CapabilityFlags stays false because Clio neither sends nor observes
+	 * typed calls on this path; this field records the distinct external fact.
+	 */
+	externalAgentLoop?: {
+		tools: "externally-governed-unobserved";
+		network: "externally-governed-unobserved";
+		budget: "external-one-shot";
+		generatingRetry: "forbidden";
+		modelCatalog: "live-authoritative" | "static";
+	};
 	/**
 	 * When true, this id is a real, distinct runtime (e.g. `llamacpp-anthropic`,
 	 * the Anthropic Messages surface on llama.cpp, or the embed/rerank runtimes)