miladyai 2.0.0-alpha.27

package/dist/api/character-routes.js

@@ -0,0 +1,195 @@
+import { CharacterSchema } from "../config/zod-schema.js";
+import { ModelType, logger } from "@elizaos/core";
+
+//#region src/api/character-routes.ts
+function buildCharacterSummary(ctx) {
+	return [
+		ctx.name ? `Name: ${ctx.name}` : "",
+		ctx.system ? `System prompt: ${ctx.system}` : "",
+		ctx.bio ? `Bio: ${ctx.bio}` : "",
+		ctx.style?.all?.length ? `Style rules: ${ctx.style.all.join("; ")}` : ""
+	].filter(Boolean).join("\n");
+}
+function buildGeneratePrompt(field, context, mode) {
+	const charSummary = buildCharacterSummary(context);
+	if (field === "bio") return `Given this character:\n${charSummary}\n\nWrite a concise, compelling bio for this character (3-4 short paragraphs, one per line). Just output the bio lines, nothing else. Match the character's voice and personality.`;
+	if (field === "style") return `Given this character:\n${charSummary}${mode === "append" && context.style?.all?.length ? `\nExisting style rules (add to these, don't repeat):\n${context.style.all.join("\n")}` : ""}\n\nGenerate 4-6 communication style rules for this character. Output a JSON object with keys "all", "chat", "post", each containing an array of short rule strings. Just output the JSON, nothing else.`;
+	if (field === "chatExamples") return `Given this character:\n${charSummary}\n\nGenerate 3 example chat conversations showing how this character responds. Output a JSON array where each element is an array of message objects like [{"user":"{{user1}}","content":{"text":"..."}},{"user":"{{agentName}}","content":{"text":"..."}}]. Just output the JSON array, nothing else.`;
+	return `Given this character:\n${charSummary}${mode === "append" && context.postExamples?.length ? `\nExisting posts (add new ones, don't repeat):\n${context.postExamples.join("\n")}` : ""}\n\nGenerate 3-5 example social media posts this character would write. Output a JSON array of strings. Just output the JSON array, nothing else.`;
+}
+const CHARACTER_SCHEMA_FIELDS = [
+	{
+		key: "name",
+		type: "string",
+		label: "Name",
+		description: "Agent display name",
+		maxLength: 100
+	},
+	{
+		key: "username",
+		type: "string",
+		label: "Username",
+		description: "Agent username for platforms",
+		maxLength: 50
+	},
+	{
+		key: "bio",
+		type: "string | string[]",
+		label: "Bio",
+		description: "Biography — single string or array of points"
+	},
+	{
+		key: "system",
+		type: "string",
+		label: "System Prompt",
+		description: "System prompt defining core behavior",
+		maxLength: 1e4
+	},
+	{
+		key: "adjectives",
+		type: "string[]",
+		label: "Adjectives",
+		description: "Personality adjectives (e.g. curious, witty)"
+	},
+	{
+		key: "topics",
+		type: "string[]",
+		label: "Topics",
+		description: "Topics the agent is knowledgeable about"
+	},
+	{
+		key: "style",
+		type: "object",
+		label: "Style",
+		description: "Communication style guides",
+		children: [
+			{
+				key: "all",
+				type: "string[]",
+				label: "All",
+				description: "Style guidelines for all responses"
+			},
+			{
+				key: "chat",
+				type: "string[]",
+				label: "Chat",
+				description: "Style guidelines for chat responses"
+			},
+			{
+				key: "post",
+				type: "string[]",
+				label: "Post",
+				description: "Style guidelines for social media posts"
+			}
+		]
+	},
+	{
+		key: "messageExamples",
+		type: "array",
+		label: "Message Examples",
+		description: "Example conversations demonstrating the agent's voice"
+	},
+	{
+		key: "postExamples",
+		type: "string[]",
+		label: "Post Examples",
+		description: "Example social media posts"
+	}
+];
+async function handleCharacterRoutes(ctx) {
+	const { req, res, method, pathname, state, readJsonBody, json, error, pickRandomNames } = ctx;
+	if (method === "GET" && pathname === "/api/character") {
+		const runtime = state.runtime;
+		const merged = {};
+		if (runtime) {
+			const character = runtime.character;
+			if (character.name) merged.name = character.name;
+			if (character.bio) merged.bio = character.bio;
+			if (character.system) merged.system = character.system;
+			if (character.adjectives) merged.adjectives = character.adjectives;
+			if (character.topics) merged.topics = character.topics;
+			if (character.style) merged.style = character.style;
+			if (character.postExamples) merged.postExamples = character.postExamples;
+		}
+		json(res, {
+			character: merged,
+			agentName: state.agentName
+		});
+		return true;
+	}
+	if (method === "PUT" && pathname === "/api/character") {
+		const body = await readJsonBody(req, res);
+		if (!body) return true;
+		const result = CharacterSchema.safeParse(body);
+		if (!result.success) {
+			json(res, {
+				ok: false,
+				validationErrors: result.error.issues.map((issue) => ({
+					path: issue.path.join("."),
+					message: issue.message
+				}))
+			}, 422);
+			return true;
+		}
+		if (state.runtime) {
+			const character = state.runtime.character;
+			if (body.name != null) character.name = String(body.name);
+			if (body.bio != null) character.bio = Array.isArray(body.bio) ? body.bio : [String(body.bio)];
+			if (body.system != null) character.system = String(body.system);
+			if (body.adjectives != null) character.adjectives = body.adjectives;
+			if (body.topics != null) character.topics = body.topics;
+			if (body.style != null) character.style = body.style;
+			if (body.postExamples != null) character.postExamples = body.postExamples;
+		}
+		if (body.name) state.agentName = String(body.name);
+		json(res, {
+			ok: true,
+			character: body,
+			agentName: state.agentName
+		});
+		return true;
+	}
+	if (method === "GET" && pathname === "/api/character/random-name") {
+		json(res, { name: pickRandomNames(1)[0] ?? "Reimu" });
+		return true;
+	}
+	if (method === "POST" && pathname === "/api/character/generate") {
+		const body = await readJsonBody(req, res);
+		if (!body) return true;
+		if (!body.field || !body.context) {
+			error(res, "field and context are required", 400);
+			return true;
+		}
+		const runtime = state.runtime;
+		if (!runtime) {
+			error(res, "Agent runtime not available. Start the agent first.", 503);
+			return true;
+		}
+		if (body.field !== "bio" && body.field !== "style" && body.field !== "chatExamples" && body.field !== "postExamples") {
+			error(res, `Unknown field: ${body.field}`, 400);
+			return true;
+		}
+		const prompt = buildGeneratePrompt(body.field, body.context, body.mode);
+		try {
+			const result = await runtime.useModel(ModelType.TEXT_SMALL, {
+				prompt,
+				temperature: .8,
+				maxTokens: 1500
+			});
+			json(res, { generated: String(result) });
+		} catch (err) {
+			const message = err instanceof Error ? err.message : "generation failed";
+			logger.error(`[character-generate] ${message}`);
+			error(res, message, 500);
+		}
+		return true;
+	}
+	if (method === "GET" && pathname === "/api/character/schema") {
+		json(res, { fields: CHARACTER_SCHEMA_FIELDS });
+		return true;
+	}
+	return false;
+}
+
+//#endregion
+export { handleCharacterRoutes };

package/dist/api/cloud-routes.js

@@ -0,0 +1,330 @@
+import { saveMiladyConfig } from "../config/config.js";
+import { createIntegrationTelemetrySpan } from "../diagnostics/integration-observability.js";
+import { readJsonBody as readJsonBody$1, sendJson, sendJsonError } from "./http-helpers.js";
+import { validateCloudBaseUrl } from "../cloud/validate-url.js";
+import { logger } from "@elizaos/core";
+
+//#region src/api/cloud-routes.ts
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function extractAgentId(pathname) {
+	const id = pathname.split("/")[4];
+	return id && UUID_RE.test(id) ? id : null;
+}
+/**
+* Read and parse a JSON request body with size limits and error handling.
+* Returns null (and sends a 4xx response) if reading or parsing fails.
+*/
+async function readJsonBody(req, res) {
+	return readJsonBody$1(req, res, {
+		maxBytes: 1048576,
+		tooLargeMessage: "Request body too large",
+		destroyOnTooLarge: true
+	});
+}
+const CLOUD_LOGIN_CREATE_TIMEOUT_MS = 1e4;
+const CLOUD_LOGIN_POLL_TIMEOUT_MS = 1e4;
+function isRedirectResponse(response) {
+	return response.status >= 300 && response.status < 400;
+}
+function isTimeoutError(error) {
+	if (!(error instanceof Error)) return false;
+	if (error.name === "TimeoutError" || error.name === "AbortError") return true;
+	const message = error.message.toLowerCase();
+	return message.includes("timed out") || message.includes("timeout");
+}
+async function fetchWithTimeout(input, init, timeoutMs) {
+	return fetch(input, {
+		...init,
+		redirect: "manual",
+		signal: AbortSignal.timeout(timeoutMs)
+	});
+}
+/**
+* Returns true if the request was handled, false if path didn't match.
+*/
+async function handleCloudRoute(req, res, pathname, method, state) {
+	if (method === "POST" && pathname === "/api/cloud/login") {
+		const baseUrl = state.config.cloud?.baseUrl ?? "https://www.elizacloud.ai";
+		const urlError = await validateCloudBaseUrl(baseUrl);
+		if (urlError) {
+			sendJsonError(res, urlError);
+			return true;
+		}
+		const sessionId = crypto.randomUUID();
+		const loginCreateSpan = createIntegrationTelemetrySpan({
+			boundary: "cloud",
+			operation: "login_create_session",
+			timeoutMs: CLOUD_LOGIN_CREATE_TIMEOUT_MS
+		});
+		let createRes;
+		try {
+			createRes = await fetchWithTimeout(`${baseUrl}/api/auth/cli-session`, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ sessionId })
+			}, CLOUD_LOGIN_CREATE_TIMEOUT_MS);
+		} catch (fetchErr) {
+			if (isTimeoutError(fetchErr)) {
+				loginCreateSpan.failure({
+					error: fetchErr,
+					statusCode: 504
+				});
+				sendJsonError(res, "Eliza Cloud login request timed out", 504);
+				return true;
+			}
+			loginCreateSpan.failure({
+				error: fetchErr,
+				statusCode: 502
+			});
+			sendJsonError(res, "Failed to reach Eliza Cloud", 502);
+			return true;
+		}
+		if (isRedirectResponse(createRes)) {
+			loginCreateSpan.failure({
+				statusCode: createRes.status,
+				errorKind: "redirect_response"
+			});
+			sendJsonError(res, "Eliza Cloud login request was redirected; redirects are not allowed", 502);
+			return true;
+		}
+		if (!createRes.ok) {
+			loginCreateSpan.failure({
+				statusCode: createRes.status,
+				errorKind: "http_error"
+			});
+			sendJsonError(res, "Failed to create auth session with Eliza Cloud", 502);
+			return true;
+		}
+		loginCreateSpan.success({ statusCode: createRes.status });
+		sendJson(res, {
+			ok: true,
+			sessionId,
+			browserUrl: `${baseUrl}/auth/cli-login?session=${encodeURIComponent(sessionId)}`
+		});
+		return true;
+	}
+	if (method === "GET" && pathname.startsWith("/api/cloud/login/status")) {
+		const sessionId = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`).searchParams.get("sessionId");
+		if (!sessionId) {
+			sendJsonError(res, "sessionId query parameter is required");
+			return true;
+		}
+		const baseUrl = state.config.cloud?.baseUrl ?? "https://www.elizacloud.ai";
+		const urlError = await validateCloudBaseUrl(baseUrl);
+		if (urlError) {
+			sendJsonError(res, urlError);
+			return true;
+		}
+		const loginPollSpan = createIntegrationTelemetrySpan({
+			boundary: "cloud",
+			operation: "login_poll_status",
+			timeoutMs: CLOUD_LOGIN_POLL_TIMEOUT_MS
+		});
+		let pollRes;
+		try {
+			pollRes = await fetchWithTimeout(`${baseUrl}/api/auth/cli-session/${encodeURIComponent(sessionId)}`, {}, CLOUD_LOGIN_POLL_TIMEOUT_MS);
+		} catch (fetchErr) {
+			if (isTimeoutError(fetchErr)) {
+				loginPollSpan.failure({
+					error: fetchErr,
+					statusCode: 504
+				});
+				sendJson(res, {
+					status: "error",
+					error: "Eliza Cloud status request timed out"
+				}, 504);
+				return true;
+			}
+			loginPollSpan.failure({
+				error: fetchErr,
+				statusCode: 502
+			});
+			sendJson(res, {
+				status: "error",
+				error: "Failed to reach Eliza Cloud"
+			}, 502);
+			return true;
+		}
+		if (isRedirectResponse(pollRes)) {
+			loginPollSpan.failure({
+				statusCode: pollRes.status,
+				errorKind: "redirect_response"
+			});
+			sendJson(res, {
+				status: "error",
+				error: "Eliza Cloud status request was redirected; redirects are not allowed"
+			}, 502);
+			return true;
+		}
+		if (!pollRes.ok) {
+			loginPollSpan.failure({
+				statusCode: pollRes.status,
+				errorKind: "http_error"
+			});
+			sendJson(res, pollRes.status === 404 ? {
+				status: "expired",
+				error: "Session not found or expired"
+			} : {
+				status: "error",
+				error: `Eliza Cloud returned HTTP ${pollRes.status}`
+			});
+			return true;
+		}
+		let data;
+		try {
+			data = await pollRes.json();
+		} catch (parseErr) {
+			loginPollSpan.failure({
+				error: parseErr,
+				statusCode: pollRes.status
+			});
+			throw parseErr;
+		}
+		loginPollSpan.success({ statusCode: pollRes.status });
+		if (data.status === "authenticated" && data.apiKey) {
+			const cloud = state.config.cloud ?? {};
+			cloud.enabled = true;
+			cloud.apiKey = data.apiKey;
+			state.config.cloud = cloud;
+			try {
+				saveMiladyConfig(state.config);
+				logger.info("[cloud-login] API key saved to config file");
+			} catch (saveErr) {
+				logger.error(`[cloud-login] Failed to save config: ${saveErr instanceof Error ? saveErr.message : saveErr}`);
+			}
+			process.env.ELIZAOS_CLOUD_API_KEY = data.apiKey;
+			process.env.ELIZAOS_CLOUD_ENABLED = "true";
+			if (state.runtime) try {
+				if (!state.runtime.character.secrets) state.runtime.character.secrets = {};
+				const secrets = state.runtime.character.secrets;
+				secrets.ELIZAOS_CLOUD_API_KEY = data.apiKey;
+				secrets.ELIZAOS_CLOUD_ENABLED = "true";
+				await state.runtime.updateAgent(state.runtime.agentId, { secrets: { ...secrets } });
+				logger.info("[cloud-login] API key persisted to agent DB record");
+			} catch (dbErr) {
+				logger.warn(`[cloud-login] DB persistence failed (non-fatal): ${dbErr instanceof Error ? dbErr.message : dbErr}`);
+			}
+			if (state.cloudManager && !state.cloudManager.getClient()) await state.cloudManager.init();
+			sendJson(res, {
+				status: "authenticated",
+				keyPrefix: data.keyPrefix
+			});
+		} else sendJson(res, { status: data.status });
+		return true;
+	}
+	if (method === "GET" && pathname === "/api/cloud/agents") {
+		const client = state.cloudManager?.getClient();
+		if (!client) {
+			sendJsonError(res, "Not connected to Eliza Cloud", 401);
+			return true;
+		}
+		sendJson(res, {
+			ok: true,
+			agents: await client.listAgents()
+		});
+		return true;
+	}
+	if (method === "POST" && pathname === "/api/cloud/agents") {
+		const client = state.cloudManager?.getClient();
+		if (!client) {
+			sendJsonError(res, "Not connected to Eliza Cloud", 401);
+			return true;
+		}
+		const body = await readJsonBody(req, res);
+		if (!body) return true;
+		if (!body.agentName?.trim()) {
+			sendJsonError(res, "agentName is required");
+			return true;
+		}
+		sendJson(res, {
+			ok: true,
+			agent: await client.createAgent({
+				agentName: body.agentName,
+				agentConfig: body.agentConfig,
+				environmentVars: body.environmentVars
+			})
+		}, 201);
+		return true;
+	}
+	if (method === "POST" && pathname.startsWith("/api/cloud/agents/") && pathname.endsWith("/provision")) {
+		const agentId = extractAgentId(pathname);
+		if (!agentId || !state.cloudManager) {
+			sendJsonError(res, "Invalid agent ID or cloud not connected", 400);
+			return true;
+		}
+		sendJson(res, {
+			ok: true,
+			agentId,
+			agentName: (await state.cloudManager.connect(agentId)).agentName,
+			status: state.cloudManager.getStatus()
+		});
+		return true;
+	}
+	if (method === "POST" && pathname.startsWith("/api/cloud/agents/") && pathname.endsWith("/shutdown")) {
+		const agentId = extractAgentId(pathname);
+		if (!agentId || !state.cloudManager) {
+			sendJsonError(res, "Invalid agent ID or cloud not connected", 400);
+			return true;
+		}
+		const client = state.cloudManager.getClient();
+		if (!client) {
+			sendJsonError(res, "Not connected to Eliza Cloud", 401);
+			return true;
+		}
+		if (state.cloudManager.getActiveAgentId() === agentId) await state.cloudManager.disconnect();
+		await client.deleteAgent(agentId);
+		sendJson(res, {
+			ok: true,
+			agentId,
+			status: "stopped"
+		});
+		return true;
+	}
+	if (method === "POST" && pathname.startsWith("/api/cloud/agents/") && pathname.endsWith("/connect")) {
+		const agentId = extractAgentId(pathname);
+		if (!agentId || !state.cloudManager) {
+			sendJsonError(res, "Invalid agent ID or cloud not connected", 400);
+			return true;
+		}
+		if (state.cloudManager.getActiveAgentId()) await state.cloudManager.disconnect();
+		sendJson(res, {
+			ok: true,
+			agentId,
+			agentName: (await state.cloudManager.connect(agentId)).agentName,
+			status: state.cloudManager.getStatus()
+		});
+		return true;
+	}
+	if (method === "POST" && pathname === "/api/cloud/disconnect") {
+		if (state.cloudManager) await state.cloudManager.disconnect();
+		const cloud = state.config.cloud ?? {};
+		cloud.enabled = false;
+		delete cloud.apiKey;
+		state.config.cloud = cloud;
+		try {
+			saveMiladyConfig(state.config);
+		} catch (saveErr) {
+			logger.warn(`[cloud-login] Failed to save cloud disconnect state: ${saveErr instanceof Error ? saveErr.message : saveErr}`);
+		}
+		delete process.env.ELIZAOS_CLOUD_API_KEY;
+		delete process.env.ELIZAOS_CLOUD_ENABLED;
+		if (state.runtime) try {
+			if (!state.runtime.character.secrets) state.runtime.character.secrets = {};
+			const secrets = state.runtime.character.secrets;
+			delete secrets.ELIZAOS_CLOUD_API_KEY;
+			delete secrets.ELIZAOS_CLOUD_ENABLED;
+			await state.runtime.updateAgent(state.runtime.agentId, { secrets: { ...secrets } });
+		} catch (dbErr) {
+			logger.warn(`[cloud-login] Failed to clear cloud secrets from agent DB: ${dbErr instanceof Error ? dbErr.message : dbErr}`);
+		}
+		sendJson(res, {
+			ok: true,
+			status: "disconnected"
+		});
+		return true;
+	}
+	return false;
+}
+
+//#endregion
+export { handleCloudRoute };

package/dist/api/cloud-status-routes.js

@@ -0,0 +1,155 @@
+import { validateCloudBaseUrl } from "../cloud/validate-url.js";
+import { logger } from "@elizaos/core";
+
+//#region src/api/cloud-status-routes.ts
+const DEFAULT_CLOUD_API_BASE_URL = "https://www.elizacloud.ai/api/v1";
+const CLOUD_BILLING_URL = "https://www.elizacloud.ai/dashboard/settings?tab=billing";
+function resolveCloudApiBaseUrl(rawBaseUrl) {
+	const base = (rawBaseUrl ?? DEFAULT_CLOUD_API_BASE_URL).trim().replace(/\/+$/, "");
+	if (base.endsWith("/api/v1")) return base;
+	return `${base}/api/v1`;
+}
+async function fetchCloudCreditsByApiKey(baseUrl, apiKey) {
+	const response = await fetch(`${baseUrl}/credits/balance`, {
+		headers: {
+			Accept: "application/json",
+			Authorization: `Bearer ${apiKey}`
+		},
+		redirect: "manual",
+		signal: AbortSignal.timeout(1e4)
+	});
+	if (response.status >= 300 && response.status < 400) throw new Error("Cloud credits request was redirected; redirects are not allowed");
+	const creditResponse = await response.json().catch(() => ({}));
+	if (!response.ok) {
+		const message = typeof creditResponse.error === "string" && creditResponse.error.trim() ? creditResponse.error : `HTTP ${response.status}`;
+		throw new Error(message);
+	}
+	const rawBalance = typeof creditResponse.balance === "number" ? creditResponse.balance : typeof creditResponse.data?.balance === "number" ? creditResponse.data.balance : void 0;
+	return typeof rawBalance === "number" ? rawBalance : null;
+}
+async function handleCloudStatusRoutes(ctx) {
+	const { res, method, pathname, config, runtime, json } = ctx;
+	if (method === "GET" && pathname === "/api/cloud/status") {
+		const cloudMode = config.cloud?.enabled;
+		const cloudEnabled = cloudMode === true;
+		const hasApiKey = Boolean(config.cloud?.apiKey?.trim());
+		const effectivelyEnabled = cloudEnabled || cloudMode !== false && hasApiKey;
+		const cloudAuth = runtime ? runtime.getService("CLOUD_AUTH") : null;
+		const authConnected = Boolean(cloudAuth?.isAuthenticated());
+		if (authConnected || hasApiKey) {
+			json(res, {
+				connected: true,
+				enabled: effectivelyEnabled,
+				hasApiKey,
+				userId: authConnected ? cloudAuth?.getUserId?.() : void 0,
+				organizationId: authConnected ? cloudAuth?.getOrganizationId?.() : void 0,
+				topUpUrl: CLOUD_BILLING_URL,
+				reason: authConnected ? void 0 : runtime ? "api_key_present_not_authenticated" : "api_key_present_runtime_not_started"
+			});
+			return true;
+		}
+		if (!runtime) {
+			json(res, {
+				connected: false,
+				enabled: effectivelyEnabled,
+				hasApiKey,
+				reason: "runtime_not_started"
+			});
+			return true;
+		}
+		json(res, {
+			connected: false,
+			enabled: effectivelyEnabled,
+			hasApiKey,
+			reason: "not_authenticated"
+		});
+		return true;
+	}
+	if (method === "GET" && pathname === "/api/cloud/credits") {
+		const cloudAuth = runtime ? runtime.getService("CLOUD_AUTH") : null;
+		const configApiKey = config.cloud?.apiKey?.trim();
+		if (!cloudAuth || !cloudAuth.isAuthenticated()) {
+			if (!configApiKey) {
+				json(res, {
+					balance: null,
+					connected: false
+				});
+				return true;
+			}
+			const resolvedBaseUrl = resolveCloudApiBaseUrl(config.cloud?.baseUrl);
+			const baseUrlRejection = await validateCloudBaseUrl(resolvedBaseUrl);
+			if (baseUrlRejection) {
+				json(res, {
+					balance: null,
+					connected: true,
+					error: baseUrlRejection
+				});
+				return true;
+			}
+			try {
+				const balance = await fetchCloudCreditsByApiKey(resolvedBaseUrl, configApiKey);
+				if (typeof balance !== "number") {
+					json(res, {
+						balance: null,
+						connected: true,
+						error: "unexpected response"
+					});
+					return true;
+				}
+				json(res, {
+					connected: true,
+					balance,
+					low: balance < 2,
+					critical: balance < .5,
+					topUpUrl: CLOUD_BILLING_URL
+				});
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : "cloud API unreachable";
+				logger.debug(`[cloud/credits] Failed to fetch balance via API key: ${msg}`);
+				json(res, {
+					balance: null,
+					connected: true,
+					error: msg
+				});
+			}
+			return true;
+		}
+		let balance;
+		const client = cloudAuth.getClient();
+		try {
+			const creditResponse = await client.get("/credits/balance");
+			const rawBalance = typeof creditResponse?.balance === "number" ? creditResponse.balance : typeof (creditResponse?.data)?.balance === "number" ? creditResponse.data.balance : void 0;
+			if (typeof rawBalance !== "number") {
+				logger.debug(`[cloud/credits] Unexpected response shape: ${JSON.stringify(creditResponse)}`);
+				json(res, {
+					balance: null,
+					connected: true,
+					error: "unexpected response"
+				});
+				return true;
+			}
+			balance = rawBalance;
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : "cloud API unreachable";
+			logger.debug(`[cloud/credits] Failed to fetch balance: ${msg}`);
+			json(res, {
+				balance: null,
+				connected: true,
+				error: msg
+			});
+			return true;
+		}
+		json(res, {
+			connected: true,
+			balance,
+			low: balance < 2,
+			critical: balance < .5,
+			topUpUrl: CLOUD_BILLING_URL
+		});
+		return true;
+	}
+	return false;
+}
+
+//#endregion
+export { handleCloudStatusRoutes };