@f5-sales-demo/xcsh 20.20.3 → 20.22.0

package/CHANGELOG.md

@@ -6,6 +6,16 @@
 
 ### Added
 
+- Added strict `xcsh://registry/provider/<namespace>/<type>` and
+  `xcsh://registry/module/<namespace>/<name>/<provider>` Terraform Registry lookups with bounded,
+  protocol-native discovery and actionable failures
+  ([#3019](https://github.com/f5-sales-demo/xcsh/issues/3019),
+   [#3361](https://github.com/f5-sales-demo/xcsh/issues/3361)).
+- Added a transactional vLLM `/login` flow with validated HTTP(S) endpoints, masked optional keys,
+  pre-commit model probing, vLLM-only model selection, provider-only refresh, secure atomic
+  persistence, and rollback
+  ([#2947](https://github.com/f5-sales-demo/xcsh/issues/2947),
+   [#3361](https://github.com/f5-sales-demo/xcsh/issues/3361)).
 - Added provenance-validated, deterministic `render_map` PNG generation with OpenStreetMap tile
   policy compliance, schematic and text fallbacks, and optional atomic PNG/GeoJSON export
   ([#3202](https://github.com/f5-sales-demo/xcsh/issues/3202)).
@@ -26,6 +36,10 @@
 
 ### Fixed
 
+- Consumed vLLM-advertised context limits with bounded output budgets while preserving compatibility
+  fallbacks when metadata is absent
+  ([#2947](https://github.com/f5-sales-demo/xcsh/issues/2947),
+   [#3361](https://github.com/f5-sales-demo/xcsh/issues/3361)).
 - Restored bare `xcsh update` as a backward-compatible executable updater while preserving
   manifest-based resource updates and the explicit `xcsh self-update` command
   ([#3249](https://github.com/f5-sales-demo/xcsh/issues/3249)).

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "20.20.3",
+	"version": "20.22.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -61,13 +61,13 @@
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.3.0",
-		"@f5-sales-demo/pi-agent-core": "20.20.3",
-		"@f5-sales-demo/pi-ai": "20.20.3",
-		"@f5-sales-demo/pi-natives": "20.20.3",
-		"@f5-sales-demo/pi-resource-management": "20.20.3",
-		"@f5-sales-demo/pi-tui": "20.20.3",
-		"@f5-sales-demo/pi-utils": "20.20.3",
-		"@f5-sales-demo/xcsh-stats": "20.20.3",
+		"@f5-sales-demo/pi-agent-core": "20.22.0",
+		"@f5-sales-demo/pi-ai": "20.22.0",
+		"@f5-sales-demo/pi-natives": "20.22.0",
+		"@f5-sales-demo/pi-resource-management": "20.22.0",
+		"@f5-sales-demo/pi-tui": "20.22.0",
+		"@f5-sales-demo/pi-utils": "20.22.0",
+		"@f5-sales-demo/xcsh-stats": "20.22.0",
 		"@mozilla/readability": "^0.6",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",

package/src/cli.ts

@@ -118,6 +118,7 @@ function requestsHelp(args: readonly string[]): boolean {
 export function runCli(argv: string[]): Promise<void> {
 	// --help and --version are handled by run() directly, don't rewrite those.
 	// Everything else that isn't a known subcommand routes to "launch".
+	// Keeping this routing boundary explicit makes the CLI fallback easy to audit.
 	const first = argv[0];
 	if (!isSubcommand(first)) {
 		try {

package/src/config/model-registry.ts

@@ -14,6 +14,7 @@ import {
 	type Model,
 	type ModelManagerOptions,
 	type ModelRefreshStrategy,
+	NO_AUTH_API_KEY,
 	type OAuthCredentials,
 	type OAuthLoginCallbacks,
 	openaiCodexModelManagerOptions,
@@ -31,6 +32,7 @@ import { type Static, Type } from "@sinclair/typebox";
 import { type ConfigError, ConfigFile } from "../config";
 import { hasLiteLLMEnv, probeAndUpgradeLiteLLMConfig, startupHealthCheck } from "../config/auto-config";
 import { parseModelString, resolveProviderModelReference } from "../config/model-resolver";
+import { parseVllmModelsPayload } from "../config/vllm-config";
 import { isValidThemeColor, type ThemeColor } from "../modes/theme/theme";
 import type { AuthStorage, OAuthCredential } from "../session/auth-storage";
 import {
@@ -45,7 +47,7 @@ import { type Settings, settings } from "./settings";
 
 export type { CanonicalModelIndex, CanonicalModelRecord, CanonicalModelVariant, ModelEquivalenceConfig };
 
-export const kNoAuth = "N/A";
+export const kNoAuth = NO_AUTH_API_KEY;
 
 export function isAuthenticated(apiKey: string | undefined | null): apiKey is string {
 	return Boolean(apiKey) && apiKey !== kNoAuth;
@@ -1737,8 +1739,11 @@ export class ModelRegistry {
 		if (!response.ok) {
 			throw new Error(`HTTP ${response.status} from ${modelsUrl}`);
 		}
-		const payload = (await response.json()) as { data?: Array<{ id: string }> };
-		const items = payload.data ?? [];
+		const payload = await response.json();
+		const items: Array<{ id: string; contextWindow?: number }> =
+			providerConfig.provider === "vllm"
+				? parseVllmModelsPayload(payload)
+				: ((payload as { data?: Array<{ id: string }> }).data ?? []);
 		const discovered: Model<Api>[] = [];
 		for (const item of items) {
 			const id = item.id;
@@ -1753,8 +1758,11 @@ export class ModelRegistry {
 					reasoning: false,
 					input: ["text"],
 					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-					contextWindow: 128000,
-					maxTokens: 8192,
+					contextWindow: item.contextWindow ?? 128000,
+					maxTokens:
+						item.contextWindow === undefined
+							? 8192
+							: Math.max(1, Math.min(8192, Math.floor(item.contextWindow / 4))),
 					headers,
 				}),
 			);

package/src/config/vllm-config.ts

@@ -0,0 +1,212 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Document, isMap, parseDocument } from "yaml";
+
+const CONFIG_DIR_MODE = 0o700;
+const MODELS_FILE_MODE = 0o600;
+const DEFAULT_PROBE_TIMEOUT_MS = 5_000;
+const CONTEXT_FIELDS = [
+	"max_model_len",
+	"max_model_length",
+	"max_context_length",
+	"context_length",
+	"context_window",
+	"max_sequence_length",
+] as const;
+
+export const DEFAULT_VLLM_BASE_URL = "http://127.0.0.1:8000/v1";
+
+export interface VllmConfig {
+	baseUrl: string;
+}
+
+export interface VllmDiscoveredModel {
+	id: string;
+	contextWindow?: number;
+}
+
+export interface VllmProbeResult {
+	models: VllmDiscoveredModel[];
+}
+
+export interface VllmProbeOptions {
+	fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+	timeoutMs?: number;
+	signal?: AbortSignal;
+}
+
+export interface WriteVllmModelsConfigOptions {
+	authenticated: boolean;
+}
+
+export function normalizeVllmBaseUrl(value: string): string {
+	const trimmed = value.trim();
+	let parsed: URL;
+	try {
+		parsed = new URL(trimmed);
+	} catch {
+		throw new Error("vLLM Base URL must be a valid HTTP or HTTPS URL");
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+		throw new Error("vLLM Base URL must use HTTP or HTTPS");
+	}
+	if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+		throw new Error("vLLM Base URL must not contain credentials, query parameters, or a fragment");
+	}
+	return parsed.toString().replace(/\/+$/, "");
+}
+
+function parseModelsDocument(content: string, filePath: string): ReturnType<typeof parseDocument> {
+	const document = parseDocument(content, { prettyErrors: false });
+	if (document.errors.length > 0) {
+		throw new Error(`Cannot update ${filePath}: invalid YAML (${document.errors[0]?.message ?? "parse error"})`);
+	}
+	if (document.contents !== null && !isMap(document.contents)) {
+		throw new Error(`Cannot update ${filePath}: the YAML root must be a map`);
+	}
+	const providers = document.get("providers", true);
+	if (providers !== undefined && providers !== null && !isMap(providers)) {
+		throw new Error(`Cannot update ${filePath}: providers must be a map`);
+	}
+	const vllm = document.getIn(["providers", "vllm"], true);
+	if (vllm !== undefined && vllm !== null && !isMap(vllm)) {
+		throw new Error(`Cannot update ${filePath}: providers.vllm must be a map`);
+	}
+	return document;
+}
+
+export function readVllmConfig(modelsPath: string): VllmConfig | undefined {
+	let content: string;
+	try {
+		content = fs.readFileSync(modelsPath, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+	const document = parseModelsDocument(content, modelsPath);
+	const baseUrl = document.getIn(["providers", "vllm", "baseUrl"]);
+	if (typeof baseUrl !== "string" || !baseUrl.trim()) return undefined;
+	return { baseUrl: normalizeVllmBaseUrl(baseUrl) };
+}
+
+function positiveInteger(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isFinite(value) && value > 0) return Math.floor(value);
+	if (typeof value === "string" && value.trim()) {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed) && parsed > 0) return Math.floor(parsed);
+	}
+	return undefined;
+}
+
+function discoveredContextWindow(entry: Record<string, unknown>): number | undefined {
+	for (const field of CONTEXT_FIELDS) {
+		const value = positiveInteger(entry[field]);
+		if (value !== undefined) return value;
+	}
+	return undefined;
+}
+
+export function parseVllmModelsPayload(payload: unknown): VllmDiscoveredModel[] {
+	if (typeof payload !== "object" || payload === null || !Array.isArray((payload as { data?: unknown }).data)) {
+		throw new Error("vLLM returned a malformed model catalog");
+	}
+
+	const models: VllmDiscoveredModel[] = [];
+	const seen = new Set<string>();
+	for (const rawEntry of (payload as { data: unknown[] }).data) {
+		if (typeof rawEntry !== "object" || rawEntry === null || typeof (rawEntry as { id?: unknown }).id !== "string") {
+			throw new Error("vLLM returned a malformed model catalog");
+		}
+		const entry = rawEntry as Record<string, unknown> & { id: string };
+		const id = entry.id.trim();
+		if (!id || seen.has(id)) continue;
+		seen.add(id);
+		const contextWindow = discoveredContextWindow(entry);
+		models.push(contextWindow === undefined ? { id } : { id, contextWindow });
+	}
+	if (models.length === 0) throw new Error("vLLM returned no models");
+	return models;
+}
+
+export async function probeVllmConnection(
+	baseUrl: string,
+	apiKey: string,
+	options: VllmProbeOptions = {},
+): Promise<VllmProbeResult> {
+	const normalizedBaseUrl = normalizeVllmBaseUrl(baseUrl);
+	const modelsUrl = `${normalizedBaseUrl}/models`;
+	const headers = new Headers({ Accept: "application/json" });
+	const trimmedApiKey = apiKey.trim();
+	if (trimmedApiKey) headers.set("Authorization", `Bearer ${trimmedApiKey}`);
+
+	const signal = options.signal ?? AbortSignal.timeout(options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS);
+	let response: Response;
+	try {
+		response = await (options.fetch ?? globalThis.fetch)(modelsUrl, { headers, signal });
+	} catch (error) {
+		const name = error instanceof Error ? error.name : "";
+		if (name === "TimeoutError" || name === "AbortError") {
+			throw new Error(`vLLM connection timed out at ${modelsUrl}`, { cause: error });
+		}
+		throw new Error(`Could not connect to vLLM at ${modelsUrl}`, { cause: error });
+	}
+
+	if (response.status === 401 || response.status === 403) {
+		throw new Error(`vLLM rejected the API key (HTTP ${response.status})`);
+	}
+	if (!response.ok) throw new Error(`vLLM model discovery failed with HTTP ${response.status}`);
+
+	let payload: unknown;
+	try {
+		payload = await response.json();
+	} catch (error) {
+		throw new Error("vLLM /models did not return valid JSON", { cause: error });
+	}
+	return { models: parseVllmModelsPayload(payload) };
+}
+
+async function atomicWrite(filePath: string, content: string): Promise<void> {
+	const directory = path.dirname(filePath);
+	await fs.promises.mkdir(directory, { recursive: true, mode: CONFIG_DIR_MODE });
+	await fs.promises.chmod(directory, CONFIG_DIR_MODE);
+
+	const tempPath = path.join(directory, `.${path.basename(filePath)}.${randomUUID()}.tmp`);
+	let handle: fs.promises.FileHandle | undefined;
+	try {
+		handle = await fs.promises.open(tempPath, "wx", MODELS_FILE_MODE);
+		await handle.writeFile(content, "utf8");
+		await handle.sync();
+		await handle.close();
+		handle = undefined;
+		await fs.promises.rename(tempPath, filePath);
+		await fs.promises.chmod(filePath, MODELS_FILE_MODE);
+	} catch (error) {
+		await handle?.close().catch(() => undefined);
+		await fs.promises.unlink(tempPath).catch(() => undefined);
+		throw error;
+	}
+}
+
+export async function writeVllmModelsConfig(
+	modelsPath: string,
+	baseUrl: string,
+	options: WriteVllmModelsConfigOptions,
+): Promise<void> {
+	let document: ReturnType<typeof parseDocument> | Document;
+	try {
+		document = parseModelsDocument(await fs.promises.readFile(modelsPath, "utf8"), modelsPath);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		document = new Document({});
+	}
+
+	document.setIn(["providers", "vllm", "baseUrl"], normalizeVllmBaseUrl(baseUrl));
+	document.setIn(["providers", "vllm", "api"], "openai-completions");
+	document.setIn(["providers", "vllm", "discovery", "type"], "openai-compat");
+	if (options.authenticated) document.deleteIn(["providers", "vllm", "auth"]);
+	else document.setIn(["providers", "vllm", "auth"], "none");
+	document.deleteIn(["providers", "vllm", "apiKey"]);
+
+	await atomicWrite(modelsPath, document.toString({ lineWidth: 0 }));
+}