@iowarp/clio-coder 0.4.0 → 0.4.2

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/runtime-resolution.ts

@@ -273,6 +273,34 @@ function appendThinkingDiagnostics(
 	diagnostics.push(diagnostic(severity, `thinking-${thinking.noticeKind}`, thinking.notice));
 }
 
+const CHAT_TEMPLATE_KWARGS_UNDELIVERABLE = "chat-template-kwargs-undeliverable";
+
+/**
+ * One warning when the family declares chat-template kwargs the runtime
+ * cannot carry (#268). LM Studio ignores `chat_template_kwargs` for every
+ * family measured, so a Nemotron 3.5 target on that runtime runs without the
+ * `force_nonempty_content` its card asks for; the operator sees that once per
+ * target and model rather than finding the key silently missing from the wire.
+ */
+function appendChatTemplateKwargsDiagnostics(
+	diagnostics: RuntimeResolutionDiagnostic[],
+	resolved: ResolvedModelRuntimeCapabilities,
+): void {
+	const undeliverable = resolved.request.undeliverableChatTemplateKwargs;
+	if (!undeliverable || undeliverable.keys.length === 0) return;
+	const keys = undeliverable.keys.join(", ");
+	const declared = undeliverable.declaredUnsupported
+		? "its family entry marks them unsupported there"
+		: "its family entry does not say so";
+	diagnostics.push(
+		diagnostic(
+			"warning",
+			CHAT_TEMPLATE_KWARGS_UNDELIVERABLE,
+			`chat-template kwargs ${keys} cannot reach ${resolved.runtimeId}, which ignores chat_template_kwargs; ${resolved.modelId} runs without them and ${declared}`,
+		),
+	);
+}
+
 function nonNegativeFiniteNumber(value: unknown): number | undefined {
 	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
 }
@@ -447,6 +475,7 @@ export function resolveRuntimeTarget(
 	const decisions = capabilityDecisions(runtime, capabilities);
 	appendCapabilityDiagnostics(diagnostics, input, capabilities, decisions, targetId);
 	appendThinkingDiagnostics(diagnostics, modelRuntime, requestedThinkingLevel);
+	appendChatTemplateKwargsDiagnostics(diagnostics, modelRuntime);
 
 	if (hasError(diagnostics)) return { ok: false, diagnostics };
 
@@ -493,6 +522,7 @@ function withoutStaleRuntimeDiagnostics(
 ): RuntimeResolutionDiagnostic[] {
 	return diagnostics.filter((entry) => {
 		if (entry.code.startsWith("thinking-")) return false;
+		if (entry.code === CHAT_TEMPLATE_KWARGS_UNDELIVERABLE) return false;
 		if (entry.code === "output-budget-unknown" && decisions.maxTokens > 0) return false;
 		if (entry.code === "tools-unsupported" && decisions.tools) return false;
 		return true;
@@ -545,6 +575,7 @@ export function refineRuntimeTargetWithModelHints(
 	const decisions = capabilityDecisions(target.runtime, capabilities);
 	const diagnostics = withoutStaleRuntimeDiagnostics(target.diagnostics, decisions);
 	appendThinkingDiagnostics(diagnostics, modelRuntime, target.requestedThinkingLevel);
+	appendChatTemplateKwargsDiagnostics(diagnostics, modelRuntime);
 	return {
 		...target,
 		capabilities,

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);
@@ -374,6 +374,8 @@ export interface LlamaCppStatusEnrichment {
 	modelId?: string;
 	serverFlags?: LlamaCppServerFlags;
 	notes?: string[];
+	/** The router's own load state for the selected model, when it reports one. */
+	loadState?: ProbeModelStatus["state"];
 }
 
 function argsFromStatus(status: unknown): string[] {
@@ -423,7 +425,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;
@@ -490,8 +492,11 @@ export async function probeLlamaCppModelStatus(
 	const entries = await probeOpenAIModelEntries(base, ctx);
 	const selected = selectedModelEntry(entries, target);
 	if (!selected) return {};
+	const loadState = modelStateFromOpenAIModelEntry({ id: selected.id, status: selected.status })?.state;
+	const withState = (enrichment: LlamaCppStatusEnrichment): LlamaCppStatusEnrichment =>
+		loadState === undefined ? enrichment : { ...enrichment, loadState };
 	const args = argsFromStatus(selected.status);
-	if (args.length === 0) return { notes: statusNotes(selected.id, selected.status) };
+	if (args.length === 0) return withState({ notes: statusNotes(selected.id, selected.status) });
 	const flags = parseLlamaCppServerFlags(args);
 	const caps: Partial<CapabilityFlags> = {};
 	const window = llamaCppRequestContextWindow(flags);
@@ -512,7 +517,7 @@ export async function probeLlamaCppModelStatus(
 		);
 	}
 	if (notes.length > 0) enrichment.notes = notes;
-	return enrichment;
+	return withState(enrichment);
 }
 
 /**

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/llamacpp.ts

@@ -56,7 +56,15 @@ const llamacppRuntime: RuntimeDescriptor = {
 		const health = await (ctx.signal ? probeHttp({ ...healthOpts, signal: ctx.signal }) : probeHttp(healthOpts));
 		if (!health.ok) return health;
 		const status = await probeLlamaCppModelStatus(base, target, ctx);
-		const props = await probeLlamaCppProps(base, ctx, status.modelId ?? target.defaultModel);
+		// A router answers /props?model=<id> by loading that model, and with
+		// --models-max 1 that evicts whatever is resident: every probe of a
+		// fleet target's default model unloaded the chat model, so the next turn
+		// prefilled from zero (11,601 tokens, cache_n 0, on the round-3 resume
+		// run on mini). The router's model list already carries the worker's
+		// flags (--parallel, --ctx-size) for an unloaded model, so the worker is
+		// asked only when it is resident.
+		const resident = status.loadState === undefined || status.loadState === "loaded";
+		const props = await probeLlamaCppProps(base, ctx, resident ? (status.modelId ?? target.defaultModel) : undefined);
 		const catalog = await probeOpenAIModelCatalog(base, ctx);
 		const result: ProbeResult = { ok: true };
 		if (catalog.models.length > 0) result.models = catalog.models;

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

@@ -14,10 +14,6 @@
  * publishes the real numbers on `/v1/model/info` instead, which is what this
  * probe reads.
  *
- * Second, routed-deployment attribution. Which physical model answered is a
- * per-response fact behind an alias, and LiteLLM returns it in `x-litellm-*`
- * response headers. See {@link routedDeploymentFromHeaders}.
- *
  * 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
@@ -110,7 +106,7 @@ 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.
  */
-export function capabilitiesFromLiteLLMModelInfo(info: Record<string, unknown>): Partial<CapabilityFlags> {
+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;
@@ -200,92 +196,6 @@ async function fetchCatalog(base: string, ctx: ProbeContext, headers: Record<str
 	return { models, modelCapabilities: {}, modelStates: {}, deployments: {} };
 }
 
-/**
- * The routed deployment LiteLLM reports for one response.
- *
- * Behind an alias the physical model is a per-request fact: a fallback, a
- * context-window promotion, or an ordinary load-balancing choice all change it
- * without changing what the client asked for. Reporting the alias back as the
- * model is how a gateway hides an outage, and it is exactly what an operator
- * needs to see. LiteLLM answers in headers on every completion.
- */
-export interface RoutedDeployment {
-	/** The alias the client asked for, e.g. `code`. */
-	group?: string;
-	/** The physical model that answered, e.g. `openai/katcoder2.5-35b-moe`. */
-	model?: string;
-	/** The upstream that served it. */
-	apiBase?: string;
-	/** Stable id of the specific deployment inside the group. */
-	deploymentId?: string;
-	/** Non-zero when the request did not reach its first-choice deployment. */
-	attemptedFallbacks?: number;
-	attemptedRetries?: number;
-}
-
-function headerValue(headers: { get(name: string): string | null }, name: string): string | undefined {
-	const raw = headers.get(name)?.trim();
-	return raw && raw.length > 0 ? raw : undefined;
-}
-
-function headerInteger(headers: { get(name: string): string | null }, name: string): number | undefined {
-	const raw = headerValue(headers, name);
-	if (raw === undefined) return undefined;
-	const parsed = Number.parseInt(raw, 10);
-	return Number.isFinite(parsed) ? parsed : undefined;
-}
-
-/**
- * Extract the routed deployment from a LiteLLM response, or null when the
- * headers are absent. Absent is the normal answer for every non-LiteLLM target,
- * so callers treat null as "no attribution available" rather than an error.
- */
-export function routedDeploymentFromHeaders(headers: { get(name: string): string | null }): RoutedDeployment | null {
-	const routed: RoutedDeployment = {};
-	const group = headerValue(headers, "x-litellm-model-group");
-	if (group !== undefined) routed.group = group;
-	const model = headerValue(headers, "x-litellm-model-name");
-	if (model !== undefined) routed.model = model;
-	const apiBase = headerValue(headers, "x-litellm-model-api-base");
-	if (apiBase !== undefined) routed.apiBase = apiBase;
-	const deploymentId = headerValue(headers, "x-litellm-model-id");
-	if (deploymentId !== undefined) routed.deploymentId = deploymentId;
-	const fallbacks = headerInteger(headers, "x-litellm-attempted-fallbacks");
-	if (fallbacks !== undefined) routed.attemptedFallbacks = fallbacks;
-	const retries = headerInteger(headers, "x-litellm-attempted-retries");
-	if (retries !== undefined) routed.attemptedRetries = retries;
-	return Object.keys(routed).length > 0 ? routed : null;
-}
-
-/**
- * One-line attribution for a routed response.
- *
- * A request that fell back says so. `code -> openai/qwen3.8-27b-dense @
- * mini.tail78f300.ts.net:8080 (fallback)` is the whole point of the runtime:
- * the operator asked for the coder, the coder was asleep, and something else
- * answered.
- */
-export function formatRoutedDeployment(routed: RoutedDeployment): string {
-	const parts: string[] = [];
-	if (routed.group && routed.model && routed.group !== routed.model) {
-		parts.push(`${routed.group} -> ${routed.model}`);
-	} else if (routed.model ?? routed.group) {
-		parts.push((routed.model ?? routed.group) as string);
-	}
-	if (routed.apiBase) {
-		let host = routed.apiBase;
-		try {
-			host = new URL(routed.apiBase).host;
-		} catch {
-			// A non-URL api_base is displayed verbatim.
-		}
-		parts.push(`@ ${host}`);
-	}
-	if ((routed.attemptedFallbacks ?? 0) > 0) parts.push("(fallback)");
-	else if ((routed.attemptedRetries ?? 0) > 0) parts.push("(retried)");
-	return parts.join(" ");
-}
-
 const litellmRuntime: RuntimeDescriptor = {
 	id: "litellm",
 	displayName: "LiteLLM gateway",

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/knowledge-base.ts

@@ -2,6 +2,7 @@ import { readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
 
+import { warnLegacyNaming } from "../../../core/naming-compat.js";
 import type { CapabilityFlags } from "./capability-flags.js";
 
 export interface KnowledgeBaseEntry {
@@ -9,6 +10,8 @@ export interface KnowledgeBaseEntry {
 	matchPatterns: ReadonlyArray<string>;
 	capabilities: Partial<CapabilityFlags>;
 	quirks?: Record<string, unknown>;
+	/** Product-owned catalog metadata, normalized from either YAML spelling. */
+	clioCoder?: Record<string, unknown>;
 }
 
 export type MatchKind = "family" | "alias";
@@ -152,5 +155,15 @@ function normalizeEntry(raw: unknown, file: string): KnowledgeBaseEntry {
 		}
 		entry.quirks = candidate.quirks as Record<string, unknown>;
 	}
+	const canonicalMetadata = candidate["clio-coder"];
+	const legacyMetadata = candidate.clio;
+	if (legacyMetadata !== undefined) warnLegacyNaming("clio: model metadata", "clio-coder: model metadata");
+	const metadata = canonicalMetadata ?? legacyMetadata;
+	if (metadata !== undefined) {
+		if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
+			throw new Error(`knowledge base file ${file}: entry '${family}' clio-coder metadata must be an object`);
+		}
+		entry.clioCoder = metadata as Record<string, unknown>;
+	}
 	return entry;
 }

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

@@ -2,8 +2,8 @@
  * 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)
- * into a typed shape that flows through `model.clio.quirks` at synth time.
+ * 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
  * can be authored against the source-of-truth card. The OpenAI adapter
@@ -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,22 +238,27 @@ 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;
 }
 
 /**
  * Pull the engine-visible quirks slice out of a free-form catalog quirks
  * record. Returns `undefined` when nothing engine-relevant is configured so
- * `model.clio.quirks` only gets attached when it carries information.
+ * `model.clioCoder.quirks` only gets attached when it carries information.
  */
 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/target-descriptor.ts

@@ -14,9 +14,9 @@ export interface TargetPricing {
 	cacheWrite?: number;
 }
 
-// "clio-managed" is a settings.yaml enum value, not an artifact name; it stays
-// unrenamed by rebrand decision so existing `lifecycle:` lines keep working.
-export type TargetLifecycle = "user-managed" | "clio-managed";
+// Canonical persisted lifecycle name. Readers temporarily normalize the
+// released `clio-managed` spelling at the settings boundary.
+export type TargetLifecycle = "user-managed" | "clio-coder-managed";
 
 export interface LmStudioLoadSettings {
 	contextLength?: number;