@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/domains/providers/types/knowledge-base.ts

@@ -0,0 +1,156 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+
+import type { CapabilityFlags } from "./capability-flags.js";
+
+export interface KnowledgeBaseEntry {
+	family: string;
+	matchPatterns: ReadonlyArray<string>;
+	capabilities: Partial<CapabilityFlags>;
+	quirks?: Record<string, unknown>;
+}
+
+export type MatchKind = "family" | "alias";
+
+export interface KnowledgeBaseHit {
+	entry: KnowledgeBaseEntry;
+	matchKind: MatchKind;
+}
+
+export interface KnowledgeBase {
+	lookup(modelId: string): KnowledgeBaseHit | null;
+	entries(): ReadonlyArray<KnowledgeBaseEntry>;
+}
+
+export interface KnowledgeBaseRoot {
+	dir: string;
+	/** Human-readable label used in parse/validation diagnostics. */
+	label?: string;
+	/** Missing optional roots are ignored; non-optional roots must exist. */
+	optional?: boolean;
+}
+
+export class FileKnowledgeBase implements KnowledgeBase {
+	private readonly roots: KnowledgeBaseRoot[];
+	private loaded: KnowledgeBaseEntry[] = [];
+
+	constructor(root: string | ReadonlyArray<string | KnowledgeBaseRoot>) {
+		this.roots = normalizeRoots(root);
+		this.reload();
+	}
+
+	reload(): void {
+		const next: KnowledgeBaseEntry[] = [];
+		for (const root of this.roots) {
+			const files = collectYamlFiles(root.dir);
+			for (const file of files) {
+				const name = root.label ? `${root.label}:${file.name}` : file.name;
+				const raw = readFileSync(file.path, "utf8");
+				const parsed = parseYaml(raw);
+				if (!Array.isArray(parsed)) {
+					throw new Error(`knowledge base file ${name} must be a YAML list of KnowledgeBaseEntry`);
+				}
+				for (const item of parsed) {
+					next.push(normalizeEntry(item, name));
+				}
+			}
+		}
+		this.loaded = next;
+	}
+
+	entries(): ReadonlyArray<KnowledgeBaseEntry> {
+		return this.loaded;
+	}
+
+	lookup(modelId: string): KnowledgeBaseHit | null {
+		const needle = modelId.toLowerCase();
+		let best: { entry: KnowledgeBaseEntry; pattern: string } | null = null;
+		for (const entry of this.loaded) {
+			for (const pattern of entry.matchPatterns) {
+				if (!needle.includes(pattern.toLowerCase())) continue;
+				if (best === null || pattern.length >= best.pattern.length) {
+					best = { entry, pattern };
+				}
+			}
+		}
+		if (best === null) return null;
+		const isFamilyMatch = best.pattern.toLowerCase() === best.entry.family.toLowerCase();
+		return { entry: best.entry, matchKind: isFamilyMatch ? "family" : "alias" };
+	}
+}
+
+function normalizeRoots(root: string | ReadonlyArray<string | KnowledgeBaseRoot>): KnowledgeBaseRoot[] {
+	const rawRoots =
+		typeof root === "string"
+			? [{ dir: root }]
+			: root.map((entry) => (typeof entry === "string" ? { dir: entry } : entry));
+	const out: KnowledgeBaseRoot[] = [];
+	const seen = new Set<string>();
+	for (const raw of rawRoots) {
+		const dir = raw.dir.trim();
+		if (dir.length === 0 || seen.has(dir)) continue;
+		let isRootDir = false;
+		try {
+			isRootDir = statSync(dir).isDirectory();
+		} catch (err) {
+			if (raw.optional === true) continue;
+			throw err;
+		}
+		if (!isRootDir) {
+			if (raw.optional === true) continue;
+			throw new Error(`knowledge base path is not a directory: ${dir}`);
+		}
+		seen.add(dir);
+		out.push({ dir, ...(raw.label ? { label: raw.label } : {}), ...(raw.optional === true ? { optional: true } : {}) });
+	}
+	return out;
+}
+
+function collectYamlFiles(dir: string, prefix = ""): Array<{ path: string; name: string }> {
+	const out: Array<{ path: string; name: string }> = [];
+	const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+	for (const entry of entries) {
+		const path = join(dir, entry.name);
+		const name = prefix ? `${prefix}/${entry.name}` : entry.name;
+		if (entry.isDirectory()) {
+			out.push(...collectYamlFiles(path, name));
+			continue;
+		}
+		if (!entry.isFile()) continue;
+		if (!entry.name.endsWith(".yaml") && !entry.name.endsWith(".yml")) continue;
+		out.push({ path, name });
+	}
+	return out;
+}
+
+function normalizeEntry(raw: unknown, file: string): KnowledgeBaseEntry {
+	if (typeof raw !== "object" || raw === null) {
+		throw new Error(`knowledge base file ${file}: every entry must be an object`);
+	}
+	const candidate = raw as Record<string, unknown>;
+	const family = candidate.family;
+	const patterns = candidate.matchPatterns;
+	const capabilities = candidate.capabilities;
+	if (typeof family !== "string" || family.length === 0) {
+		throw new Error(`knowledge base file ${file}: entry is missing 'family' string`);
+	}
+	if (!Array.isArray(patterns) || patterns.some((p) => typeof p !== "string")) {
+		throw new Error(`knowledge base file ${file}: entry '${family}' needs matchPatterns: string[]`);
+	}
+	if (typeof capabilities !== "object" || capabilities === null || Array.isArray(capabilities)) {
+		throw new Error(`knowledge base file ${file}: entry '${family}' needs capabilities object`);
+	}
+	const entry: KnowledgeBaseEntry = {
+		family,
+		matchPatterns: patterns as string[],
+		capabilities: capabilities as Partial<CapabilityFlags>,
+	};
+	if (candidate.quirks !== undefined) {
+		if (typeof candidate.quirks !== "object" || candidate.quirks === null || Array.isArray(candidate.quirks)) {
+			throw new Error(`knowledge base file ${file}: entry '${family}' quirks must be an object`);
+		}
+		entry.quirks = candidate.quirks as Record<string, unknown>;
+	}
+	return entry;
+}

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

@@ -0,0 +1,216 @@
+/**
+ * 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.
+ *
+ * Field naming follows the Hugging Face / model-card terminology so the YAML
+ * can be authored against the source-of-truth card. The OpenAI adapter
+ * translates these into pi-ai sampling parameters at consumption:
+ *   - OpenAI-compatible surfaces accept `top_p`, `top_k`, `min_p`,
+ *     `repeat_penalty`.
+ */
+
+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;
+}
+
+export interface SamplingProfile {
+	temperature?: number;
+	topP?: number;
+	topK?: number;
+	minP?: number;
+	/** HF "repetition_penalty" / SDK "repeatPenalty". Catalog accepts either YAML key. */
+	repeatPenalty?: number;
+	presencePenalty?: number;
+	frequencyPenalty?: number;
+	maxTokens?: number;
+}
+
+export interface SamplingQuirks {
+	/** Sampler used when the agent is reasoning (thinking level != "off"). */
+	thinking?: SamplingProfile;
+	/** Sampler used when the agent is in plain instruct mode (thinking == "off"). */
+	instruct?: SamplingProfile;
+}
+
+/**
+ * How a local family exposes thinking control to the engine. Drives the
+ * payload mutations and TUI glyph rendering so a request never lies about
+ * what the model can actually do.
+ *
+ *   - `effort-levels`: vendor accepts a discrete reasoning_effort enum.
+ *   - `budget-tokens`: vendor honors a numeric thinking budget per request.
+ *   - `on-off`: chat template toggles thinking on or off; level is coerced.
+ *   - `always-on`: model emits chain-of-thought unconditionally.
+ *   - `none`: model has no thinking surface; level is ignored.
+ */
+export type ThinkingMechanism = "effort-levels" | "budget-tokens" | "on-off" | "always-on" | "none";
+
+export interface ThinkingQuirks {
+	mechanism: ThinkingMechanism;
+	/** Token budget for budget-tokens mechanism, keyed by Clio's thinking level. */
+	budgetByLevel?: ThinkingBudgetByLevel;
+	/** Effort string for effort-levels mechanism, keyed by Clio's thinking level. */
+	effortByLevel?: ThinkingEffortByLevel;
+	/** 2-5 line free-text guidance rendered into the Runtime prompt block. */
+	guidance?: string;
+}
+
+export interface LocalModelQuirks {
+	kvCache?: KvCacheQuirks;
+	sampling?: SamplingQuirks;
+	thinking?: ThinkingQuirks;
+}
+
+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;
+}
+
+function asInteger(value: unknown): number | undefined {
+	const n = asPositive(value);
+	return n !== undefined && Number.isInteger(n) ? n : undefined;
+}
+
+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 = {};
+	const temperature = asPositive(raw.temperature);
+	if (temperature !== undefined) out.temperature = temperature;
+	const topP = asPositive(raw.topP);
+	if (topP !== undefined) out.topP = topP;
+	const topK = asInteger(raw.topK);
+	if (topK !== undefined) out.topK = topK;
+	const minP = asPositive(raw.minP);
+	if (minP !== undefined) out.minP = minP;
+	// Catalog YAML may use either `repeatPenalty` (engine field name) or
+	// `repetitionPenalty` (HF model-card term); accept both, preferring the
+	// engine spelling when both are present.
+	const rp = asPenalty(raw.repeatPenalty) ?? asPenalty(raw.repetitionPenalty);
+	if (rp !== undefined) out.repeatPenalty = rp;
+	const pp = asPenalty(raw.presencePenalty);
+	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;
+}
+
+function extractSampling(raw: unknown): SamplingQuirks | undefined {
+	if (!isRecord(raw)) return undefined;
+	const out: SamplingQuirks = {};
+	const thinking = extractSamplingProfile(raw.thinking);
+	if (thinking) out.thinking = thinking;
+	const instruct = extractSamplingProfile(raw.instruct);
+	if (instruct) out.instruct = instruct;
+	return Object.keys(out).length > 0 ? out : undefined;
+}
+
+const THINKING_MECHANISMS: ReadonlyArray<ThinkingMechanism> = [
+	"effort-levels",
+	"budget-tokens",
+	"on-off",
+	"always-on",
+	"none",
+];
+
+function asThinkingMechanism(value: unknown): ThinkingMechanism | undefined {
+	if (typeof value !== "string") return undefined;
+	return (THINKING_MECHANISMS as ReadonlyArray<string>).includes(value) ? (value as ThinkingMechanism) : undefined;
+}
+
+function extractBudgetByLevel(raw: unknown): ThinkingQuirks["budgetByLevel"] | undefined {
+	if (!isRecord(raw)) return undefined;
+	const out: NonNullable<ThinkingQuirks["budgetByLevel"]> = {};
+	const minimal = asInteger(raw.minimal);
+	if (minimal !== undefined) out.minimal = minimal;
+	const low = asInteger(raw.low);
+	if (low !== undefined) out.low = low;
+	const medium = asInteger(raw.medium);
+	if (medium !== undefined) out.medium = medium;
+	const high = asInteger(raw.high);
+	if (high !== undefined) out.high = high;
+	const xhigh = asInteger(raw.xhigh);
+	if (xhigh !== undefined) out.xhigh = xhigh;
+	return Object.keys(out).length > 0 ? out : undefined;
+}
+
+function extractEffortByLevel(raw: unknown): ThinkingQuirks["effortByLevel"] | undefined {
+	if (!isRecord(raw)) return undefined;
+	const out: NonNullable<ThinkingQuirks["effortByLevel"]> = {};
+	if (typeof raw.off === "string" && raw.off.length > 0) out.off = raw.off;
+	if (typeof raw.minimal === "string" && raw.minimal.length > 0) out.minimal = raw.minimal;
+	if (typeof raw.low === "string" && raw.low.length > 0) out.low = raw.low;
+	if (typeof raw.medium === "string" && raw.medium.length > 0) out.medium = raw.medium;
+	if (typeof raw.high === "string" && raw.high.length > 0) out.high = raw.high;
+	if (typeof raw.xhigh === "string" && raw.xhigh.length > 0) out.xhigh = raw.xhigh;
+	return Object.keys(out).length > 0 ? out : undefined;
+}
+
+function extractThinkingQuirks(raw: unknown): ThinkingQuirks | undefined {
+	if (!isRecord(raw)) return undefined;
+	const mechanism = asThinkingMechanism(raw.mechanism);
+	if (!mechanism) return undefined;
+	const out: ThinkingQuirks = { mechanism };
+	const budgetByLevel = extractBudgetByLevel(raw.budgetByLevel);
+	if (budgetByLevel) out.budgetByLevel = budgetByLevel;
+	const effortByLevel = extractEffortByLevel(raw.effortByLevel);
+	if (effortByLevel) out.effortByLevel = effortByLevel;
+	if (typeof raw.guidance === "string" && raw.guidance.length > 0) out.guidance = raw.guidance;
+	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.
+ */
+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;
+	return Object.keys(out).length > 0 ? out : undefined;
+}

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

@@ -0,0 +1,181 @@
+import type { Api, Model } from "../../../engine/types.js";
+
+import type { CapabilityFlags } from "./capability-flags.js";
+import type { CompleteOptions, CompletionChunk, EmbedResult, InfillOptions, RerankResult } from "./inference.js";
+import type { KnowledgeBaseHit } from "./knowledge-base.js";
+import type { TargetDescriptor } from "./target-descriptor.js";
+
+export type RuntimeKind = "http" | "sdk" | "subprocess";
+export type RuntimeTier = "protocol" | "cloud" | "local-native" | "subscription";
+
+export type RuntimeApiFamily =
+	| "openai-completions"
+	| "openai-responses"
+	| "openai-codex-responses"
+	| "azure-openai-responses"
+	| "anthropic-messages"
+	| "bedrock-converse-stream"
+	| "google-generative-ai"
+	| "google-vertex"
+	| "mistral-conversations"
+	| "ollama-native"
+	| "rerank-http"
+	| "embeddings-http"
+	| "claude-agent-sdk"
+	| "claude-code-subprocess";
+
+export type RuntimeAuth = "api-key" | "oauth" | "aws-sdk" | "vertex-adc" | "claude-cli" | "none";
+
+export interface ProbeContext {
+	credentialsPresent: ReadonlySet<string>;
+	httpTimeoutMs: number;
+	signal?: AbortSignal;
+	/**
+	 * Resolved bearer/API token for the target being probed, when one is
+	 * available from stored auth, environment, or refreshed OAuth credentials.
+	 * Auth-gated discovery endpoints can use this instead of reaching into auth
+	 * storage directly.
+	 */
+	authToken?: string;
+}
+
+/**
+ * Map of which inference surfaces a probe found at the target.
+ * Composite local descriptors (llamacpp, lemonade) populate this from a
+ * batched HEAD/GET sweep; fields are absent when the surface did not respond.
+ * Values are the path the probe used so callers can cite it in errors.
+ */
+export interface ProbeSurfaceMap {
+	anthropicMessages?: string;
+	openaiChat?: string;
+	embeddings?: string;
+	rerank?: string;
+	completion?: string;
+	infill?: string;
+	nativeV1?: string;
+	nativeV0?: string;
+}
+
+export type ProbeModelLoadState = "loaded" | "loading" | "unloaded" | "failed" | "unknown";
+
+export interface ProbeModelStatus {
+	state: ProbeModelLoadState;
+	detail?: string;
+	/**
+	 * Context the runtime has this model loaded at, when it reports one. LM
+	 * Studio serves a loaded instance at whatever window it was opened with,
+	 * which is routinely well below the model's `max_context_length`, and that
+	 * smaller number is the one a run has to be planned against. Absent when the
+	 * model is not resident or the runtime does not report it.
+	 */
+	contextLength?: number;
+	/**
+	 * Resident footprint reported by the runtime when a model is loaded. Ollama
+	 * exposes both via `/api/ps` (`size_vram` is the GPU-resident portion,
+	 * `size` the total). Captured here so the picker and any future VRAM-fit
+	 * hinting have a real number to work with instead of re-probing.
+	 */
+	sizeVramBytes?: number;
+	sizeBytes?: number;
+	/** Downloaded model key that owns this configured id or loaded instance. */
+	key?: string;
+	/** Loaded instance id selected for this model, when one exists. */
+	instanceId?: string;
+	/** Load configuration echoed by LM Studio for the selected instance. */
+	loadConfig?: Readonly<Record<string, unknown>>;
+	/** Reasoning levels accepted by this model after LM Studio option clamping. */
+	reasoningLevels?: ReadonlyArray<"off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max">;
+}
+
+export interface ProbeResult {
+	ok: boolean;
+	latencyMs?: number;
+	error?: string;
+	serverVersion?: string;
+	models?: string[];
+	/** Probe-only per-model load state when the runtime exposes it. */
+	modelStates?: Record<string, ProbeModelStatus>;
+	discoveredCapabilities?: Partial<CapabilityFlags>;
+	/** Probe-only capabilities keyed by wire model id when a runtime can list model metadata. */
+	modelCapabilities?: Record<string, Partial<CapabilityFlags>>;
+	/** Wire model id those discovered capabilities describe, when known. */
+	capabilityModelId?: string;
+	/**
+	 * Free-form diagnostic notes from the probe. llama.cpp uses this to flag a
+	 * mismatch between the configured wire model id and the server's loaded
+	 * weights (single-model server, so there is no eviction recourse).
+	 */
+	notes?: ReadonlyArray<string>;
+	/**
+	 * Composite descriptors set this to the api family they will use for chat.
+	 * `synthesizeModel` reads it back out of the cached probe state to choose
+	 * which provider implementation pi-ai routes to. Absent when the descriptor
+	 * is single-surface or no chat surface was reachable.
+	 */
+	chatApiFamily?: RuntimeApiFamily;
+	surfaces?: ProbeSurfaceMap;
+}
+
+export interface ReasoningProbeResult {
+	reasoning: boolean;
+	latencyMs: number;
+	error?: string;
+}
+
+export interface RuntimeDescriptor {
+	id: string;
+	/** Deprecated or compatibility ids that resolve to this descriptor object. */
+	aliases?: ReadonlyArray<string>;
+	displayName: string;
+	kind: RuntimeKind;
+	tier?: RuntimeTier;
+	apiFamily: RuntimeApiFamily;
+	auth: RuntimeAuth;
+	credentialsEnvVar?: string;
+	/**
+	 * pi-ai OAuth provider id backing this runtime when `auth === "oauth"` and it
+	 * differs from `id`. `openai-codex` omits this because its registry id, target
+	 * `oauthProfile`, and pi-ai provider id all coincide. The Claude Pro/Max
+	 * runtime sets this to `"anthropic"` so login/refresh/credential storage key
+	 * on the pi-ai `anthropic` OAuth provider while keeping a distinct registry id
+	 * (`anthropic-max`) from the api-key `anthropic` runtime.
+	 */
+	oauthProviderId?: string;
+	/**
+	 * Optional one-line notice printed before an interactive `clio-coder auth login` or
+	 * configure connect for this runtime. Used to surface subscription usage-terms
+	 * considerations so OAuth subscription paths are an explicit, informed opt-in.
+	 */
+	authNotice?: string;
+	knownModels?: string[];
+	binaryName?: string;
+	defaultBinaryPath?: string;
+	headlessCommand?: string;
+	outputParser?: string;
+	defaultCapabilities: CapabilityFlags;
+	/**
+	 * 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)
+	 * that stays resolvable by id but is hidden from `clio-coder configure --list` and
+	 * the interactive wizard, where a composite descriptor owns the
+	 * user-visible slot.
+	 */
+	hidden?: boolean;
+	probe?(target: TargetDescriptor, ctx: ProbeContext): Promise<ProbeResult>;
+	probeModels?(target: TargetDescriptor, ctx: ProbeContext): Promise<string[]>;
+	/**
+	 * Optional per-model reasoning capability probe. Protocol-compatible local
+	 * servers (LM Studio, llama.cpp, Ollama, ...) advertise an OpenAI or
+	 * Anthropic wire surface regardless of whether the loaded model supports
+	 * thinking. Implementations here send a one-shot priming request and look at
+	 * `reasoning_content` / `reasoning` / `reasoning_text` in the response.
+	 * Result is cached per (target, model) by the providers domain so
+	 * /thinking can surface the correct level set.
+	 */
+	probeReasoning?(target: TargetDescriptor, modelId: string, ctx: ProbeContext): Promise<ReasoningProbeResult>;
+	synthesizeModel(target: TargetDescriptor, wireModelId: string, kb: KnowledgeBaseHit | null): Model<Api>;
+	complete?(target: TargetDescriptor, opts: CompleteOptions, ctx: ProbeContext): AsyncIterable<CompletionChunk>;
+	infill?(target: TargetDescriptor, opts: InfillOptions, ctx: ProbeContext): AsyncIterable<CompletionChunk>;
+	embed?(target: TargetDescriptor, input: string | string[], ctx: ProbeContext): Promise<EmbedResult>;
+	rerank?(target: TargetDescriptor, query: string, documents: string[], ctx: ProbeContext): Promise<RerankResult>;
+}

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

@@ -0,0 +1,60 @@
+import type { CapabilityFlags } from "./capability-flags.js";
+
+export interface TargetAuth {
+	apiKeyEnvVar?: string;
+	apiKeyRef?: string;
+	oauthProfile?: string;
+	headers?: Record<string, string>;
+}
+
+export interface TargetPricing {
+	input: number;
+	output: number;
+	cacheRead?: number;
+	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";
+
+export interface LmStudioLoadSettings {
+	contextLength?: number;
+	flashAttention?: boolean;
+	evalBatchSize?: number;
+	numExperts?: number;
+	offloadKvCacheToGpu?: boolean;
+}
+
+export type LmStudioReasoningSetting = "auto" | "off" | "on" | "low" | "medium" | "high";
+
+export interface LmStudioRequestSettings {
+	ttlSeconds?: number;
+	draftModel?: string;
+	reasoning?: LmStudioReasoningSetting;
+}
+
+export interface LmStudioTargetSettings {
+	load?: LmStudioLoadSettings;
+	request?: LmStudioRequestSettings;
+}
+
+/**
+ * Persisted target specification from settings.yaml (`targets:`). It binds a
+ * user-facing target id to a RuntimeDescriptor id, target URL/auth metadata,
+ * model defaults, and capability overrides. Runtime resolution combines this
+ * spec with the registry/catalog to produce a ResolvedRuntimeTarget.
+ */
+export interface TargetDescriptor {
+	id: string;
+	runtime: string;
+	url?: string;
+	auth?: TargetAuth;
+	defaultModel?: string;
+	wireModels?: string[];
+	capabilities?: Partial<CapabilityFlags>;
+	lifecycle?: TargetLifecycle;
+	gateway?: boolean;
+	pricing?: TargetPricing;
+	lmstudio?: LmStudioTargetSettings;
+}