ruflo 3.5.2 → 3.5.3

package/src/ruvocal/src/lib/server/mcp/hf.ts

@@ -0,0 +1,32 @@
+// Minimal shared helpers for HF MCP token forwarding
+
+export const hasAuthHeader = (h?: Record<string, string>) =>
+	!!h && Object.keys(h).some((k) => k.toLowerCase() === "authorization");
+
+export const isStrictHfMcpLogin = (urlString: string) => {
+	try {
+		const u = new URL(urlString);
+		const host = u.hostname.toLowerCase();
+		const allowedHosts = new Set(["hf.co", "huggingface.co"]);
+		return (
+			u.protocol === "https:" &&
+			allowedHosts.has(host) &&
+			u.pathname === "/mcp" &&
+			u.search === "?login"
+		);
+	} catch {
+		return false;
+	}
+};
+
+export const hasNonEmptyToken = (tok: unknown): tok is string =>
+	typeof tok === "string" && tok.trim().length > 0;
+
+export const isExaMcpServer = (urlString: string): boolean => {
+	try {
+		const u = new URL(urlString);
+		return u.protocol === "https:" && u.hostname.toLowerCase() === "mcp.exa.ai";
+	} catch {
+		return false;
+	}
+};

package/src/ruvocal/src/lib/server/mcp/httpClient.ts

@@ -0,0 +1,122 @@
+import { Client } from "@modelcontextprotocol/sdk/client";
+import { getClient, evictFromPool } from "./clientPool";
+import { config } from "$lib/server/config";
+
+function isConnectionClosedError(err: unknown): boolean {
+	const message = err instanceof Error ? err.message : String(err);
+	return message.includes("-32000") || message.toLowerCase().includes("connection closed");
+}
+
+export interface McpServerConfig {
+	name: string;
+	url: string;
+	headers?: Record<string, string>;
+}
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+export function getMcpToolTimeoutMs(): number {
+	const envValue = config.MCP_TOOL_TIMEOUT_MS;
+	if (envValue) {
+		const parsed = parseInt(envValue, 10);
+		if (!isNaN(parsed) && parsed > 0) {
+			return parsed;
+		}
+	}
+	return DEFAULT_TIMEOUT_MS;
+}
+
+export type McpToolTextResponse = {
+	text: string;
+	/** If the server returned structuredContent, include it raw */
+	structured?: unknown;
+	/** Raw content blocks returned by the server, if any */
+	content?: unknown[];
+};
+
+export type McpToolProgress = {
+	progress: number;
+	total?: number;
+	message?: string;
+};
+
+export async function callMcpTool(
+	server: McpServerConfig,
+	tool: string,
+	args: unknown = {},
+	{
+		timeoutMs = DEFAULT_TIMEOUT_MS,
+		signal,
+		client,
+		onProgress,
+	}: {
+		timeoutMs?: number;
+		signal?: AbortSignal;
+		client?: Client;
+		onProgress?: (progress: McpToolProgress) => void;
+	} = {}
+): Promise<McpToolTextResponse> {
+	const normalizedArgs =
+		typeof args === "object" && args !== null && !Array.isArray(args)
+			? (args as Record<string, unknown>)
+			: undefined;
+
+	// Get a (possibly pooled) client. The client itself was connected with a signal
+	// that already composes outer cancellation. We still enforce a per-call timeout here.
+	let activeClient = client ?? (await getClient(server, signal));
+
+	const callToolOptions = {
+		signal,
+		timeout: timeoutMs,
+		// Enable progress tokens so long-running tools keep extending the timeout.
+		onprogress: (progress: McpToolProgress) => {
+			onProgress?.({
+				progress: progress.progress,
+				total: progress.total,
+				message: progress.message,
+			});
+		},
+		resetTimeoutOnProgress: true,
+	};
+
+	let response;
+	try {
+		response = await activeClient.callTool(
+			{ name: tool, arguments: normalizedArgs },
+			undefined,
+			callToolOptions
+		);
+	} catch (err) {
+		if (!isConnectionClosedError(err)) {
+			throw err;
+		}
+
+		// Evict stale client and close it
+		const stale = evictFromPool(server);
+		stale?.close?.().catch(() => {});
+
+		// Retry with fresh client
+		activeClient = await getClient(server, signal);
+		response = await activeClient.callTool(
+			{ name: tool, arguments: normalizedArgs },
+			undefined,
+			callToolOptions
+		);
+	}
+
+	const parts = Array.isArray(response?.content) ? (response.content as Array<unknown>) : [];
+	const textParts = parts
+		.filter((part): part is { type: "text"; text: string } => {
+			if (typeof part !== "object" || part === null) return false;
+			const obj = part as Record<string, unknown>;
+			return obj["type"] === "text" && typeof obj["text"] === "string";
+		})
+		.map((p) => p.text);
+
+	const text = textParts.join("\n");
+	const structured = (response as unknown as { structuredContent?: unknown })?.structuredContent;
+	const contentBlocks = Array.isArray(response?.content)
+		? (response.content as unknown[])
+		: undefined;
+	return { text, structured, content: contentBlocks };
+}

package/src/ruvocal/src/lib/server/mcp/registry.ts

@@ -0,0 +1,76 @@
+import { config } from "$lib/server/config";
+import { logger } from "$lib/server/logger";
+import type { McpServerConfig } from "./httpClient";
+import { resetMcpToolsCache } from "./tools";
+
+let cachedRaw: string | null = null;
+let cachedServers: McpServerConfig[] = [];
+
+function parseServers(raw: string): McpServerConfig[] {
+	if (!raw) return [];
+
+	try {
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed)) return [];
+
+		return parsed
+			.map((entry) => {
+				if (!entry || typeof entry !== "object") return undefined;
+				const name = (entry as Record<string, unknown>).name;
+				const url = (entry as Record<string, unknown>).url;
+				if (typeof name !== "string" || !name.trim()) return undefined;
+				if (typeof url !== "string" || !url.trim()) return undefined;
+
+				const headersRaw = (entry as Record<string, unknown>).headers;
+				let headers: Record<string, string> | undefined;
+				if (headersRaw && typeof headersRaw === "object" && !Array.isArray(headersRaw)) {
+					const headerEntries = Object.entries(headersRaw as Record<string, unknown>).filter(
+						(entry): entry is [string, string] => typeof entry[1] === "string"
+					);
+					headers = Object.fromEntries(headerEntries);
+				}
+
+				return headers ? { name, url, headers } : { name, url };
+			})
+			.filter((server): server is McpServerConfig => Boolean(server));
+	} catch (error) {
+		logger.warn({ err: error }, "[mcp] failed to parse MCP_SERVERS env");
+		return [];
+	}
+}
+
+function setServers(raw: string) {
+	cachedServers = parseServers(raw);
+	cachedRaw = raw;
+	resetMcpToolsCache();
+	logger.debug({ count: cachedServers.length }, "[mcp] loaded server configuration");
+	console.log(
+		`[MCP] Loaded ${cachedServers.length} server(s):`,
+		cachedServers.map((s) => s.name).join(", ") || "none"
+	);
+}
+
+export function loadMcpServersOnStartup(): McpServerConfig[] {
+	const raw = config.MCP_SERVERS || "[]";
+	setServers(raw);
+	return cachedServers;
+}
+
+export function refreshMcpServersIfChanged(): void {
+	const currentRaw = config.MCP_SERVERS || "[]";
+	if (cachedRaw === null) {
+		setServers(currentRaw);
+		return;
+	}
+
+	if (currentRaw !== cachedRaw) {
+		setServers(currentRaw);
+	}
+}
+
+export function getMcpServers(): McpServerConfig[] {
+	if (cachedRaw === null) {
+		loadMcpServersOnStartup();
+	}
+	return cachedServers;
+}

package/src/ruvocal/src/lib/server/mcp/tools.ts

@@ -0,0 +1,196 @@
+import { Client } from "@modelcontextprotocol/sdk/client";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import type { McpServerConfig } from "./httpClient";
+import { logger } from "$lib/server/logger";
+// use console.* for lightweight diagnostics in production logs
+
+export type OpenAiTool = {
+	type: "function";
+	function: { name: string; description?: string; parameters?: Record<string, unknown> };
+};
+
+export interface McpToolMapping {
+	fnName: string;
+	server: string;
+	tool: string;
+}
+
+interface CacheEntry {
+	fetchedAt: number;
+	ttlMs: number;
+	tools: OpenAiTool[];
+	mapping: Record<string, McpToolMapping>;
+}
+
+const DEFAULT_TTL_MS = 60_000;
+const cache = new Map<string, CacheEntry>();
+
+// Per OpenAI tool/function name guidelines most providers enforce:
+//   ^[a-zA-Z0-9_-]{1,64}$
+// Dots are not universally accepted (e.g., MiniMax via HF router rejects them).
+// Normalize any disallowed characters (including ".") to underscore and trim to 64 chars.
+function sanitizeName(name: string) {
+	return name.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64);
+}
+
+function buildCacheKey(servers: McpServerConfig[]): string {
+	const normalized = servers
+		.map((server) => ({
+			name: server.name,
+			url: server.url,
+			headers: server.headers
+				? Object.entries(server.headers)
+						.sort(([a], [b]) => a.localeCompare(b))
+						.map(([key, value]) => [key, value])
+				: [],
+		}))
+		.sort((a, b) => {
+			const byName = a.name.localeCompare(b.name);
+			if (byName !== 0) return byName;
+			return a.url.localeCompare(b.url);
+		});
+
+	return JSON.stringify(normalized);
+}
+
+type ListedTool = {
+	name?: string;
+	inputSchema?: Record<string, unknown>;
+	description?: string;
+	annotations?: { title?: string };
+};
+
+async function listServerTools(
+	server: McpServerConfig,
+	opts: { signal?: AbortSignal } = {}
+): Promise<ListedTool[]> {
+	const url = new URL(server.url);
+	const client = new Client({ name: "chat-ui-mcp", version: "0.1.0" });
+	try {
+		try {
+			const transport = new StreamableHTTPClientTransport(url, {
+				requestInit: { headers: server.headers, signal: opts.signal },
+			});
+			await client.connect(transport);
+		} catch {
+			const transport = new SSEClientTransport(url, {
+				requestInit: { headers: server.headers, signal: opts.signal },
+			});
+			await client.connect(transport);
+		}
+
+		const response = await client.listTools({});
+		const tools = Array.isArray(response?.tools) ? (response.tools as ListedTool[]) : [];
+		try {
+			logger.debug(
+				{
+					server: server.name,
+					url: server.url,
+					count: tools.length,
+					toolNames: tools.map((t) => t?.name).filter(Boolean),
+				},
+				"[mcp] listed tools from server"
+			);
+		} catch {}
+		return tools;
+	} finally {
+		try {
+			await client.close?.();
+		} catch {
+			// ignore close errors
+		}
+	}
+}
+
+export async function getOpenAiToolsForMcp(
+	servers: McpServerConfig[],
+	{ ttlMs = DEFAULT_TTL_MS, signal }: { ttlMs?: number; signal?: AbortSignal } = {}
+): Promise<{ tools: OpenAiTool[]; mapping: Record<string, McpToolMapping> }> {
+	const now = Date.now();
+	const cacheKey = buildCacheKey(servers);
+	const cached = cache.get(cacheKey);
+	if (cached && now - cached.fetchedAt < cached.ttlMs) {
+		return { tools: cached.tools, mapping: cached.mapping };
+	}
+
+	const tools: OpenAiTool[] = [];
+	const mapping: Record<string, McpToolMapping> = {};
+
+	const seenNames = new Set<string>();
+
+	const pushToolDefinition = (
+		name: string,
+		description: string | undefined,
+		parameters: Record<string, unknown> | undefined
+	) => {
+		if (seenNames.has(name)) return;
+		tools.push({
+			type: "function",
+			function: {
+				name,
+				description,
+				parameters,
+			},
+		});
+		seenNames.add(name);
+	};
+
+	// Fetch tools in parallel; tolerate individual failures
+	const tasks = servers.map((server) => listServerTools(server, { signal }));
+	const results = await Promise.allSettled(tasks);
+
+	for (let i = 0; i < results.length; i++) {
+		const server = servers[i];
+		const r = results[i];
+		if (r.status === "fulfilled") {
+			const serverTools = r.value;
+			for (const tool of serverTools) {
+				if (typeof tool.name !== "string" || tool.name.trim().length === 0) {
+					continue;
+				}
+
+				const parameters =
+					tool.inputSchema && typeof tool.inputSchema === "object" ? tool.inputSchema : undefined;
+				const description = tool.description ?? tool.annotations?.title;
+				const toolName = tool.name;
+
+				// Emit a collision-aware function name.
+				// Prefer the plain tool name; on conflict, suffix with server name.
+				let plainName = sanitizeName(toolName);
+				if (plainName in mapping) {
+					const suffix = sanitizeName(server.name);
+					const candidate = `${plainName}_${suffix}`.slice(0, 64);
+					if (!(candidate in mapping)) {
+						plainName = candidate;
+					} else {
+						let i = 2;
+						let next = `${candidate}_${i}`;
+						while (i < 10 && next in mapping) {
+							i += 1;
+							next = `${candidate}_${i}`;
+						}
+						plainName = next.slice(0, 64);
+					}
+				}
+
+				pushToolDefinition(plainName, description, parameters);
+				mapping[plainName] = {
+					fnName: plainName,
+					server: server.name,
+					tool: toolName,
+				};
+			}
+		} else {
+			// ignore failure for this server
+			continue;
+		}
+	}
+
+	cache.set(cacheKey, { fetchedAt: now, ttlMs, tools, mapping });
+	return { tools, mapping };
+}
+
+export function resetMcpToolsCache() {
+	cache.clear();
+}

package/src/ruvocal/src/lib/server/metrics.ts

@@ -0,0 +1,255 @@
+import { collectDefaultMetrics, Counter, Registry, Summary } from "prom-client";
+import { logger } from "$lib/server/logger";
+import { config } from "$lib/server/config";
+import { createServer, type Server as HttpServer } from "http";
+import { onExit } from "./exitHandler";
+
+type ModelLabel = "model";
+type ToolLabel = "tool";
+
+interface Metrics {
+	model: {
+		conversationsTotal: Counter<ModelLabel>;
+		messagesTotal: Counter<ModelLabel>;
+		tokenCountTotal: Counter<ModelLabel>;
+		timePerOutputToken: Summary<ModelLabel>;
+		timeToFirstToken: Summary<ModelLabel>;
+		latency: Summary<ModelLabel>;
+		votesPositive: Counter<ModelLabel>;
+		votesNegative: Counter<ModelLabel>;
+	};
+	webSearch: {
+		requestCount: Counter;
+		pageFetchCount: Counter;
+		pageFetchCountError: Counter;
+		pageFetchDuration: Summary;
+		embeddingDuration: Summary;
+	};
+	tool: {
+		toolUseCount: Counter<ToolLabel>;
+		toolUseCountError: Counter<ToolLabel>;
+		toolUseDuration: Summary<ToolLabel>;
+		timeToChooseTools: Summary<ModelLabel>;
+	};
+}
+
+export class MetricsServer {
+	private static instance: MetricsServer | undefined;
+	private readonly enabled: boolean;
+	private readonly register: Registry;
+	private readonly metrics: Metrics;
+	private httpServer: HttpServer | undefined;
+
+	private constructor() {
+		this.enabled = config.METRICS_ENABLED === "true";
+		this.register = new Registry();
+
+		if (this.enabled) {
+			collectDefaultMetrics({ register: this.register });
+		}
+
+		this.metrics = this.createMetrics();
+
+		if (this.enabled) {
+			this.startStandaloneServer();
+		}
+	}
+
+	public static getInstance(): MetricsServer {
+		if (!MetricsServer.instance) {
+			MetricsServer.instance = new MetricsServer();
+		}
+		return MetricsServer.instance;
+	}
+
+	public static getMetrics(): Metrics {
+		return MetricsServer.getInstance().metrics;
+	}
+
+	public static isEnabled(): boolean {
+		return config.METRICS_ENABLED === "true";
+	}
+
+	public async render(): Promise<string> {
+		if (!this.enabled) {
+			return "";
+		}
+
+		return this.register.metrics();
+	}
+
+	private createMetrics(): Metrics {
+		const labelNames: ModelLabel[] = ["model"];
+		const toolLabelNames: ToolLabel[] = ["tool"];
+
+		const noopRegistry = new Registry();
+
+		const registry = this.enabled ? this.register : noopRegistry;
+
+		return {
+			model: {
+				conversationsTotal: new Counter<ModelLabel>({
+					name: "model_conversations_total",
+					help: "Total number of conversations",
+					labelNames,
+					registers: [registry],
+				}),
+				messagesTotal: new Counter<ModelLabel>({
+					name: "model_messages_total",
+					help: "Total number of messages",
+					labelNames,
+					registers: [registry],
+				}),
+				tokenCountTotal: new Counter<ModelLabel>({
+					name: "model_token_count_total",
+					help: "Total number of tokens emitted by the model",
+					labelNames,
+					registers: [registry],
+				}),
+				timePerOutputToken: new Summary<ModelLabel>({
+					name: "model_time_per_output_token_ms",
+					help: "Per-token latency in milliseconds",
+					labelNames,
+					registers: [registry],
+					maxAgeSeconds: 5 * 60,
+					ageBuckets: 5,
+				}),
+				timeToFirstToken: new Summary<ModelLabel>({
+					name: "model_time_to_first_token_ms",
+					help: "Time to first token in milliseconds",
+					labelNames,
+					registers: [registry],
+					maxAgeSeconds: 5 * 60,
+					ageBuckets: 5,
+				}),
+				latency: new Summary<ModelLabel>({
+					name: "model_latency_ms",
+					help: "Total time to complete a response in milliseconds",
+					labelNames,
+					registers: [registry],
+					maxAgeSeconds: 5 * 60,
+					ageBuckets: 5,
+				}),
+				votesPositive: new Counter<ModelLabel>({
+					name: "model_votes_positive_total",
+					help: "Total number of positive votes on model messages",
+					labelNames,
+					registers: [registry],
+				}),
+				votesNegative: new Counter<ModelLabel>({
+					name: "model_votes_negative_total",
+					help: "Total number of negative votes on model messages",
+					labelNames,
+					registers: [registry],
+				}),
+			},
+			webSearch: {
+				requestCount: new Counter({
+					name: "web_search_request_count",
+					help: "Total number of web search requests",
+					registers: [registry],
+				}),
+				pageFetchCount: new Counter({
+					name: "web_search_page_fetch_count",
+					help: "Total number of web search page fetches",
+					registers: [registry],
+				}),
+				pageFetchCountError: new Counter({
+					name: "web_search_page_fetch_count_error",
+					help: "Total number of web search page fetch errors",
+					registers: [registry],
+				}),
+				pageFetchDuration: new Summary({
+					name: "web_search_page_fetch_duration_ms",
+					help: "Duration of web search page fetches in milliseconds",
+					registers: [registry],
+					maxAgeSeconds: 5 * 60,
+					ageBuckets: 5,
+				}),
+				embeddingDuration: new Summary({
+					name: "web_search_embedding_duration_ms",
+					help: "Duration of web search embeddings in milliseconds",
+					registers: [registry],
+					maxAgeSeconds: 5 * 60,
+					ageBuckets: 5,
+				}),
+			},
+			tool: {
+				toolUseCount: new Counter<ToolLabel>({
+					name: "tool_use_count",
+					help: "Total number of tool invocations",
+					labelNames: toolLabelNames,
+					registers: [registry],
+				}),
+				toolUseCountError: new Counter<ToolLabel>({
+					name: "tool_use_count_error",
+					help: "Total number of tool invocation errors",
+					labelNames: toolLabelNames,
+					registers: [registry],
+				}),
+				toolUseDuration: new Summary<ToolLabel>({
+					name: "tool_use_duration_ms",
+					help: "Duration of tool invocations in milliseconds",
+					labelNames: toolLabelNames,
+					registers: [registry],
+					maxAgeSeconds: 30 * 60,
+					ageBuckets: 5,
+				}),
+				timeToChooseTools: new Summary<ModelLabel>({
+					name: "time_to_choose_tools_ms",
+					help: "Time spent selecting tools in milliseconds",
+					labelNames,
+					registers: [registry],
+					maxAgeSeconds: 5 * 60,
+					ageBuckets: 5,
+				}),
+			},
+		};
+	}
+
+	private startStandaloneServer() {
+		const port = Number(config.METRICS_PORT || "5565");
+
+		if (!Number.isInteger(port) || port < 0 || port > 65535) {
+			logger.warn(`Invalid METRICS_PORT value: ${config.METRICS_PORT}`);
+			return;
+		}
+
+		this.httpServer = createServer(async (req, res) => {
+			if (req.method !== "GET") {
+				res.statusCode = 405;
+				res.end("Method Not Allowed");
+				return;
+			}
+
+			try {
+				const payload = await this.render();
+				res.setHeader("Content-Type", "text/plain; version=0.0.4");
+				res.end(payload);
+			} catch (error) {
+				logger.error(error, "Failed to render metrics");
+				res.statusCode = 500;
+				res.end("Failed to render metrics");
+			}
+		});
+
+		this.httpServer.listen(port, () => {
+			logger.info(`Metrics server listening on port ${port}`);
+		});
+
+		onExit(async () => {
+			if (!this.httpServer) return;
+			logger.info("Shutting down metrics server...");
+			await new Promise<void>((resolve, reject) => {
+				this.httpServer?.close((err) => {
+					if (err) {
+						reject(err);
+						return;
+					}
+					resolve();
+				});
+			}).catch((error) => logger.error(error, "Failed to close metrics server"));
+			this.httpServer = undefined;
+		});
+	}
+}