@f5-sales-demo/xcsh 19.51.2

package/src/config/auto-config.ts

@@ -0,0 +1,698 @@
+/**
+ * Auto-configuration and self-healing for LiteLLM proxy.
+ *
+ * Runs on every startup to ensure xcsh has a working configuration:
+ *
+ * 1. Missing config → auto-generate from LITELLM env vars
+ * 2. Corrupt config → backup and regenerate
+ * 3. Empty config → regenerate
+ * 4. Drifted config → detect and auto-fix (URL changed in env)
+ * 5. Incomplete config → fill missing fields
+ * 6. Outdated config → detect missing/old configVersion, backup and regenerate
+ *
+ * All fixes create .bak backups before overwriting.
+ * All operations are idempotent and safe to run repeatedly.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { $env, logger, readProviderFromModelsYml } from "@f5xc-salesdemos/pi-utils";
+
+/** Current config schema version. Bump when the generated format changes. */
+export const CURRENT_CONFIG_VERSION = 2;
+
+// ---------------------------------------------------------------------------
+// Detection
+// ---------------------------------------------------------------------------
+
+/** Check if LiteLLM env vars are set and usable. */
+export function hasLiteLLMEnv(): boolean {
+	const baseUrl = $env.LITELLM_BASE_URL?.trim();
+	const apiKey = $env.LITELLM_API_KEY?.trim();
+	return !!baseUrl && !!apiKey && (baseUrl.startsWith("http://") || baseUrl.startsWith("https://"));
+}
+
+/** Get the LiteLLM base URL from env, normalized (no trailing slash). */
+function getLiteLLMBaseUrl(): string | undefined {
+	const raw = $env.LITELLM_BASE_URL?.trim();
+	if (!raw) return undefined;
+	return raw.replace(/\/+$/, "");
+}
+
+// ---------------------------------------------------------------------------
+// Generation
+// ---------------------------------------------------------------------------
+
+export interface GenerateModelsYmlOptions {
+	/** API base path for the litellm provider (e.g. "/v1" or "/api/v1"). Defaults to "/v1". */
+	apiBasePath?: string;
+	/** When provided, write this literal API key value instead of the LITELLM_API_KEY env var reference. */
+	apiKeyLiteral?: string;
+}
+
+/** Generate models.yml content for LiteLLM proxy. */
+export function generateModelsYml(baseUrl: string, options?: GenerateModelsYmlOptions): string {
+	const apiBase = options?.apiBasePath ?? "/v1";
+	// When a literal API key is provided, double-quote it to handle YAML-significant
+	// characters (: ! # { } [ ] ' " etc.). Escape backslashes and double quotes first.
+	const apiKeyValue = options?.apiKeyLiteral
+		? `"${options.apiKeyLiteral.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`
+		: "LITELLM_API_KEY";
+	const keyComment = options?.apiKeyLiteral
+		? "# API key stored as literal value"
+		: "# API key resolved from LITELLM_API_KEY env var at runtime";
+	const lines = [
+		"# Auto-generated by xcsh for LiteLLM proxy",
+		keyComment,
+		`configVersion: ${CURRENT_CONFIG_VERSION}`,
+		"providers:",
+		"  anthropic:",
+		`    baseUrl: "${baseUrl}/anthropic"`,
+		`    apiKey: ${apiKeyValue}`,
+		"  litellm:",
+		`    baseUrl: "${baseUrl}${apiBase}"`,
+		`    apiKey: ${apiKeyValue}`,
+		"    api: openai-completions",
+		"    discovery:",
+		"      type: openai-compat",
+	];
+
+	lines.push("");
+	return lines.join("\n");
+}
+
+export interface LiteLLMConfig {
+	baseUrl: string;
+	apiKey: string;
+}
+
+/**
+ * Read existing models.yml and extract the anthropic provider's base URL and API key.
+ *
+ * - baseUrl: strips `/anthropic` suffix to recover the root proxy URL
+ * - apiKey: env var name → process.env lookup; shell-backed → fall back to env;
+ *   otherwise literal
+ * - Falls back to getLiteLLMBaseUrl() and $env.LITELLM_API_KEY when the file is
+ *   missing or the anthropic block is incomplete
+ */
+export function readLiteLLMConfig(modelsPath: string): LiteLLMConfig | undefined {
+	if (!fs.existsSync(modelsPath)) return undefined;
+
+	const block = readProviderFromModelsYml("anthropic", modelsPath);
+
+	const resolvedBaseUrl = block?.baseUrl ? block.baseUrl.replace(/\/anthropic\/?$/, "") : getLiteLLMBaseUrl();
+
+	let resolvedApiKey: string | undefined;
+	const apiKey = block?.apiKey;
+	if (!apiKey) {
+		resolvedApiKey = $env.LITELLM_API_KEY;
+	} else if (apiKey.kind === "envVar") {
+		resolvedApiKey = process.env[apiKey.name] ?? $env.LITELLM_API_KEY;
+	} else if (apiKey.kind === "shellSecret") {
+		resolvedApiKey = $env.LITELLM_API_KEY;
+	} else {
+		resolvedApiKey = apiKey.value;
+	}
+
+	if (!resolvedBaseUrl || !resolvedApiKey) return undefined;
+
+	return { baseUrl: resolvedBaseUrl, apiKey: resolvedApiKey };
+}
+
+/** Generate config.yml with sensible defaults for LiteLLM. */
+export function generateConfigYml(): string {
+	return [
+		"# Auto-generated by xcsh for LiteLLM proxy",
+		"modelRoles:",
+		"  default: anthropic/claude-opus-4-6",
+		"",
+		"providers:",
+		"  image: openai",
+		"  webSearch: anthropic",
+		"",
+		"generate_image:",
+		"  enabled: true",
+		"",
+		"inspect_image:",
+		"  enabled: true",
+		"",
+		"images:",
+		"  blockImages: false",
+		"  autoResize: true",
+		"",
+		"terminal:",
+		"  showImages: true",
+		"",
+	].join("\n");
+}
+
+/**
+ * Ensure config.yml has a modelRoles.default entry.
+ * Existing configs from earlier versions may be missing this, causing xcsh
+ * to fall through to the "first available model" fallback which picks stale
+ * cached models that the proxy can't serve.
+ */
+export function healConfigYmlModelRoles(configPath: string): void {
+	try {
+		const content = fs.readFileSync(configPath, "utf-8");
+		if (content.includes("modelRoles:")) return; // Already has modelRoles
+		// Prepend modelRoles section
+		const healed = `modelRoles:\n  default: anthropic/claude-opus-4-6\n\n${content}`;
+		fs.writeFileSync(configPath, healed);
+		logger.debug("Healed config.yml: added default modelRoles", { configPath });
+	} catch {
+		// Best-effort — don't block startup
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Backup
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract a double-quoted literal API key from an existing models.yml file.
+ * Checks the anthropic and litellm provider blocks; returns undefined if
+ * neither has a literal (e.g., both use env var references) or the file is
+ * missing.
+ */
+export function readApiKeyLiteral(modelsPath: string): string | undefined {
+	for (const name of ["anthropic", "litellm"]) {
+		const block = readProviderFromModelsYml(name, modelsPath);
+		if (block?.apiKey?.kind === "literal" && block.apiKey.wasQuoted) {
+			return block.apiKey.value;
+		}
+	}
+	return undefined;
+}
+
+/** Create a .bak backup of a file if it exists. Returns true if backed up. */
+function backupIfExists(filePath: string): boolean {
+	try {
+		if (fs.existsSync(filePath)) {
+			fs.copyFileSync(filePath, `${filePath}.bak`);
+			return true;
+		}
+	} catch (err) {
+		logger.warn("Failed to create backup", { filePath, err });
+	}
+	return false;
+}
+
+/** Safely write a file, creating parent directories. */
+function safeWrite(filePath: string, content: string): boolean {
+	try {
+		fs.mkdirSync(path.dirname(filePath), { recursive: true });
+		fs.writeFileSync(filePath, content, "utf-8");
+		return true;
+	} catch (err) {
+		logger.warn("Failed to write config file", { filePath, err });
+		return false;
+	}
+}
+
+/** Remove the model cache database so discovery re-runs fresh. */
+function clearModelCache(modelsPath: string): void {
+	const cacheDbPath = path.join(path.dirname(modelsPath), "models.db");
+	try {
+		if (fs.existsSync(cacheDbPath)) {
+			fs.unlinkSync(cacheDbPath);
+			logger.debug("Cleared stale model cache", { cacheDbPath });
+		}
+		// Also remove WAL/SHM files if present
+		for (const suffix of ["-wal", "-shm"]) {
+			const walPath = `${cacheDbPath}${suffix}`;
+			if (fs.existsSync(walPath)) {
+				fs.unlinkSync(walPath);
+			}
+		}
+	} catch {
+		// Best-effort — don't block config repair
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Proxy connection probing
+// ---------------------------------------------------------------------------
+
+export interface ProbeResult {
+	reachable: boolean;
+	models: string[];
+	error?: string;
+	/** The API base path that worked (e.g. "/v1" or "/api/v1"). */
+	apiBasePath?: string;
+}
+
+/** Candidate paths to probe for the models endpoint (tried in order). */
+const MODELS_ENDPOINT_PATHS = ["/v1/models", "/api/v1/models"];
+
+/**
+ * Probe a LiteLLM proxy to validate connectivity and discover available models.
+ *
+ * Tries multiple endpoint paths in order (/v1/models, then /api/v1/models) to
+ * handle deployments where a frontend like Open WebUI intercepts /v1/*.
+ *
+ * Returns the list of model IDs on success, or an error on failure.
+ * Uses a 3-second timeout per endpoint to avoid blocking startup.
+ */
+export async function probeLiteLLMConnection(
+	baseUrl: string,
+	apiKey: string,
+	options?: { signal?: AbortSignal; fetch?: typeof globalThis.fetch },
+): Promise<ProbeResult> {
+	const fetchImpl = options?.fetch ?? globalThis.fetch;
+	const normalizedUrl = baseUrl.replace(/\/+$/, "");
+	let lastError = "";
+
+	for (const endpointPath of MODELS_ENDPOINT_PATHS) {
+		const url = `${normalizedUrl}${endpointPath}`;
+		let response: Response;
+		try {
+			response = await fetchImpl(url, {
+				method: "GET",
+				headers: {
+					Accept: "application/json",
+					Authorization: `Bearer ${apiKey}`,
+				},
+				signal: options?.signal ?? AbortSignal.timeout(3000),
+			});
+		} catch (err) {
+			lastError = err instanceof Error ? err.message : String(err);
+			continue;
+		}
+
+		if (!response.ok) {
+			lastError = `HTTP ${response.status} ${response.statusText} from ${url}`;
+			continue;
+		}
+
+		let payload: unknown;
+		try {
+			payload = await response.json();
+		} catch {
+			lastError = `Non-JSON response from ${url}`;
+			continue;
+		}
+
+		// OpenAI-compatible /v1/models returns { data: [{ id: "model-name", ... }] }
+		const models: string[] = [];
+		if (
+			payload &&
+			typeof payload === "object" &&
+			"data" in payload &&
+			Array.isArray((payload as { data: unknown }).data)
+		) {
+			for (const entry of (payload as { data: Array<{ id?: string }> }).data) {
+				if (typeof entry.id === "string" && entry.id.length > 0) {
+					models.push(entry.id);
+				}
+			}
+		}
+
+		if (models.length > 0) {
+			// Derive the API base path from the endpoint that worked
+			const apiBasePath = endpointPath.replace(/\/models$/, "");
+			return { reachable: true, models, apiBasePath };
+		}
+
+		lastError = `No models in response from ${url}`;
+	}
+
+	return { reachable: false, models: [], error: lastError };
+}
+
+// ---------------------------------------------------------------------------
+// Auto-config on startup (handles missing file)
+// ---------------------------------------------------------------------------
+
+/**
+ * Try to auto-generate models.yml and config.yml for LiteLLM.
+ * Called when models.yml is not found and LITELLM env vars are set.
+ * Returns true if config was generated.
+ */
+export function tryAutoConfigLiteLLM(modelsPath: string): boolean {
+	if (!hasLiteLLMEnv()) return false;
+
+	const baseUrl = getLiteLLMBaseUrl();
+	if (!baseUrl) return false;
+
+	if (!safeWrite(modelsPath, generateModelsYml(baseUrl))) return false;
+	logger.debug("Auto-configured LiteLLM proxy", { modelsPath, baseUrl });
+
+	// Write config.yml if it doesn't exist, or heal it if it's missing modelRoles
+	const configPath = path.join(path.dirname(modelsPath), "config.yml");
+	if (!fs.existsSync(configPath)) {
+		safeWrite(configPath, generateConfigYml());
+		logger.debug("Auto-generated default config", { configPath });
+	} else {
+		healConfigYmlModelRoles(configPath);
+	}
+
+	return true;
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+export interface ValidationResult {
+	valid: boolean;
+	errors: string[];
+	warnings: string[];
+	fixable: boolean;
+}
+
+/**
+ * Validate existing models.yml against environment.
+ *
+ * Checks:
+ * - File exists and is readable
+ * - File is not empty or whitespace-only
+ * - Contains expected providers section
+ * - configVersion matches CURRENT_CONFIG_VERSION
+ * - Anthropic baseUrl matches LITELLM_BASE_URL env var
+ * - apiKey env var reference resolves to a set variable
+ */
+export function validateModelsConfig(modelsPath: string): ValidationResult {
+	const result: ValidationResult = { valid: true, errors: [], warnings: [], fixable: false };
+
+	// Check file exists
+	if (!fs.existsSync(modelsPath)) {
+		result.valid = false;
+		result.errors.push("models.yml not found");
+		result.fixable = hasLiteLLMEnv();
+		return result;
+	}
+
+	// Check file is readable
+	let content: string;
+	try {
+		content = fs.readFileSync(modelsPath, "utf-8");
+	} catch {
+		result.valid = false;
+		result.errors.push("models.yml is not readable");
+		return result;
+	}
+
+	// Check not empty
+	if (content.trim().length === 0) {
+		result.valid = false;
+		result.errors.push("models.yml is empty");
+		result.fixable = hasLiteLLMEnv();
+		return result;
+	}
+
+	// Check for providers section (basic structural check)
+	if (!content.includes("providers:")) {
+		result.valid = false;
+		result.errors.push("models.yml missing 'providers:' section");
+		result.fixable = hasLiteLLMEnv();
+		return result;
+	}
+
+	// Check config version
+	if (!content.includes(`configVersion: ${CURRENT_CONFIG_VERSION}`)) {
+		result.warnings.push(
+			`models.yml missing or outdated configVersion (expected ${CURRENT_CONFIG_VERSION}). Run 'xcsh setup litellm' to upgrade.`,
+		);
+		result.fixable = true;
+	}
+
+	// Check env var alignment
+	const envBaseUrl = getLiteLLMBaseUrl();
+	if (envBaseUrl) {
+		const expectedAnthropicUrl = `${envBaseUrl}/anthropic`;
+		if (!content.includes(expectedAnthropicUrl)) {
+			result.warnings.push(
+				`Anthropic baseUrl in models.yml does not match LITELLM_BASE_URL. Expected: ${expectedAnthropicUrl}`,
+			);
+			result.fixable = true;
+		}
+	}
+
+	// Check apiKey references a set env var
+	if (content.includes("apiKey: LITELLM_API_KEY") && !$env.LITELLM_API_KEY) {
+		result.warnings.push("models.yml references LITELLM_API_KEY but the env var is not set");
+	}
+
+	return result;
+}
+
+// ---------------------------------------------------------------------------
+// Auto-fix (handles corrupt, drifted, incomplete configs)
+// ---------------------------------------------------------------------------
+
+export interface FixResult {
+	fixed: boolean;
+	changes: string[];
+}
+
+/**
+ * Auto-fix models.yml issues.
+ *
+ * Handles:
+ * - Corrupt YAML → backup and regenerate
+ * - Empty file → regenerate
+ * - URL drift → backup and regenerate with new URL
+ * - Missing providers section → regenerate
+ *
+ * Always creates .bak backup before overwriting.
+ */
+export function autoFixModelsConfig(modelsPath: string): FixResult {
+	if (!hasLiteLLMEnv()) {
+		return { fixed: false, changes: ["Cannot fix: LITELLM_BASE_URL or LITELLM_API_KEY not set"] };
+	}
+
+	const baseUrl = getLiteLLMBaseUrl();
+	if (!baseUrl) {
+		return { fixed: false, changes: ["Cannot fix: LITELLM_BASE_URL is invalid"] };
+	}
+
+	const existingLiteralKey = readApiKeyLiteral(modelsPath);
+
+	backupIfExists(modelsPath);
+
+	if (
+		!safeWrite(
+			modelsPath,
+			generateModelsYml(baseUrl, {
+				...(existingLiteralKey ? { apiKeyLiteral: existingLiteralKey } : {}),
+			}),
+		)
+	) {
+		return { fixed: false, changes: [`Write failed: could not write to ${modelsPath}`] };
+	}
+
+	// Clear stale model cache so discovery re-runs with the new config
+	clearModelCache(modelsPath);
+
+	logger.debug("Auto-fixed LiteLLM config", { modelsPath, baseUrl });
+	return { fixed: true, changes: [`Regenerated models.yml with baseUrl: ${baseUrl}/anthropic`] };
+}
+
+// ---------------------------------------------------------------------------
+// Startup self-healing (called from ModelRegistry on every load)
+// ---------------------------------------------------------------------------
+
+/**
+ * Comprehensive startup health check for models.yml.
+ *
+ * Called from ModelRegistry.#loadCustomModels() on every startup.
+ * Handles all error conditions:
+ *
+ * - "not-found" → tryAutoConfigLiteLLM (generate from env)
+ * - "error" (corrupt/invalid) → autoFixModelsConfig (backup + regenerate)
+ * - "ok" but drifted → autoFixModelsConfig (backup + update URL)
+ * - "ok" but outdated configVersion → autoFixModelsConfig (backup + upgrade)
+ *
+ * Returns true if any repair was performed (caller should invalidate cache and reload).
+ */
+export function startupHealthCheck(
+	status: "ok" | "not-found" | "error",
+	modelsPath: string,
+	loadedProviders?: Record<string, { baseUrl?: string }>,
+): boolean {
+	// Case 1: No config file — generate from env
+	if (status === "not-found") {
+		return tryAutoConfigLiteLLM(modelsPath);
+	}
+
+	// Case 2: Config file exists but failed to parse — backup and regenerate
+	if (status === "error") {
+		if (!hasLiteLLMEnv()) return false;
+		const fix = autoFixModelsConfig(modelsPath);
+		return fix.fixed;
+	}
+
+	// Case 3: Config loaded OK — check for drift and auto-fix
+	if (status === "ok" && loadedProviders) {
+		const envBaseUrl = getLiteLLMBaseUrl();
+		if (!envBaseUrl) return false;
+
+		const anthropicConfig = loadedProviders.anthropic;
+		if (!anthropicConfig?.baseUrl) return false;
+
+		const expectedUrl = `${envBaseUrl}/anthropic`;
+		if (anthropicConfig.baseUrl !== expectedUrl) {
+			// Only auto-fix configs that were generated by xcsh. User-written configs
+			// with a custom proxy URL must never be silently overwritten.
+			// Recognize both env-var-ref configs and literal-key configs as auto-generated.
+			let isAutoGenerated = false;
+			try {
+				const content = fs.readFileSync(modelsPath, "utf-8");
+				isAutoGenerated = content.includes("Auto-generated by xcsh") || content.includes("apiKey: LITELLM_API_KEY");
+			} catch {
+				// File unreadable — skip, don't block startup
+			}
+			if (!isAutoGenerated) return false;
+
+			logger.warn("LiteLLM config drift detected — auto-fixing", {
+				configured: anthropicConfig.baseUrl,
+				expected: expectedUrl,
+			});
+			const fix = autoFixModelsConfig(modelsPath);
+			return fix.fixed;
+		}
+
+		// Case 4: Config OK and URL matches — check for structural issues
+		try {
+			const content = fs.readFileSync(modelsPath, "utf-8");
+
+			// 4a: configVersion is missing or outdated
+			if (!content.includes(`configVersion: ${CURRENT_CONFIG_VERSION}`)) {
+				logger.debug("Upgrading models.yml to configVersion", { version: CURRENT_CONFIG_VERSION });
+				const fix = autoFixModelsConfig(modelsPath);
+				return fix.fixed;
+			}
+
+			// 4b: litellm discovery provider is missing (legacy v1-style config)
+			if (!content.includes("type: openai-compat")) {
+				logger.debug("Adding litellm discovery provider to models.yml");
+				const fix = autoFixModelsConfig(modelsPath);
+				return fix.fixed;
+			}
+		} catch {
+			// File read failed — skip structural checks, don't block startup
+		}
+	}
+
+	// Always heal config.yml model roles (regardless of models.yml state)
+	if (hasLiteLLMEnv()) {
+		const configPath = path.join(path.dirname(modelsPath), "config.yml");
+		if (fs.existsSync(configPath)) {
+			healConfigYmlModelRoles(configPath);
+		}
+	}
+
+	return false;
+}
+
+// ---------------------------------------------------------------------------
+// Async probe-and-upgrade (called from ModelRegistry.refresh on first run)
+// ---------------------------------------------------------------------------
+
+/**
+ * Probe the LiteLLM proxy and upgrade config with the correct API base path.
+ *
+ * This is an async operation that runs during the first ModelRegistry.refresh().
+ * It validates proxy connectivity and, if successful, ensures the config uses
+ * the correct API base path (e.g. /api/v1 for Open WebUI deployments).
+ *
+ * Returns true if the config was upgraded (caller should reload).
+ */
+export async function probeAndUpgradeLiteLLMConfig(
+	modelsPath: string,
+	options?: { fetch?: typeof globalThis.fetch },
+): Promise<boolean> {
+	// Try env vars first; fall back to literal key stored in the config
+	let baseUrl = getLiteLLMBaseUrl();
+	let apiKey = $env.LITELLM_API_KEY?.trim();
+
+	if (!baseUrl || !apiKey) {
+		const existing = readLiteLLMConfig(modelsPath);
+		if (existing) {
+			baseUrl = baseUrl || existing.baseUrl;
+			apiKey = apiKey || existing.apiKey;
+		}
+	}
+
+	if (!baseUrl || !apiKey) return false;
+
+	let content: string;
+	try {
+		content = fs.readFileSync(modelsPath, "utf-8");
+	} catch {
+		// File doesn't exist or is unreadable — nothing to upgrade
+		return false;
+	}
+
+	// Only upgrade configs that were auto-generated by xcsh. User-written configs
+	// with custom proxy URLs must never be silently overwritten by LiteLLM probing.
+	// Recognize both env-var-ref configs and literal-key configs as auto-generated.
+	if (!content.includes("Auto-generated by xcsh") && !content.includes("apiKey: LITELLM_API_KEY")) {
+		return false;
+	}
+
+	// Probe the proxy to find the working API base path
+	const probe = await probeLiteLLMConnection(baseUrl, apiKey, { fetch: options?.fetch });
+	if (!probe.reachable) {
+		logger.warn("LiteLLM proxy unreachable during upgrade probe — keeping existing config", {
+			baseUrl,
+			error: probe.error,
+		});
+		return false;
+	}
+
+	if (probe.models.length === 0) {
+		logger.warn("LiteLLM proxy returned no models — keeping existing config", { baseUrl });
+		return false;
+	}
+
+	// Check if the config already has the correct discovery base path
+	const hasDiscovery = content.includes("type: openai-compat");
+	const correctBase = `${baseUrl}${probe.apiBasePath}`;
+	if (hasDiscovery && content.includes(correctBase)) {
+		return false; // Already correct
+	}
+
+	// Upgrade: backup and regenerate with correct base path, preserving literal keys
+	const existingLiteralKey = readApiKeyLiteral(modelsPath);
+	backupIfExists(modelsPath);
+	const newContent = generateModelsYml(baseUrl, {
+		apiBasePath: probe.apiBasePath,
+		...(existingLiteralKey ? { apiKeyLiteral: existingLiteralKey } : {}),
+	});
+	if (!safeWrite(modelsPath, newContent)) {
+		return false;
+	}
+
+	logger.debug("Upgraded LiteLLM config", {
+		modelsPath,
+		baseUrl,
+		apiBasePath: probe.apiBasePath,
+		models: probe.models.length,
+		hadDiscovery: hasDiscovery,
+	});
+	return true;
+}
+
+/**
+ * Validate config against env and warn if drifted.
+ * Informational only — does not fix. Use startupHealthCheck for auto-fix.
+ */
+export function warnIfConfigDrifted(providers: Record<string, { baseUrl?: string }> | undefined): void {
+	if (!providers) return;
+
+	const envBaseUrl = getLiteLLMBaseUrl();
+	if (!envBaseUrl) return;
+
+	const anthropicConfig = providers.anthropic;
+	if (!anthropicConfig?.baseUrl) return;
+
+	const expectedUrl = `${envBaseUrl}/anthropic`;
+	if (anthropicConfig.baseUrl !== expectedUrl) {
+		logger.warn("LiteLLM config drift detected", {
+			configured: anthropicConfig.baseUrl,
+			expected: expectedUrl,
+			hint: "Run 'xcsh setup litellm' to update",
+		});
+	}
+}