@f5xc-salesdemos/xcsh 15.5.0 → 15.6.2

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "15.5.0",
+	"version": "15.6.2",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -46,12 +46,12 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5xc-salesdemos/xcsh-stats": "15.5.0",
-		"@f5xc-salesdemos/pi-agent-core": "15.5.0",
-		"@f5xc-salesdemos/pi-ai": "15.5.0",
-		"@f5xc-salesdemos/pi-natives": "15.5.0",
-		"@f5xc-salesdemos/pi-tui": "15.5.0",
-		"@f5xc-salesdemos/pi-utils": "15.5.0",
+		"@f5xc-salesdemos/xcsh-stats": "15.6.2",
+		"@f5xc-salesdemos/pi-agent-core": "15.6.2",
+		"@f5xc-salesdemos/pi-ai": "15.6.2",
+		"@f5xc-salesdemos/pi-natives": "15.6.2",
+		"@f5xc-salesdemos/pi-tui": "15.6.2",
+		"@f5xc-salesdemos/pi-utils": "15.6.2",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/src/config/auto-config.ts

@@ -43,12 +43,13 @@ function getLiteLLMBaseUrl(): string | undefined {
 // ---------------------------------------------------------------------------
 
 export interface GenerateModelsYmlOptions {
-	/** Model IDs discovered from the proxy's /v1/models endpoint. */
-	discoveredModels?: string[];
+	/** API base path for the litellm provider (e.g. "/v1" or "/api/v1"). Defaults to "/v1". */
+	apiBasePath?: string;
 }
 
 /** Generate models.yml content for LiteLLM proxy. */
 export function generateModelsYml(baseUrl: string, options?: GenerateModelsYmlOptions): string {
+	const apiBase = options?.apiBasePath ?? "/v1";
 	const lines = [
 		"# Auto-generated by xcsh for LiteLLM proxy",
 		"# API key resolved from LITELLM_API_KEY env var at runtime",
@@ -57,22 +58,14 @@ export function generateModelsYml(baseUrl: string, options?: GenerateModelsYmlOp
 		"  anthropic:",
 		`    baseUrl: "${baseUrl}/anthropic"`,
 		"    apiKey: LITELLM_API_KEY",
+		"  litellm:",
+		`    baseUrl: "${baseUrl}${apiBase}"`,
+		"    apiKey: LITELLM_API_KEY",
+		"    api: openai-completions",
+		"    discovery:",
+		"      type: openai-compat",
 	];
 
-	// When the proxy has been probed and models discovered, add a litellm provider
-	// with openai-compat discovery so the model registry fetches real model catalog
-	const discovered = options?.discoveredModels;
-	if (discovered && discovered.length > 0) {
-		lines.push(
-			"  litellm:",
-			`    baseUrl: "${baseUrl}/v1"`,
-			"    apiKey: LITELLM_API_KEY",
-			"    api: openai-completions",
-			"    discovery:",
-			"      type: openai-compat",
-		);
-	}
-
 	lines.push("");
 	return lines.join("\n");
 }
@@ -81,6 +74,9 @@ export function generateModelsYml(baseUrl: string, options?: GenerateModelsYmlOp
 export function generateConfigYml(): string {
 	return [
 		"# Auto-generated by xcsh for LiteLLM proxy",
+		"modelRoles:",
+		"  default: anthropic/claude-opus-4-6",
+		"",
 		"providers:",
 		"  image: openai",
 		"",
@@ -100,6 +96,25 @@ export function generateConfigYml(): string {
 	].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.
+ */
+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
 // ---------------------------------------------------------------------------
@@ -129,6 +144,26 @@ function safeWrite(filePath: string, content: string): boolean {
 	}
 }
 
+/** 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
 // ---------------------------------------------------------------------------
@@ -137,14 +172,21 @@ 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's /v1/models endpoint to validate connectivity
- * and discover available 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 to avoid blocking startup.
+ * Uses a 3-second timeout per endpoint to avoid blocking startup.
  */
 export async function probeLiteLLMConnection(
 	baseUrl: string,
@@ -153,60 +195,63 @@ export async function probeLiteLLMConnection(
 ): Promise<ProbeResult> {
 	const fetchImpl = options?.fetch ?? globalThis.fetch;
 	const normalizedUrl = baseUrl.replace(/\/+$/, "");
+	let lastError = "";
 
-	let response: Response;
-	try {
-		response = await fetchImpl(`${normalizedUrl}/v1/models`, {
-			method: "GET",
-			headers: {
-				Accept: "application/json",
-				Authorization: `Bearer ${apiKey}`,
-			},
-			signal: options?.signal ?? AbortSignal.timeout(3000),
-		});
-	} catch (err) {
-		return {
-			reachable: false,
-			models: [],
-			error: err instanceof Error ? err.message : String(err),
-		};
-	}
+	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) {
-		return {
-			reachable: false,
-			models: [],
-			error: `HTTP ${response.status} ${response.statusText}`,
-		};
-	}
+		if (!response.ok) {
+			lastError = `HTTP ${response.status} ${response.statusText} from ${url}`;
+			continue;
+		}
 
-	let payload: unknown;
-	try {
-		payload = await response.json();
-	} catch {
-		return {
-			reachable: false,
-			models: [],
-			error: "Failed to parse response as JSON",
-		};
-	}
+		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);
+		// 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: true, models };
+	return { reachable: false, models: [], error: lastError };
 }
 
 // ---------------------------------------------------------------------------
@@ -227,11 +272,13 @@ export function tryAutoConfigLiteLLM(modelsPath: string): boolean {
 	if (!safeWrite(modelsPath, generateModelsYml(baseUrl))) return false;
 	logger.debug("Auto-configured LiteLLM proxy", { modelsPath, baseUrl });
 
-	// Write config.yml if it doesn't exist
+	// 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;
@@ -360,6 +407,9 @@ export function autoFixModelsConfig(modelsPath: string): FixResult {
 		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`] };
 }
@@ -416,16 +466,33 @@ export function startupHealthCheck(
 			return fix.fixed;
 		}
 
-		// Case 4: Config OK and URL matches, but configVersion is missing or outdated
+		// 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 version check, don't block startup
+			// 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);
 		}
 	}
 
@@ -437,12 +504,11 @@ export function startupHealthCheck(
 // ---------------------------------------------------------------------------
 
 /**
- * Probe the LiteLLM proxy and upgrade a v1 config to v2 with discovery.
+ * 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, upgrades the config to
- * include a `litellm` provider with `openai-compat` discovery so the registry
- * discovers real models at runtime instead of relying on bundled model IDs.
+ * 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).
  */
@@ -456,18 +522,15 @@ export async function probeAndUpgradeLiteLLMConfig(
 	const apiKey = $env.LITELLM_API_KEY?.trim();
 	if (!baseUrl || !apiKey) return false;
 
-	// Check if discovery is already configured — no-op if so
+	let content: string;
 	try {
-		const content = fs.readFileSync(modelsPath, "utf-8");
-		if (content.includes("type: openai-compat")) {
-			return false;
-		}
+		content = fs.readFileSync(modelsPath, "utf-8");
 	} catch {
 		// File doesn't exist or is unreadable — nothing to upgrade
 		return false;
 	}
 
-	// Probe the proxy
+	// 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", {
@@ -482,17 +545,26 @@ export async function probeAndUpgradeLiteLLMConfig(
 		return false;
 	}
 
-	// Upgrade: backup and regenerate with discovery
+	// 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
 	backupIfExists(modelsPath);
-	const newContent = generateModelsYml(baseUrl, { discoveredModels: probe.models });
+	const newContent = generateModelsYml(baseUrl, { apiBasePath: probe.apiBasePath });
 	if (!safeWrite(modelsPath, newContent)) {
 		return false;
 	}
 
-	logger.debug("Upgraded LiteLLM config with model discovery", {
+	logger.debug("Upgraded LiteLLM config", {
 		modelsPath,
 		baseUrl,
-		discoveredModels: probe.models.length,
+		apiBasePath: probe.apiBasePath,
+		models: probe.models.length,
+		hadDiscovery: hasDiscovery,
 	});
 	return true;
 }

package/src/config/model-registry.ts

@@ -822,6 +822,29 @@ export class ModelRegistry {
 		this.#backgroundRefresh = refreshPromise;
 	}
 
+	/**
+	 * Await the in-flight background refresh if one is running.
+	 * Returns immediately if no background refresh is in progress.
+	 */
+	async awaitBackgroundRefresh(): Promise<void> {
+		if (this.#backgroundRefresh) {
+			await this.#backgroundRefresh;
+		}
+	}
+
+	/**
+	 * Check if any non-optional discoverable provider has no cached models yet.
+	 * Returns true on first run when the model cache is empty.
+	 */
+	hasUncachedDiscoverableProviders(): boolean {
+		for (const [, state] of this.#providerDiscoveryStates) {
+			if (state.status === "idle" && !state.optional) {
+				return true;
+			}
+		}
+		return false;
+	}
+
 	async refreshProvider(providerId: string, strategy: ModelRefreshStrategy = "online"): Promise<void> {
 		this.#reloadStaticModels();
 		for (const selector of this.#suppressedSelectors.keys()) {
@@ -1283,10 +1306,22 @@ export class ModelRegistry {
 	): Promise<Model<Api>[]> {
 		// Skip providers already handled by configured discovery (e.g. user-configured ollama with discovery.type)
 		const configuredDiscoveryProviders = new Set(this.#discoverableProviders.map(p => p.provider));
+
+		// When a LiteLLM proxy is configured, providers with overridden baseUrls are
+		// proxied through it. Their built-in discovery would query the proxy's model
+		// listing endpoint, which may return model IDs the proxy can't serve for chat.
+		// Skip them — the litellm discovery provider handles model listing instead.
+		const proxiedProviders = hasLiteLLMEnv()
+			? new Set([...this.#providerOverrides.keys()].filter(id => this.#providerOverrides.get(id)?.baseUrl))
+			: new Set<string>();
+
 		const managerOptions = (await this.#collectBuiltInModelManagerOptions()).filter(opts => {
 			if (configuredDiscoveryProviders.has(opts.providerId)) {
 				return false;
 			}
+			if (proxiedProviders.has(opts.providerId)) {
+				return false;
+			}
 			return providerFilter ? providerFilter.has(opts.providerId) : true;
 		});
 		if (managerOptions.length === 0) {

package/src/sdk.ts

@@ -28,6 +28,7 @@ import { AsyncJobManager } from "./async";
 import { createAutoresearchExtension } from "./autoresearch";
 import { loadCapability } from "./capability";
 import { type Rule, ruleCapability } from "./capability/rule";
+import { hasLiteLLMEnv } from "./config/auto-config";
 import { ModelRegistry } from "./config/model-registry";
 import { formatModelString, parseModelPattern, parseModelString, resolveModelRoleValue } from "./config/model-resolver";
 import { loadPromptTemplates as loadPromptTemplatesInternal, type PromptTemplate } from "./config/prompt-templates";
@@ -728,6 +729,14 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	const modelMatchPreferences = {
 		usageOrder: settings.getStorage()?.getModelUsageOrder(),
 	};
+
+	// When LiteLLM is configured and no model cache exists yet (first run),
+	// await the background refresh so model discovery from the proxy completes
+	// before we select a default model. Bounded by the 3s probe timeout.
+	if (!options.modelRegistry && hasLiteLLMEnv() && modelRegistry.hasUncachedDiscoverableProviders()) {
+		await logger.time("awaitLiteLLMDiscovery", () => modelRegistry.awaitBackgroundRefresh());
+	}
+
 	const defaultRoleSpec = logger.time("resolveDefaultModelRole", () =>
 		resolveModelRoleValue(settings.getModelRole("default"), modelRegistry.getAvailable(), {
 			settings,