@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/interactive/overlays/model-selector.ts

@@ -0,0 +1,1091 @@
+import { BusChannels } from "../../core/bus-events.js";
+import type { ClioSettings } from "../../core/config.js";
+import type { SafeEventBus } from "../../core/event-bus.js";
+import { listRecentModels } from "../../core/recent-models.js";
+import type {
+	CapabilityFlags,
+	ProvidersContract,
+	ResolvedRuntimeTarget,
+	RuntimeCapabilityDecision,
+	RuntimeResolutionDiagnostic,
+	TargetStatus,
+	ThinkingLevel,
+} from "../../domains/providers/index.js";
+import {
+	AGENT_ROLE_TOOLS_REQUIRED_REASON,
+	isOrchestratorEligibleRuntime,
+	modelCandidatesForStatus,
+	modelIdsForStatus,
+	type ProviderModelSource,
+	resolveRuntimeTarget,
+	supportsAgentRoleTools,
+} from "../../domains/providers/index.js";
+import {
+	type Component,
+	getKeybindings,
+	matchesKey,
+	type OverlayHandle,
+	type SelectItem,
+	type TUI,
+	truncateToWidth,
+	visibleWidth,
+} from "../../engine/tui.js";
+import {
+	buildHint,
+	clioError,
+	FILTER_HINT,
+	formatRuntimeResolutionDiagnostic,
+	runtimeResolutionDiagnosticLine,
+	showClioOverlayFrame,
+} from "../overlay-frame.js";
+import { type ClioToken, clioTheme, GLYPH } from "../theme/index.js";
+
+export const MODEL_OVERLAY_WIDTH = 82;
+const MODEL_OVERLAY_MAX_WIDTH = 120;
+const MODEL_OVERLAY_TERMINAL_PADDING = 8;
+const VISIBLE_ROWS = 10;
+const MODEL_MIN_WIDTH = 14;
+const CONTEXT_COL_WIDTH = 7;
+const CAPS_COL_WIDTH = 5;
+const TARGET_COL_WIDTH_NARROW = 8;
+const TARGET_COL_WIDTH_WIDE = 12;
+const RUNTIME_COL_WIDTH_NARROW = 10;
+const RUNTIME_COL_WIDTH_MEDIUM = 14;
+const RUNTIME_COL_WIDTH_WIDE = 18;
+const SELECTED_PREFIX_WIDTH = 6;
+const BACKSPACE = "\x7f";
+const BACKSPACE_ALT = "\b";
+const CTRL_U = "\x15";
+const TAB = "\t";
+
+function resolveOverlayWidth(terminalColumns: number): number {
+	// Default 82 fits a typical 80-col terminal with margin. On wider
+	// terminals grow the overlay so target/runtime columns can stay visible.
+	if (!Number.isFinite(terminalColumns) || terminalColumns <= 0) return MODEL_OVERLAY_WIDTH;
+	const available = terminalColumns - MODEL_OVERLAY_TERMINAL_PADDING;
+	if (available <= MODEL_OVERLAY_WIDTH) return Math.max(1, available);
+	return Math.min(MODEL_OVERLAY_MAX_WIDTH, available);
+}
+
+export interface ModelSelection {
+	target: string;
+	model: string;
+}
+
+export interface OpenModelOverlayDeps {
+	settings: Readonly<ClioSettings>;
+	/** Optional live settings resolver so refreshes pick up target/config edits made while the overlay is open. */
+	getSettings?: () => Readonly<ClioSettings>;
+	providers: ProvidersContract;
+	bus?: SafeEventBus;
+	onSelect: (ref: ModelSelection) => void;
+	onToggleFavorite?: (ref: ModelSelection, favorite: boolean) => void;
+	onClose: () => void;
+	autoRefresh?: boolean;
+}
+
+function healthGlyph(status: TargetStatus): string {
+	switch (status.health.status) {
+		case "healthy":
+			return GLYPH.running;
+		case "degraded":
+			return "◐";
+		case "down":
+			return "○";
+		default:
+			return "·";
+	}
+}
+
+/**
+ * Map a row's health glyph back to its semantic token so the status cell states
+ * the fact in color: healthy green, degraded amber, down red, unknown dim.
+ */
+function healthToken(row: ModelRow): ClioToken {
+	switch (row.healthGlyph) {
+		case GLYPH.running:
+			return "success";
+		case "◐":
+			return "warning";
+		case "○":
+			return "error";
+		default:
+			return "dim";
+	}
+}
+
+function capabilityBadges(caps: CapabilityFlags): string {
+	let badges = "";
+	if (caps.tools) badges += "T";
+	if (caps.reasoning) badges += "R";
+	if (caps.vision) badges += "V";
+	if (caps.embeddings) badges += "E";
+	if (caps.rerank) badges += "K";
+	if (caps.fim) badges += "F";
+	return badges.length > 0 ? badges : "-";
+}
+
+function compactTokenCount(value: number): string {
+	if (!Number.isFinite(value) || value <= 0) return "?";
+	const rounded = Math.round(value);
+	if (rounded >= 1_000_000) return `${Math.round(rounded / 100_000) / 10}m`;
+	if (rounded >= 1000) return `${Math.round(rounded / 1000)}k`;
+	return `${rounded}`;
+}
+
+function contextDecisionLabel(decisions: RuntimeCapabilityDecision): string {
+	return `${compactTokenCount(decisions.contextWindow)}ctx`;
+}
+
+function maxTokensDecisionLabel(decisions: RuntimeCapabilityDecision): string {
+	return compactTokenCount(decisions.maxTokens);
+}
+
+function truncateMiddle(text: string, maxWidth: number): string {
+	if (maxWidth <= 0 || text.length <= maxWidth) return text;
+	if (maxWidth <= 8) return truncateToWidth(text, maxWidth, "", true);
+	const suffixWidth = Math.min(14, Math.max(6, Math.floor(maxWidth / 3)));
+	const prefixWidth = maxWidth - suffixWidth - 1;
+	if (prefixWidth <= 0) return truncateToWidth(text, maxWidth, "", true);
+	return `${text.slice(0, prefixWidth)}…${text.slice(-suffixWidth)}`;
+}
+
+type ModelSource = ProviderModelSource | "missing";
+type ModelBucket = "local" | "cloud";
+type ModelRefreshScope = "selected" | "all";
+
+export interface ModelRow {
+	value: string;
+	target: string;
+	model: string;
+	runtimeName: string;
+	runtimeShortName: string;
+	runtimeId: string;
+	apiFamily: string;
+	bucket: ModelBucket;
+	source: ModelSource;
+	loadState?: string;
+	loadStateDetail?: string;
+	authText: string;
+	available: boolean;
+	reason: string;
+	healthGlyph: string;
+	healthText: string;
+	caps: CapabilityFlags;
+	capabilityDecisions?: RuntimeCapabilityDecision;
+	thinking?: string;
+	streaming?: boolean;
+	diagnostics?: RuntimeResolutionDiagnostic[];
+	badges: string;
+	context: string;
+	maxTokens: string;
+	active: boolean;
+	scoped: boolean;
+	favorite?: boolean;
+	recent?: boolean;
+	defaultModel?: boolean;
+	focusPinned?: boolean;
+	visibleByDefault?: boolean;
+	selectable: boolean;
+}
+
+export interface ModelOverlaySummary {
+	totalModels: number;
+	targets: number;
+	localModels: number;
+	cloudModels: number;
+	activeRef: string;
+	focusedModels?: number;
+}
+
+/** Enumerate target wire model ids with live discovery taking precedence when available. */
+export function modelsForTarget(status: TargetStatus): string[] {
+	return modelIdsForStatus(status);
+}
+
+export interface ModelItemsResult {
+	items: SelectItem[];
+	/** Parallel to items. onSelect of items[i] resolves to refs[i]. */
+	refs: ModelSelection[];
+	rows: ModelRow[];
+	summary: ModelOverlaySummary;
+}
+
+function fallbackCapabilityDecisions(status: TargetStatus, caps: CapabilityFlags): RuntimeCapabilityDecision {
+	const kind = status.runtime?.kind;
+	return {
+		chat: caps.chat,
+		tools: caps.tools,
+		reasoning: caps.reasoning,
+		vision: caps.vision,
+		streaming: kind === "http",
+		contextWindow: caps.contextWindow,
+		maxTokens: caps.maxTokens,
+	};
+}
+
+function providersWithStatusFallback(providers: ProvidersContract, status: TargetStatus): ProvidersContract {
+	return {
+		...providers,
+		getTarget: (id) => providers.getTarget(id) ?? (id === status.target.id ? status.target : null),
+		getRuntime: (id) => providers.getRuntime(id) ?? (status.runtime && id === status.runtime.id ? status.runtime : null),
+	};
+}
+
+interface OverlayRuntimeResolution {
+	target: ResolvedRuntimeTarget | null;
+	diagnostics: RuntimeResolutionDiagnostic[];
+	capabilities: CapabilityFlags;
+	capabilityDecisions: RuntimeCapabilityDecision;
+	thinking: string;
+	streaming: boolean;
+}
+
+/** Resolve the same runtime/capability descriptor used by the footer and chat loop for one overlay row. */
+function resolveOverlayRuntimeTarget(input: {
+	providers: ProvidersContract;
+	status: TargetStatus;
+	wireModelId: string;
+	requestedThinkingLevel?: ThinkingLevel;
+}): OverlayRuntimeResolution {
+	const resolution = resolveRuntimeTarget(providersWithStatusFallback(input.providers, input.status), {
+		targetId: input.status.target.id,
+		wireModelId: input.wireModelId,
+		requestedThinkingLevel: input.requestedThinkingLevel ?? "off",
+		use: "orchestrator",
+		requireTools: true,
+		requireStreaming: true,
+		requireOutputBudget: true,
+	});
+	if (resolution.ok) {
+		return {
+			target: resolution.target,
+			diagnostics: resolution.diagnostics,
+			capabilities: resolution.target.capabilities,
+			capabilityDecisions: resolution.target.capabilityDecisions,
+			thinking: resolution.target.modelRuntime.thinking.display,
+			streaming: resolution.target.capabilityDecisions.streaming,
+		};
+	}
+	const capabilities = input.status.capabilities;
+	const decisions = fallbackCapabilityDecisions(input.status, capabilities);
+	return {
+		target: null,
+		diagnostics: resolution.diagnostics,
+		capabilities,
+		capabilityDecisions: decisions,
+		thinking: "unresolved",
+		streaming: decisions.streaming,
+	};
+}
+
+function modelBucket(status: TargetStatus): ModelBucket {
+	const tier = status.runtime?.tier;
+	if (
+		tier === "protocol" ||
+		tier === "local-native" ||
+		status.target.url?.includes("127.0.0.1") ||
+		status.target.url?.includes("localhost")
+	) {
+		return "local";
+	}
+	return "cloud";
+}
+
+function shortRuntimeName(name: string): string {
+	return name
+		.replace(/\s*\(OpenAI-compat\)\s*/g, "")
+		.replace(/\s+native API$/i, "")
+		.replace(/\s+API$/i, "")
+		.replace(/\s+SDK$/i, "");
+}
+
+function authLabel(deps: { providers: ProvidersContract; status: TargetStatus }): string {
+	const { providers, status } = deps;
+	if (!status.runtime) return "unknown";
+	const auth = providers.auth.statusForTarget(status.target, status.runtime);
+	if (!auth.available) return "disconnected";
+	if (auth.source === "environment") return auth.detail ? `env:${auth.detail}` : "environment";
+	if (auth.source === "none") return "not required";
+	return auth.detail ? `${auth.source}:${auth.detail}` : auth.source;
+}
+
+function healthText(status: TargetStatus): string {
+	const latency =
+		typeof status.health.latencyMs === "number" && Number.isFinite(status.health.latencyMs)
+			? ` ${Math.round(status.health.latencyMs)}ms`
+			: "";
+	if (status.health.status === "unknown") return "unknown";
+	if (status.health.lastError) return `${status.health.status}: ${status.health.lastError}`;
+	return `${status.health.status}${latency}`;
+}
+
+function statusPriority(status: TargetStatus): number {
+	if (status.available && status.health.status === "healthy") return 0;
+	if (status.available && status.health.status !== "down") return 1;
+	return 2;
+}
+
+function buildSummary(rows: ReadonlyArray<ModelRow>, targets: number, activeRef: string): ModelOverlaySummary {
+	let localModels = 0;
+	let cloudModels = 0;
+	for (const row of rows) {
+		if (!row.selectable) continue;
+		if (row.bucket === "local") localModels++;
+		else cloudModels++;
+	}
+	return {
+		totalModels: localModels + cloudModels,
+		targets,
+		localModels,
+		cloudModels,
+		activeRef,
+		focusedModels: rows.filter((row) => row.selectable && row.visibleByDefault !== false).length,
+	};
+}
+
+/**
+ * Build the target-first model picker. Each configured target renders one
+ * row per candidate wire model (see `modelsForTarget`). Targets without
+ * a resolvable wire model still render a single "no-model" row so users can
+ * see the target exists and why it is not selectable. Scope stars come from
+ * `settings.scope`: both plain `targetId` and `targetId/wireModelId` refs
+ * match so a user can pin either granularity.
+ */
+export function buildModelItems(deps: {
+	settings: Readonly<ClioSettings>;
+	providers: ProvidersContract;
+}): ModelItemsResult {
+	const activeTarget = deps.settings.orchestrator?.target?.trim() ?? "";
+	const activeModel = deps.settings.orchestrator?.model?.trim() ?? "";
+	const activeRef = activeTarget && activeModel ? `${activeTarget}/${activeModel}` : activeTarget;
+	const favoriteSet = new Set(deps.settings.modelSelector?.favorites ?? []);
+	const recentSet = new Set(listRecentModels({ limit: deps.settings.modelSelector?.recentLimit ?? 12 }));
+	const list = [...deps.providers.list()]
+		.filter((status) => {
+			return status.runtime !== null && isOrchestratorEligibleRuntime(status.runtime);
+		})
+		.sort((a, b) => {
+			const aActive = a.target.id === activeTarget ? 0 : 1;
+			const bActive = b.target.id === activeTarget ? 0 : 1;
+			return (
+				aActive - bActive ||
+				statusPriority(a) - statusPriority(b) ||
+				(a.runtime?.displayName ?? a.target.runtime).localeCompare(b.runtime?.displayName ?? b.target.runtime) ||
+				a.target.id.localeCompare(b.target.id)
+			);
+		});
+	const scopeSet = new Set(deps.settings.scope ?? []);
+	const items: SelectItem[] = [];
+	const refs: ModelSelection[] = [];
+	const rows: ModelRow[] = [];
+	for (const status of list) {
+		const { target } = status;
+		const runtimeName = status.runtime?.displayName ?? target.runtime;
+		const runtimeShortName = shortRuntimeName(runtimeName);
+		const candidates = modelCandidatesForStatus(status);
+		const authText = authLabel({ providers: deps.providers, status });
+		const bucket = modelBucket(status);
+		const singleTarget = list.length === 1;
+		if (candidates.length === 0) {
+			const fallbackModel = target.defaultModel?.trim() ?? "";
+			const resolution =
+				fallbackModel.length > 0
+					? resolveOverlayRuntimeTarget({
+							providers: deps.providers,
+							status,
+							wireModelId: fallbackModel,
+							requestedThinkingLevel: deps.settings.orchestrator?.thinkingLevel,
+						})
+					: null;
+			const rowCaps = resolution?.capabilities ?? status.capabilities;
+			const decisions = resolution?.capabilityDecisions ?? fallbackCapabilityDecisions(status, rowCaps);
+			const row: ModelRow = {
+				value: target.id,
+				target: target.id,
+				model: "",
+				runtimeName,
+				runtimeShortName,
+				runtimeId: status.runtime?.id ?? target.runtime,
+				apiFamily: status.runtime?.apiFamily ?? "unknown",
+				bucket,
+				source: "missing",
+				authText,
+				available: status.available,
+				reason: status.reason,
+				healthGlyph: healthGlyph(status),
+				healthText: healthText(status),
+				caps: rowCaps,
+				capabilityDecisions: decisions,
+				thinking: resolution?.thinking ?? "unresolved",
+				streaming: decisions.streaming,
+				diagnostics: resolution?.diagnostics ?? [
+					{ severity: "error", code: "model-not-configured", message: `target '${target.id}' has no model configured` },
+				],
+				badges: capabilityBadges(rowCaps),
+				context: contextDecisionLabel(decisions),
+				maxTokens: maxTokensDecisionLabel(decisions),
+				active: target.id === activeTarget,
+				scoped: scopeSet.has(target.id),
+				favorite: false,
+				recent: false,
+				defaultModel: false,
+				visibleByDefault: target.id === activeTarget || scopeSet.has(target.id),
+				selectable: false,
+			};
+			items.push({
+				value: target.id,
+				label: `${row.healthGlyph}  ${runtimeName}`,
+				description: `target=${target.id}  auth=${authText}${status.reason ? `  ${status.reason}` : ""}`,
+			});
+			refs.push({ target: target.id, model: target.defaultModel ?? "" });
+			rows.push(row);
+			continue;
+		}
+		for (const candidate of candidates) {
+			const wireModel = candidate.id;
+			const rowRef = `${target.id}/${wireModel}`;
+			const resolution = resolveOverlayRuntimeTarget({
+				providers: deps.providers,
+				status,
+				wireModelId: wireModel,
+				requestedThinkingLevel: deps.settings.orchestrator?.thinkingLevel,
+			});
+			const rowCaps = resolution.capabilities;
+			const decisions = resolution.capabilityDecisions;
+			const badges = capabilityBadges(rowCaps);
+			const exactScopeHit = scopeSet.has(rowRef);
+			const targetScopeHit = scopeSet.has(target.id);
+			const scopeHit = exactScopeHit || targetScopeHit;
+			const active = target.id === activeTarget && wireModel === activeModel;
+			const favorite = favoriteSet.has(rowRef) || exactScopeHit;
+			const recent = recentSet.has(rowRef);
+			const defaultModel = wireModel === target.defaultModel;
+			const targetScopedFocus = targetScopeHit && (active || defaultModel);
+			const focusPinned = singleTarget && candidate.source === "configured";
+			const row: ModelRow = {
+				value: rowRef,
+				target: target.id,
+				model: wireModel,
+				runtimeName,
+				runtimeShortName,
+				runtimeId: status.runtime?.id ?? target.runtime,
+				apiFamily: status.runtime?.apiFamily ?? "unknown",
+				bucket,
+				source: candidate.source,
+				...(candidate.loadState ? { loadState: candidate.loadState } : {}),
+				...(candidate.loadStateDetail ? { loadStateDetail: candidate.loadStateDetail } : {}),
+				authText,
+				available: status.available,
+				reason: status.reason,
+				healthGlyph: healthGlyph(status),
+				healthText: healthText(status),
+				caps: rowCaps,
+				capabilityDecisions: decisions,
+				thinking: resolution.thinking,
+				streaming: resolution.streaming,
+				diagnostics: resolution.diagnostics,
+				badges,
+				context: contextDecisionLabel(decisions),
+				maxTokens: maxTokensDecisionLabel(decisions),
+				active,
+				scoped: scopeHit,
+				favorite,
+				recent,
+				defaultModel,
+				focusPinned,
+				visibleByDefault: active || favorite || recent || defaultModel || targetScopedFocus || focusPinned,
+				// A model that cannot call tools stays listed so the operator can see it
+				// exists and why it is refused, but it cannot be chosen for the chat role.
+				selectable: supportsAgentRoleTools(decisions),
+			};
+			items.push({
+				value: rowRef,
+				label: `${row.healthGlyph}${favorite ? GLYPH.favorite : scopeHit ? GLYPH.scoped : active ? GLYPH.active : " "} ${wireModel}`,
+				description: `${row.context}  ${badges}  ${runtimeShortName}  target=${target.id}`,
+			});
+			refs.push({ target: target.id, model: wireModel });
+			rows.push(row);
+		}
+	}
+	return { items, refs, rows, summary: buildSummary(rows, list.length, activeRef) };
+}
+
+interface ModelColumns {
+	modelWidth: number;
+	targetWidth: number;
+	runtimeWidth: number;
+	showTarget: boolean;
+	showRuntime: boolean;
+}
+
+function modelColumns(width: number): ModelColumns {
+	const targetWidth = width >= 92 ? TARGET_COL_WIDTH_WIDE : TARGET_COL_WIDTH_NARROW;
+	const runtimeWidth =
+		width >= 96 ? RUNTIME_COL_WIDTH_WIDE : width >= 78 ? RUNTIME_COL_WIDTH_MEDIUM : RUNTIME_COL_WIDTH_NARROW;
+	let showTarget = width >= 58;
+	let showRuntime = width >= 68;
+	const calcModel = (): number => {
+		let fixed = SELECTED_PREFIX_WIDTH + CONTEXT_COL_WIDTH + 1 + CAPS_COL_WIDTH;
+		if (showTarget) fixed += 1 + targetWidth;
+		if (showRuntime) fixed += 1 + runtimeWidth;
+		return width - fixed;
+	};
+	let modelWidth = calcModel();
+	if (modelWidth < MODEL_MIN_WIDTH && showRuntime) {
+		showRuntime = false;
+		modelWidth = calcModel();
+	}
+	if (modelWidth < MODEL_MIN_WIDTH && showTarget) {
+		showTarget = false;
+		modelWidth = calcModel();
+	}
+	return {
+		modelWidth: Math.max(1, modelWidth),
+		targetWidth,
+		runtimeWidth,
+		showTarget,
+		showRuntime,
+	};
+}
+
+function fitCell(text: string, width: number, align: "left" | "right" = "left"): string {
+	const clipped = truncateToWidth(text, width, "", true);
+	const pad = " ".repeat(Math.max(0, width - visibleWidth(clipped)));
+	return align === "right" ? `${pad}${clipped}` : `${clipped}${pad}`;
+}
+
+function fitLine(text: string, width: number): string {
+	const clipped = truncateToWidth(text, width, "", true);
+	return `${clipped}${" ".repeat(Math.max(0, width - visibleWidth(clipped)))}`;
+}
+
+// The state mark to the left of a model id. The active model carries the accent
+// active mark; a scoped model the muted scoped mark; favorite, recent, and
+// default are quiet dim metadata; everything else is a dim placeholder dot.
+function activeMark(row: ModelRow): string {
+	const theme = clioTheme();
+	if (row.active) return theme.fg("accent", GLYPH.active);
+	if (row.favorite) return theme.fg("dim", GLYPH.favorite);
+	if (row.recent) return theme.fg("dim", "↺");
+	if (row.scoped) return theme.fg("muted", GLYPH.scoped);
+	if (row.defaultModel) return theme.fg("dim", "d");
+	return theme.fg("dim", "·");
+}
+
+function formatModelHeader(width: number): string {
+	const columns = modelColumns(width);
+	let line =
+		`${" ".repeat(SELECTED_PREFIX_WIDTH)}` +
+		`${fitCell("model", columns.modelWidth)}` +
+		`${fitCell("ctx", CONTEXT_COL_WIDTH, "right")} ` +
+		`${fitCell("caps", CAPS_COL_WIDTH)}`;
+	if (columns.showTarget) line += ` ${fitCell("target", columns.targetWidth)}`;
+	if (columns.showRuntime) line += ` ${fitCell("runtime", columns.runtimeWidth)}`;
+	// Table headers render dim per the design-system table recipe (section 4.6).
+	return clioTheme().fg("dim", fitLine(line, width));
+}
+
+function formatModelRow(row: ModelRow, width: number, selected: boolean): string {
+	const theme = clioTheme();
+	const columns = modelColumns(width);
+	// Selection points with the accent cursor and bolds the model id; the health
+	// glyph states the fact in its status token; the remaining cells stay muted.
+	// The whole line is never recolored, so a cell's own reset can never clip the
+	// selection highlight.
+	const pointer = selected ? theme.fg("accent", GLYPH.cursor) : " ";
+	const health = theme.fg(healthToken(row), row.healthGlyph);
+	const prefix = `${pointer} ${health} ${activeMark(row)} `;
+	const modelLabel = row.model.length > 0 ? row.model : "(no model ids)";
+	const modelCell = fitCell(truncateMiddle(modelLabel, columns.modelWidth), columns.modelWidth);
+	const model = selected ? theme.style("accent", modelCell, { bold: true }) : theme.fg("muted", modelCell);
+	let line =
+		prefix +
+		model +
+		`${theme.fg("muted", fitCell(row.context, CONTEXT_COL_WIDTH, "right"))} ` +
+		theme.fg("muted", fitCell(row.badges, CAPS_COL_WIDTH));
+	if (columns.showTarget) line += ` ${theme.fg("muted", fitCell(row.target, columns.targetWidth))}`;
+	if (columns.showRuntime) line += ` ${theme.fg("dim", fitCell(row.runtimeShortName, columns.runtimeWidth))}`;
+	return fitLine(line, width);
+}
+
+function capabilityNames(caps: CapabilityFlags): string {
+	const names: string[] = [];
+	if (caps.tools) names.push("tools");
+	if (caps.reasoning) names.push("reasoning");
+	if (caps.vision) names.push("vision");
+	if (caps.embeddings) names.push("embeddings");
+	if (caps.rerank) names.push("rerank");
+	if (caps.fim) names.push("fim");
+	return names.length > 0 ? names.join(", ") : "none";
+}
+
+function sourceLabel(source: ModelSource): string {
+	switch (source) {
+		case "configured":
+			return "configured";
+		case "live":
+			return "live probe";
+		case "catalog":
+			return "catalog";
+		case "default":
+			return "target default";
+		default:
+			return "no model ids";
+	}
+}
+
+function formatModelDetail(row: ModelRow, width: number): string[] {
+	const ref = row.model.length > 0 ? `${row.target}/${row.model}` : row.target;
+	const tags: string[] = [];
+	if (row.active) tags.push("current");
+	if (row.favorite) tags.push("favorite");
+	if (row.recent) tags.push("recent");
+	if (row.scoped) tags.push("scoped");
+	if (row.defaultModel) tags.push("default");
+	const state = tags.length > 0 ? tags.join("+") : row.selectable ? "candidate" : "not selectable";
+	const availability = row.available ? row.healthText : `${row.healthText}; ${row.reason || "unavailable"}`;
+	const loadState = row.loadState
+		? ` · state ${row.loadState}${row.loadStateDetail ? ` (${row.loadStateDetail})` : ""}`
+		: "";
+	const theme = clioTheme();
+	// The detail block is quiet scaffolding beneath the selected row; only the
+	// diagnostics carry a semantic token, so the two fact lines render dim.
+	return [
+		theme.fg("dim", fitLine(`${state} ${ref} · ${availability} · auth ${row.authText}`, width)),
+		theme.fg(
+			"dim",
+			fitLine(
+				`source ${sourceLabel(row.source)}${loadState} · ${row.runtimeName} · ${row.apiFamily} · max output ${row.maxTokens} · thinking ${row.thinking ?? "-"} · streaming ${row.streaming === false ? "no" : "yes"} · ${capabilityNames(row.caps)}`,
+				width,
+			),
+		),
+		...(row.diagnostics ?? [])
+			.filter((entry) => entry.severity !== "info")
+			.slice(0, 2)
+			.map((entry) => runtimeResolutionDiagnosticLine(entry, width)),
+	];
+}
+
+function matchesQuery(row: ModelRow, query: string): boolean {
+	const tokens = query
+		.toLowerCase()
+		.split(/\s+/)
+		.map((token) => token.trim())
+		.filter(Boolean);
+	if (tokens.length === 0) return true;
+	const haystack = [
+		row.target,
+		row.model,
+		row.runtimeName,
+		row.runtimeShortName,
+		row.runtimeId,
+		row.apiFamily,
+		row.bucket,
+		row.source,
+		row.loadState ?? "",
+		row.loadStateDetail ?? "",
+		row.badges,
+		row.context,
+		row.maxTokens,
+		row.authText,
+		row.healthText,
+	]
+		.join(" ")
+		.toLowerCase();
+	return tokens.every((token) => haystack.includes(token));
+}
+
+function visibleSlice<T>(
+	items: ReadonlyArray<T>,
+	selectedIndex: number,
+	maxVisible: number,
+): { start: number; rows: T[] } {
+	const start = Math.max(0, Math.min(selectedIndex - Math.floor(maxVisible / 2), items.length - maxVisible));
+	return { start, rows: items.slice(start, start + maxVisible) };
+}
+
+function refreshStatusLine(
+	refreshing: ModelRefreshScope | null | undefined,
+	error: RuntimeResolutionDiagnostic | null | undefined,
+): string | null {
+	if (refreshing)
+		return refreshing === "all" ? "refreshing all targets and model catalogs…" : "refreshing selected target models…";
+	return error ? formatRuntimeResolutionDiagnostic(error) : null;
+}
+
+function renderModelOverlayLines(input: {
+	rows: ReadonlyArray<ModelRow>;
+	summary: ModelOverlaySummary;
+	selectedIndex: number;
+	query: string;
+	width: number;
+	showAll?: boolean;
+	refreshing?: ModelRefreshScope | null;
+	refreshError?: RuntimeResolutionDiagnostic | null;
+	selectionError?: string | null;
+}): string[] {
+	const width = Math.max(1, input.width);
+	const query = input.query.trim();
+	const searching = query.length > 0;
+	const allMatches = input.rows.filter((row) => matchesQuery(row, input.query));
+	const focusedMatches = allMatches.filter((row) => row.visibleByDefault !== false);
+	const filtered = searching || input.showAll ? allMatches : focusedMatches;
+	const selectableFiltered = filtered.filter((row) => row.selectable).length;
+	const selectedIndex = Math.max(0, Math.min(input.selectedIndex, Math.max(0, filtered.length - 1)));
+	const selected = filtered[selectedIndex] ?? null;
+	const active = input.summary.activeRef || "not configured";
+	const modeLabel = searching ? `search "${query}"` : input.showAll ? "all" : "focus";
+	const theme = clioTheme();
+	// The mode/count summary and the focus legend are quiet scaffolding, so they
+	// render dim; only the table rows and status rails carry brighter tokens.
+	const lines = [
+		theme.fg(
+			"dim",
+			fitLine(
+				`${modeLabel} · ${selectableFiltered}/${input.summary.totalModels} models · ${input.summary.targets} targets · ${input.summary.localModels} local  ${input.summary.cloudModels} cloud`,
+				width,
+			),
+		),
+		theme.fg("dim", fitLine(`current ${active} · focus shows current, favorites, recent, and target defaults`, width)),
+	];
+	const refreshLine = refreshStatusLine(input.refreshing, input.refreshError);
+	if (refreshLine)
+		lines.push(
+			input.refreshError ? clioError(fitLine(refreshLine, width)) : theme.fg("dim", fitLine(refreshLine, width)),
+		);
+	if (input.selectionError) lines.push(clioError(fitLine(input.selectionError, width)));
+	lines.push(formatModelHeader(width));
+	if (filtered.length === 0) {
+		lines.push(
+			theme.fg(
+				"muted",
+				fitLine(
+					searching ? "  no models match the current filter" : "  no focused models; type to search or press Tab for all",
+					width,
+				),
+			),
+		);
+	} else {
+		const { start, rows } = visibleSlice(filtered, selectedIndex, VISIBLE_ROWS);
+		for (let i = 0; i < rows.length; i++) {
+			const row = rows[i];
+			if (!row) continue;
+			lines.push(formatModelRow(row, width, start + i === selectedIndex));
+		}
+		if (filtered.length > VISIBLE_ROWS) {
+			lines.push(theme.fg("dim", fitLine(`  (${selectedIndex + 1}/${filtered.length})`, width)));
+		}
+	}
+	lines.push("");
+	if (selected) lines.push(...formatModelDetail(selected, width));
+	else lines.push(theme.fg("muted", fitLine("no selected model", width)), "");
+	return lines.map((line) => fitLine(line, width));
+}
+
+interface ModelRefreshActions {
+	selected?: (targetId: string) => Promise<ModelItemsResult>;
+	all?: () => Promise<ModelItemsResult>;
+	requestRender?: () => void;
+}
+
+export class ModelOverlayView implements Component {
+	private selectedIndex = 0;
+	private query = "";
+	private showAll = false;
+	private rows: ModelRow[];
+	private summary: ModelOverlaySummary;
+	private refreshing: ModelRefreshScope | null = null;
+	private refreshError: RuntimeResolutionDiagnostic | null = null;
+	private selectionError: string | null = null;
+	private readonly lifecycle = new AbortController();
+
+	constructor(
+		rows: ReadonlyArray<ModelRow>,
+		summary: ModelOverlaySummary,
+		private readonly onSelect: (ref: ModelSelection) => void,
+		private readonly onToggleFavorite: ((ref: ModelSelection, favorite: boolean) => void) | undefined,
+		private readonly onClose: () => void,
+		private readonly refreshActions: ModelRefreshActions = {},
+	) {
+		this.rows = [...rows];
+		this.summary = summary;
+	}
+
+	selectedValue(): string | null {
+		return this.selectedRow()?.value ?? null;
+	}
+
+	setSelectedValue(value: string): void {
+		this.restoreSelection(value);
+	}
+
+	replaceItems(result: ModelItemsResult, preferredValue: string | null = this.selectedValue()): void {
+		if (this.lifecycle.signal.aborted) return;
+		this.rows = [...result.rows];
+		this.summary = result.summary;
+		this.selectionError = null;
+		this.restoreSelection(preferredValue);
+	}
+
+	dispose(): void {
+		if (!this.lifecycle.signal.aborted) this.lifecycle.abort();
+	}
+
+	isDisposed(): boolean {
+		return this.lifecycle.signal.aborted;
+	}
+
+	private restoreSelection(preferredValue: string | null): void {
+		const filtered = this.filteredRows();
+		if (preferredValue) {
+			const idx = filtered.findIndex((row) => row.value === preferredValue);
+			if (idx >= 0) {
+				this.selectedIndex = idx;
+				return;
+			}
+		}
+		this.selectedIndex = Math.max(0, Math.min(this.selectedIndex, Math.max(0, filtered.length - 1)));
+	}
+
+	private filteredRows(): ModelRow[] {
+		const matches = this.rows.filter((row) => matchesQuery(row, this.query));
+		if (this.query.trim().length > 0 || this.showAll) return matches;
+		return matches.filter((row) => row.visibleByDefault !== false);
+	}
+
+	private selectedRow(): ModelRow | null {
+		return this.filteredRows()[this.selectedIndex] ?? null;
+	}
+
+	private move(delta: number): void {
+		this.selectionError = null;
+		const count = this.filteredRows().length;
+		if (count === 0) {
+			this.selectedIndex = 0;
+			return;
+		}
+		this.selectedIndex = (this.selectedIndex + delta + count) % count;
+	}
+
+	private appendQuery(data: string): void {
+		this.selectionError = null;
+		this.query += data;
+		this.selectedIndex = 0;
+	}
+
+	private deleteQueryChar(): void {
+		if (this.query.length === 0) return;
+		this.selectionError = null;
+		this.query = this.query.slice(0, -1);
+		this.selectedIndex = 0;
+	}
+
+	private clearQuery(): void {
+		if (this.query.length === 0) return;
+		this.selectionError = null;
+		this.query = "";
+		this.selectedIndex = 0;
+	}
+
+	private toggleShowAll(): void {
+		this.selectionError = null;
+		this.showAll = !this.showAll;
+		this.selectedIndex = 0;
+	}
+
+	private toggleFavorite(): void {
+		const row = this.selectedRow();
+		if (!row?.selectable || !this.onToggleFavorite) return;
+		row.favorite = !row.favorite;
+		row.visibleByDefault =
+			row.focusPinned === true ||
+			row.active ||
+			row.favorite === true ||
+			row.recent === true ||
+			row.scoped === true ||
+			row.defaultModel === true;
+		this.onToggleFavorite({ target: row.target, model: row.model }, row.favorite === true);
+	}
+
+	refresh(scope: ModelRefreshScope): void {
+		void this.runRefresh(scope);
+	}
+
+	private async runRefresh(scope: ModelRefreshScope): Promise<void> {
+		if (this.refreshing || this.lifecycle.signal.aborted) return;
+		const signal = this.lifecycle.signal;
+		const selected = this.selectedRow();
+		const preferredValue = selected?.value ?? null;
+		if (scope === "all" && !this.refreshActions.all) return;
+		if (scope === "selected" && (!this.refreshActions.selected || !selected?.target)) return;
+		this.refreshing = scope;
+		this.refreshError = null;
+		this.selectionError = null;
+		this.refreshActions.requestRender?.();
+		try {
+			const next =
+				scope === "all" ? await this.refreshActions.all?.() : await this.refreshActions.selected?.(selected?.target ?? "");
+			if (signal.aborted) return;
+			if (next) this.replaceItems(next, preferredValue);
+		} catch (err) {
+			if (signal.aborted) return;
+			this.refreshError = {
+				severity: "error",
+				code: "probe-failed",
+				message: err instanceof Error ? err.message : String(err),
+			};
+		} finally {
+			this.refreshing = null;
+			if (!signal.aborted) this.refreshActions.requestRender?.();
+		}
+	}
+
+	render(width: number): string[] {
+		return renderModelOverlayLines({
+			rows: this.rows,
+			summary: this.summary,
+			selectedIndex: this.selectedIndex,
+			query: this.query,
+			width,
+			showAll: this.showAll,
+			refreshing: this.refreshing,
+			refreshError: this.refreshError,
+			selectionError: this.selectionError,
+		});
+	}
+
+	invalidate(): void {}
+
+	handleInput(data: string): void {
+		if (this.lifecycle.signal.aborted) return;
+		const kb = getKeybindings();
+		if (kb.matches(data, "tui.select.up")) {
+			this.move(-1);
+			return;
+		}
+		if (kb.matches(data, "tui.select.down")) {
+			this.move(1);
+			return;
+		}
+		if (kb.matches(data, "tui.select.confirm") || matchesKey(data, "enter") || data === "\n") {
+			const row = this.selectedRow();
+			if (row?.selectable) {
+				this.onSelect({ target: row.target, model: row.model });
+				this.onClose();
+				return;
+			}
+			this.selectionError = row
+				? row.model && row.capabilityDecisions && !supportsAgentRoleTools(row.capabilityDecisions)
+					? `${row.model} ${AGENT_ROLE_TOOLS_REQUIRED_REASON}`
+					: `target ${row.target} has no selectable model id`
+				: "no model is selected";
+			this.refreshActions.requestRender?.();
+			return;
+		}
+		if (kb.matches(data, "tui.select.cancel")) {
+			// Esc unwinds one step at a time: an active filter is the thing the
+			// user most recently built, so it goes first and the overlay stays
+			// open. A second press with no filter left closes. Typing a filter
+			// and reaching for Esc used to dump the whole overlay.
+			if (this.query.length > 0) {
+				this.clearQuery();
+				this.refreshActions.requestRender?.();
+				return;
+			}
+			this.onClose();
+			return;
+		}
+		if (data === BACKSPACE || data === BACKSPACE_ALT) {
+			this.deleteQueryChar();
+			return;
+		}
+		if (data === CTRL_U) {
+			this.clearQuery();
+			return;
+		}
+		if (data === TAB) {
+			this.toggleShowAll();
+			return;
+		}
+		if (data === "r" && this.query.length === 0) {
+			this.refresh("selected");
+			return;
+		}
+		if (data === "R" && this.query.length === 0) {
+			this.refresh("all");
+			return;
+		}
+		if (data === "*" && this.query.length === 0) {
+			this.toggleFavorite();
+			return;
+		}
+		if (data.length === 1 && data >= " " && data !== "\x7f") this.appendQuery(data);
+	}
+}
+
+function reloadKnowledgeBaseIfSupported(providers: ProvidersContract): void {
+	const knowledgeBase = providers.knowledgeBase;
+	const reload = (knowledgeBase as { reload?: unknown } | null)?.reload;
+	if (typeof reload === "function") reload.call(knowledgeBase);
+}
+
+export function openModelOverlay(tui: TUI, deps: OpenModelOverlayDeps): OverlayHandle {
+	const currentSettings = (): Readonly<ClioSettings> => deps.getSettings?.() ?? deps.settings;
+	const build = (options?: { reloadCatalog?: boolean }): ModelItemsResult => {
+		if (options?.reloadCatalog) reloadKnowledgeBaseIfSupported(deps.providers);
+		return buildModelItems({ settings: currentSettings(), providers: deps.providers });
+	};
+	const initial = build();
+	const overlayWidth = resolveOverlayWidth(tui.terminal?.columns ?? 0);
+	const activeTarget = currentSettings().orchestrator?.target?.trim();
+	const activeModel = currentSettings().orchestrator?.model?.trim();
+	const view = new ModelOverlayView(
+		initial.rows,
+		initial.summary,
+		(ref) => deps.onSelect(ref),
+		deps.onToggleFavorite ? (ref, favorite) => deps.onToggleFavorite?.(ref, favorite) : undefined,
+		() => deps.onClose(),
+		{
+			selected: async (targetId) => {
+				await deps.providers.probeTarget(targetId);
+				return build({ reloadCatalog: true });
+			},
+			all: async () => {
+				await deps.providers.probeAllLive();
+				return build({ reloadCatalog: true });
+			},
+			requestRender: () => tui.requestRender(),
+		},
+	);
+	if (activeTarget && activeModel) view.setSelectedValue(`${activeTarget}/${activeModel}`);
+	const unsubscribeHealth = deps.bus?.on(BusChannels.ProviderHealth, () => {
+		if (view.isDisposed()) return;
+		view.replaceItems(build());
+		tui.requestRender();
+	});
+	const handle = showClioOverlayFrame(tui, view, {
+		anchor: "center",
+		width: overlayWidth,
+		title: "Models",
+		footerHint: buildHint([
+			FILTER_HINT,
+			{ key: "Tab", verb: "focus/all" },
+			{ key: "r", verb: "refresh target" },
+			{ key: "R", verb: "refresh all" },
+			{ key: "*", verb: "fav" },
+			{ key: "Enter", verb: "use" },
+		]),
+	});
+	if (deps.autoRefresh !== false) {
+		view.refresh("all");
+	}
+	return {
+		...handle,
+		hide(): void {
+			view.dispose();
+			unsubscribeHealth?.();
+			handle.hide();
+		},
+	};
+}