@iowarp/clio-coder 0.3.0 → 0.3.2

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

@@ -0,0 +1,102 @@
+import { existsSync, statSync } from "node:fs";
+import { delimiter, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveClioDirs } from "../../core/xdg.js";
+import type { KnowledgeBaseRoot } from "./types/knowledge-base.js";
+
+export const MODEL_CATALOG_OVERLAY_DIR = "model-catalog.d";
+export const MODEL_CATALOG_DIRS_ENV = "CLIO_CODER_MODEL_CATALOG_DIRS";
+
+export interface ProviderModelCatalogDirs {
+	/** Bundled curated catalog shipped with Clio, when present. */
+	bundled: string | null;
+	/** Existing user/project/env overlay roots, ordered from lower to higher precedence. */
+	overlays: string[];
+	/** All existing roots, ordered from lower to higher precedence. */
+	all: string[];
+}
+
+function isDirectory(path: string): boolean {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function resolveProvidersModelsDir(importMetaUrl: string): string | null {
+	const start = dirname(fileURLToPath(importMetaUrl));
+	const directCandidates = [
+		join(start, "models"),
+		join(start, "..", "domains", "providers", "models"),
+		join(start, "..", "providers-models"),
+	];
+	for (const candidate of directCandidates) {
+		if (isDirectory(candidate)) return candidate;
+	}
+
+	let cursor = start;
+	for (let i = 0; i < 8; i++) {
+		const packageJson = join(cursor, "package.json");
+		const sourceModels = join(cursor, "src", "domains", "providers", "models");
+		const distModels = join(cursor, "dist", "providers-models");
+		if (existsSync(packageJson)) {
+			if (isDirectory(sourceModels)) return sourceModels;
+			if (isDirectory(distModels)) return distModels;
+		}
+		const parent = dirname(cursor);
+		if (parent === cursor) break;
+		cursor = parent;
+	}
+	return null;
+}
+
+function uniqueExistingDirs(paths: ReadonlyArray<string | null | undefined>): string[] {
+	const out: string[] = [];
+	const seen = new Set<string>();
+	for (const candidate of paths) {
+		const path = candidate?.trim();
+		if (!path || seen.has(path) || !isDirectory(path)) continue;
+		seen.add(path);
+		out.push(path);
+	}
+	return out;
+}
+
+function envOverlayDirs(): string[] {
+	const raw = process.env[MODEL_CATALOG_DIRS_ENV]?.trim();
+	if (!raw) return [];
+	return raw
+		.split(delimiter)
+		.map((entry) => entry.trim())
+		.filter((entry) => entry.length > 0);
+}
+
+export function resolveProviderModelCatalogDirs(
+	importMetaUrl: string,
+	options: { cwd?: string } = {},
+): ProviderModelCatalogDirs {
+	const bundled = resolveProvidersModelsDir(importMetaUrl);
+	const cwd = options.cwd ?? process.cwd();
+	const overlays = uniqueExistingDirs([
+		join(resolveClioDirs().config, MODEL_CATALOG_OVERLAY_DIR),
+		join(cwd, ".clio-coder", MODEL_CATALOG_OVERLAY_DIR),
+		...envOverlayDirs(),
+	]);
+	return {
+		bundled,
+		overlays,
+		all: uniqueExistingDirs([bundled, ...overlays]),
+	};
+}
+
+export function resolveProviderKnowledgeBaseRoots(
+	importMetaUrl: string,
+	options: { cwd?: string } = {},
+): KnowledgeBaseRoot[] {
+	const dirs = resolveProviderModelCatalogDirs(importMetaUrl, options);
+	return [
+		...(dirs.bundled ? [{ dir: dirs.bundled, label: "bundled" }] : []),
+		...dirs.overlays.map((dir) => ({ dir, label: `overlay:${dir}` })),
+	];
+}

package/src/domains/providers/manifest.ts

@@ -0,0 +1,6 @@
+import type { DomainManifest } from "../../core/domain-loader.js";
+
+export const ProvidersManifest: DomainManifest = {
+	name: "providers",
+	dependsOn: ["config"] as const,
+};

package/src/domains/providers/model-capabilities.ts

@@ -0,0 +1,136 @@
+import { mergeCapabilities } from "./capabilities.js";
+import { capabilitiesFromCatalogModel, getCatalogModelForRuntime } from "./catalog.js";
+import type { TargetStatus } from "./contract.js";
+import { type CapabilityFlags, EMPTY_CAPABILITIES } from "./types/capability-flags.js";
+import type { KnowledgeBase } from "./types/knowledge-base.js";
+import { extractLocalModelQuirks } from "./types/local-model-quirks.js";
+
+function normalizedModelId(wireModelId: string | null | undefined): string | null {
+	const trimmed = wireModelId?.trim();
+	return trimmed ? trimmed : null;
+}
+
+export interface ModelCapabilityPatchTarget {
+	contextWindow?: number;
+	maxTokens?: number;
+	reasoning?: boolean;
+}
+
+/**
+ * Apply the small mutable capability surface pi-ai reads from model objects.
+ * Runtime synthesis returns immutable-ish catalog objects, but live probes can
+ * refine context/output/reasoning after synthesis. Keeping the mutation in one
+ * helper makes those refinements explicit and avoids ad-hoc casts at call sites.
+ */
+export function applyModelCapabilityPatch<T extends ModelCapabilityPatchTarget>(
+	model: T,
+	caps: Partial<CapabilityFlags> | null | undefined,
+): T {
+	if (!caps) return model;
+	if (typeof caps.contextWindow === "number") model.contextWindow = caps.contextWindow;
+	if (typeof caps.maxTokens === "number") model.maxTokens = caps.maxTokens;
+	if (typeof caps.reasoning === "boolean") model.reasoning = caps.reasoning;
+	return model;
+}
+
+export interface ResolveModelCapabilitiesOptions {
+	/**
+	 * Per-(target, model) reasoning detection result, typically supplied by
+	 * `providers.getDetectedReasoning(targetId, modelId)`. When true or
+	 * false, the returned caps preserve that exact live result. Null leaves
+	 * the merged value untouched.
+	 */
+	detectedReasoning?: boolean | null;
+}
+
+function applyReasoningResolution(
+	caps: CapabilityFlags,
+	kbHit: ReturnType<KnowledgeBase["lookup"]> | null | undefined,
+	detectedReasoning: boolean | null,
+): CapabilityFlags {
+	const mechanism = extractLocalModelQuirks(kbHit?.entry.quirks)?.thinking?.mechanism;
+	if (mechanism === "none") return { ...caps, reasoning: false };
+	if (mechanism === "always-on") return { ...caps, reasoning: true };
+	return detectedReasoning === null ? caps : { ...caps, reasoning: detectedReasoning };
+}
+
+/**
+ * Resolve the effective capability set for one target/model pair.
+ *
+ * TargetStatus stores a merged target-level view in `capabilities`, which
+ * is adequate for health/readiness, but the model picker and thinking controls
+ * need the selected row's own knowledge-base hit. When model-keyed
+ * `probeCapabilities` are present for this same wire model, rebuild the stack as:
+ *
+ *   runtime defaults + knowledge-base(model) + live probe + target override
+ *
+ * When older test doubles do not provide `probeCapabilities`, fall back to the
+ * pre-merged `status.capabilities` for the target-default model.
+ *
+ * `options.detectedReasoning` lets callers feed in a per-model reasoning probe
+ * result so /thinking and the model picker reflect what the loaded model can
+ * actually do, without baking the detection into the runtime defaults.
+ */
+type ProbeCapabilityStatus = Pick<
+	TargetStatus,
+	"target" | "probeCapabilities" | "probeModelCapabilities" | "probeModelId"
+>;
+
+export function probeCapabilitiesForModel(
+	status: ProbeCapabilityStatus,
+	wireModelId: string | null | undefined,
+): Partial<CapabilityFlags> | null {
+	const modelId = normalizedModelId(wireModelId) ?? normalizedModelId(status.target.defaultModel);
+	if (!modelId) return null;
+	const exact = status.probeModelCapabilities?.[modelId];
+	if (exact) return exact;
+	const probeModelId = normalizedModelId(status.probeModelId);
+	if (probeModelId !== null) return probeModelId === modelId ? (status.probeCapabilities ?? null) : null;
+	const defaultModelId = normalizedModelId(status.target.defaultModel);
+	return defaultModelId !== null && defaultModelId === modelId ? (status.probeCapabilities ?? null) : null;
+}
+
+export function resolveModelCapabilities(
+	status: Pick<
+		TargetStatus,
+		"target" | "runtime" | "capabilities" | "probeCapabilities" | "probeModelCapabilities" | "probeModelId"
+	>,
+	wireModelId: string | null | undefined,
+	knowledgeBase: KnowledgeBase | null,
+	options?: ResolveModelCapabilitiesOptions,
+): CapabilityFlags {
+	const detectedReasoning = options?.detectedReasoning ?? null;
+
+	if (!status.runtime) {
+		const modelId = normalizedModelId(wireModelId) ?? normalizedModelId(status.target.defaultModel);
+		const kbHit = modelId ? (knowledgeBase?.lookup(modelId) ?? null) : null;
+		return applyReasoningResolution(status.capabilities, kbHit, detectedReasoning);
+	}
+	const modelId = normalizedModelId(wireModelId) ?? normalizedModelId(status.target.defaultModel);
+	const baseCapabilities = capabilitiesFromCatalogModel(
+		status.runtime.defaultCapabilities ?? EMPTY_CAPABILITIES,
+		modelId ? getCatalogModelForRuntime(status.runtime.id, modelId) : undefined,
+	);
+	const kbHit = modelId ? (knowledgeBase?.lookup(modelId) ?? null) : null;
+	const hasModernProbeFields = status.probeCapabilities !== undefined || status.probeModelCapabilities !== undefined;
+	if (!hasModernProbeFields) {
+		if (!modelId || modelId === normalizedModelId(status.target.defaultModel)) {
+			return applyReasoningResolution(status.capabilities, kbHit, detectedReasoning);
+		}
+		return applyReasoningResolution(
+			mergeCapabilities(baseCapabilities, kbHit?.entry.capabilities ?? null, null, status.target.capabilities ?? null),
+			kbHit,
+			detectedReasoning,
+		);
+	}
+	return applyReasoningResolution(
+		mergeCapabilities(
+			baseCapabilities,
+			kbHit?.entry.capabilities ?? null,
+			probeCapabilitiesForModel(status, modelId),
+			status.target.capabilities ?? null,
+		),
+		kbHit,
+		detectedReasoning,
+	);
+}

package/src/domains/providers/model-discovery.ts

@@ -0,0 +1,144 @@
+import type { TargetStatus } from "./contract.js";
+import { listKnownModelsForRuntime } from "./support.js";
+
+export type ProviderModelSource = "configured" | "live" | "catalog" | "default";
+
+export interface ProviderModelCandidate {
+	id: string;
+	source: ProviderModelSource;
+	loadState?: string;
+	loadStateDetail?: string;
+}
+
+function uniqueModels(ids: ReadonlyArray<string | undefined>): string[] {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const id of ids) {
+		const trimmed = id?.trim() ?? "";
+		if (trimmed.length === 0 || seen.has(trimmed)) continue;
+		seen.add(trimmed);
+		out.push(trimmed);
+	}
+	return out;
+}
+
+export function modelLoadStateLabel(status: TargetStatus, modelId: string): string {
+	return status.discoveredModelStates?.[modelId]?.state ?? "-";
+}
+
+/** Whether the model is serving, waiting to serve, or not on the server at all. */
+export type ModelResidency = "resident" | "loading" | "absent" | "unknown";
+
+type DiscoveryStatus = Pick<TargetStatus, "discoveredModelStates">;
+
+/**
+ * The window discovery says this model is loaded at, or null when discovery has
+ * no such number. Ranked above every declared window: `max_context_length` is
+ * what the weights allow, this is what the backend will actually serve, and a
+ * run planned against the larger one overruns before compaction ever fires.
+ */
+export function loadedContextWindowForModel(
+	status: DiscoveryStatus | null | undefined,
+	modelId: string,
+): number | null {
+	const reported = status?.discoveredModelStates?.[modelId]?.contextLength;
+	return typeof reported === "number" && Number.isFinite(reported) && reported > 0 ? reported : null;
+}
+
+/**
+ * Residency as one view, so the planner and the "not resident" notice cannot
+ * disagree about the same model. A reported loaded window settles it whatever
+ * the state field says: a server does not hold a window open for a model it has
+ * not loaded.
+ */
+export function modelResidencyForStatus(status: DiscoveryStatus | null | undefined, modelId: string): ModelResidency {
+	if (loadedContextWindowForModel(status, modelId) !== null) return "resident";
+	switch (status?.discoveredModelStates?.[modelId]?.state) {
+		case "loaded":
+			return "resident";
+		case "loading":
+			return "loading";
+		case "unloaded":
+			return "absent";
+		default:
+			return "unknown";
+	}
+}
+
+export function hasLiveModelCatalog(status: TargetStatus): boolean {
+	if (status.discoveredModelsSource === "probe" || status.discoveredModelsSource === "cache") return true;
+	// Unit-test and plugin mocks from before `discoveredModelsSource` still use
+	// `discoveredModels` to mean "this came from discovery".
+	return status.discoveredModelsSource === undefined && status.discoveredModels.length > 0;
+}
+
+/**
+ * Enumerate selectable wire model ids for a target. Before a live catalog is
+ * known, Clio keeps useful configured/default/catalog hints. Once the target
+ * returns a live catalog, that catalog is authoritative: configured and default
+ * model ids that the provider no longer returns stop resolving.
+ */
+export function modelCandidatesForStatus(status: TargetStatus): ProviderModelCandidate[] {
+	const configured = uniqueModels(status.target.wireModels ?? []);
+	const discovered = uniqueModels(status.discoveredModels);
+	const defaultModel = status.target.defaultModel?.trim() ?? "";
+	const out: ProviderModelCandidate[] = [];
+	const seen = new Set<string>();
+	const add = (id: string, source: ProviderModelSource): void => {
+		const trimmed = id.trim();
+		if (trimmed.length === 0 || seen.has(trimmed)) return;
+		seen.add(trimmed);
+		const state = status.discoveredModelStates?.[trimmed];
+		out.push({
+			id: trimmed,
+			source,
+			...(state ? { loadState: state.state } : {}),
+			...(state?.detail ? { loadStateDetail: state.detail } : {}),
+		});
+	};
+
+	if (hasLiveModelCatalog(status)) {
+		for (const id of discovered) add(id, "live");
+		return out;
+	}
+
+	if (configured.length > 0) {
+		for (const id of configured) add(id, "configured");
+		if (defaultModel) add(defaultModel, "default");
+		return out;
+	}
+
+	const knownModels = listKnownModelsForRuntime(status.runtime?.id ?? status.target.runtime);
+	if (knownModels.length > 0) {
+		const knownSet = new Set(knownModels);
+		for (const id of uniqueModels([defaultModel, ...knownModels])) {
+			add(id, knownSet.has(id) ? "catalog" : "default");
+		}
+		return out;
+	}
+
+	if (defaultModel) add(defaultModel, "default");
+	return out;
+}
+
+export function modelIdsForStatus(status: TargetStatus): string[] {
+	return modelCandidatesForStatus(status).map((candidate) => candidate.id);
+}
+
+export function canonicalizeWireModelId(status: TargetStatus, requested: string): string {
+	const trimmedRequested = requested.trim();
+	if (trimmedRequested.length === 0) return requested;
+	// Canonicalize against the authoritative wire ids: the live catalog when one
+	// exists, otherwise the configured wire models.
+	const candidates = uniqueModels(
+		hasLiveModelCatalog(status) ? status.discoveredModels : (status.target.wireModels ?? []),
+	);
+	if (candidates.includes(trimmedRequested)) return trimmedRequested;
+
+	const separators = ["-", ":", ".", "/"];
+	const matches = candidates.filter((candidate) => {
+		if (candidate.toLowerCase() === trimmedRequested.toLowerCase()) return true;
+		return separators.some((separator) => candidate.startsWith(`${trimmedRequested}${separator}`));
+	});
+	return matches.length === 1 ? (matches[0] ?? requested) : requested;
+}

package/src/domains/providers/model-family.ts

@@ -0,0 +1,32 @@
+export type LocalModelFamily =
+	| "openai-gpt-oss"
+	| "qwen3"
+	| "nemotron-3-nano-omni"
+	| "nemotron-cascade-2"
+	| "gemma-4"
+	| "unknown";
+
+export function normalizeModelIdForFamily(modelId: string | null | undefined): string {
+	return (modelId ?? "").trim().toLowerCase().replace(/_/g, "-");
+}
+
+export function isHarmonyModelId(modelId: string | null | undefined): boolean {
+	return normalizeModelIdForFamily(modelId).includes("gpt-oss");
+}
+
+export function inferLocalModelFamily(modelId: string | null | undefined): LocalModelFamily {
+	const normalized = normalizeModelIdForFamily(modelId);
+	if (normalized.length === 0) return "unknown";
+	if (normalized.includes("gpt-oss")) return "openai-gpt-oss";
+	if (normalized.includes("nemotron-cascade-2") || normalized.includes("nemotron-cascade2")) {
+		return "nemotron-cascade-2";
+	}
+	if (normalized.includes("nemotron-3-nano-omni") || normalized.includes("nemotron-nano-omni")) {
+		return "nemotron-3-nano-omni";
+	}
+	if (normalized.includes("qwen3")) return "qwen3";
+	if (normalized.includes("gemma-4") || normalized.includes("gemma4") || normalized.includes("gemopus")) {
+		return "gemma-4";
+	}
+	return "unknown";
+}