@kenz1117/dsh-ui-usage-billing 0.9.6 → 0.9.8

package/lib/index.js

@@ -5,6 +5,8 @@ import { join } from "node:path";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
+import { settingsNamespace } from "@deepseek-ai/dsh-settings";
+import z from "@deepseek-ai/schemastery";
 //#region lib/types/client/plan-knowledge.js
 /**
 * Plan-knowledge reference (adapted from dsh-spend's `knowledge.js`, MIT):
@@ -28,7 +30,11 @@ import { credentialRef } from "@deepseek-ai/dsh-credentials";
 const PLAN_KNOWLEDGE = {
 	"opencode-go": {
 		type: "code",
-		subscriptionCny: 70,
+		subscription: {
+			amount: 10,
+			currency: "USD",
+			period: "month"
+		},
 		tier: {
 			amount: 10,
 			currency: "USD",
@@ -38,7 +44,11 @@ const PLAN_KNOWLEDGE = {
 	},
 	opencode: {
 		type: "code",
-		subscriptionCny: 70,
+		subscription: {
+			amount: 10,
+			currency: "USD",
+			period: "month"
+		},
 		tier: {
 			amount: 10,
 			currency: "USD",
@@ -46,67 +56,59 @@ const PLAN_KNOWLEDGE = {
 			label: "周额度 $30"
 		}
 	},
-	"kimi-coding": {
-		type: "code",
-		subscriptionCny: 0
-	},
-	"zai-coding-cn": {
-		type: "code",
-		subscriptionCny: 0
-	},
-	"zai-coding": {
-		type: "code",
-		subscriptionCny: 0
-	},
-	"qwen-token-plan": {
-		type: "code",
-		subscriptionCny: 0
-	},
-	"qwen-token-plan-cn": {
-		type: "code",
-		subscriptionCny: 0
-	},
-	"xiaomi-token-plan-ams": {
-		type: "code",
-		subscriptionCny: 0
-	},
-	"xiaomi-token-plan-cn": {
-		type: "code",
-		subscriptionCny: 0
-	},
-	"xiaomi-token-plan-sgp": {
-		type: "code",
-		subscriptionCny: 0
-	},
-	"volcengine-token-plan": {
-		type: "code",
-		subscriptionCny: 0
-	},
-	"ark-token-plan": {
-		type: "code",
-		subscriptionCny: 0
-	},
-	"doubao-token-plan": {
-		type: "code",
-		subscriptionCny: 0
-	},
-	"minimax": {
-		type: "code",
-		subscriptionCny: 0
-	},
-	"minimax-token-plan": {
-		type: "code",
-		subscriptionCny: 0
-	}
+	"kimi-coding": { type: "code" },
+	"zai-coding-cn": { type: "code" },
+	"zai-coding": { type: "code" },
+	"qwen-token-plan": { type: "code" },
+	"qwen-token-plan-cn": { type: "code" },
+	"xiaomi-token-plan-ams": { type: "code" },
+	"xiaomi-token-plan-cn": { type: "code" },
+	"xiaomi-token-plan-sgp": { type: "code" },
+	"volcengine-token-plan": { type: "code" },
+	"ark-token-plan": { type: "code" },
+	"doubao-token-plan": { type: "code" },
+	"minimax": { type: "code" },
+	"minimax-token-plan": { type: "code" }
+};
+/**
+* 订阅/plan provider id 变体 → PLAN_KNOWLEDGE 规范键（引用 dsh-spend 的别名归一化）。
+* 部署配置的订阅 provider id 写法不一（glm/zhipu/bigmodel、ark/volcengine、
+* kimi/moonshot、xiaomi…），先归一化再匹配，提升"自动识别"覆盖率。
+* 注意：裸 qwen/dashscope/tongyi 等是按量 API（token 计费）而非订阅，不归一到
+* 订阅键——只有显式 token-plan 后缀才由 SUBSCRIPTION_ID_RE 判定为订阅。
+*/
+const PLAN_PROVIDER_ALIASES = {
+	"glm": "zai-coding-cn",
+	"bigmodel": "zai-coding-cn",
+	"zhipu": "zai-coding-cn",
+	"zhipuai": "zai-coding-cn",
+	"zai": "zai-coding",
+	"ark": "volcengine-token-plan",
+	"volcengine": "volcengine-token-plan",
+	"doubao": "doubao-token-plan",
+	"moonshot": "kimi-coding",
+	"kimi": "kimi-coding",
+	"xiaomi": "xiaomi-token-plan-cn",
+	"opencode": "opencode-go"
 };
+/** 归一化订阅 provider id：别名命中则映射到规范键，否则原样返回。 */
+function normalizePlanProvider(providerId) {
+	if (providerId === "") return providerId;
+	return PLAN_PROVIDER_ALIASES[providerId] ?? providerId;
+}
 /** provider id（llm-pi-ai 设置键）→ plan 知识；未命中默认 token。 */
 function planTypeOf(providerId) {
-	return PLAN_KNOWLEDGE[providerId]?.type ?? "token";
+	return PLAN_KNOWLEDGE[normalizePlanProvider(providerId)]?.type ?? "token";
 }
-/** 订阅月费（人民币元）；非 code 或未配置时为 0。 */
-function subscriptionCnyOf(providerId) {
-	const entry = PLAN_KNOWLEDGE[providerId];
-	return entry?.type === "code" ? entry.subscriptionCny ?? 0 : 0;
+/**
+* 订阅月费折算为人民币：原生币 × 实时汇率（USD→CNY）。汇率缺失时返回 0，
+* 避免用假设汇率造成失真（跨币种保护：金额统一折成 CNY 再相加）。
+*/
+function subscriptionFeeCnyOf(providerId, rate) {
+	const mount = PLAN_KNOWLEDGE[normalizePlanProvider(providerId)]?.subscription;
+	if (mount === void 0) return 0;
+	if (mount.currency === "CNY") return mount.amount;
+	return rate !== void 0 && rate > 0 ? mount.amount * rate : 0;
 }
 const FALLBACK_RATES = [
 	{
@@ -956,6 +958,46 @@ const DEFAULT_SUBSCRIPTION_PROVIDERS = [
 function isOfficialProvider(provider) {
 	return /^deepseek(?:-[a-z0-9-]+)?$/i.test(provider.trim());
 }
+/** 由 baseURL 归一化出站点 origin（协议 + 主机 + 端口）；解析失败回退原值。 */
+function siteOriginOf(baseURL) {
+	try {
+		return new URL(baseURL).origin;
+	} catch {
+		return baseURL;
+	}
+}
+/**
+* 把一个 provider 路由归类为站点引用。判定顺序（与路由在 provider 配置里的状态一致）：
+* - 路由存在于当前配置且配了 baseURL → 中转站 `site`（按 origin 归组，同站多 key 合并）；
+* - 路由存在于当前配置但无 baseURL → 厂商直连 `direct`；
+* - 路由不在当前配置里 → `unknown`（改过名 / 删除过，是「读不到」而非「直连」）。
+* @param provider - 会话日志里的 provider 路由名（request/header 的 `config.provider`）。
+* @param routes - 当前 provider 路由视图（来自 llm-pi-ai providers）。
+*/
+function siteRefOf(provider, routes) {
+	const view = routes[provider];
+	if (view !== void 0) {
+		if (view.baseURL !== void 0) return {
+			kind: "site",
+			origin: siteOriginOf(view.baseURL),
+			provider
+		};
+		return {
+			kind: "direct",
+			provider
+		};
+	}
+	return {
+		kind: "unknown",
+		provider
+	};
+}
+/** 站点桶的稳定 key：`site:<origin>` 与 `direct:<provider>` 分开，`unknown` 单一桶。 */
+function siteBucketKey(ref) {
+	if (ref.kind === "site") return `site:${ref.origin ?? ""}`;
+	if (ref.kind === "direct") return `direct:${ref.provider}`;
+	return "unknown";
+}
 /** Zeroed usage accumulator. */
 function emptyUsage() {
 	return {
@@ -1079,12 +1121,13 @@ function turnState(turns, turn) {
 *   (default: any `deepseek`-prefixed id). Others count as third-party.
 * @returns the per-session fold (cached by the incremental aggregator).
 */
-function foldSession(events, subscriptionProviders, officialProviderIds) {
+function foldSession(events, subscriptionProviders, officialProviderIds, routes = {}) {
 	const fold = {
 		total: emptyUsage(),
 		byModel: /* @__PURE__ */ new Map(),
 		byDay: /* @__PURE__ */ new Map(),
 		byDayModels: /* @__PURE__ */ new Map(),
+		bySite: /* @__PURE__ */ new Map(),
 		planCalls: /* @__PURE__ */ new Map(),
 		turns: [],
 		perf: [],
@@ -1099,6 +1142,7 @@ function foldSession(events, subscriptionProviders, officialProviderIds) {
 	let key = "other";
 	let subscription = false;
 	let official = false;
+	let siteBucket = "unknown";
 	const turns = /* @__PURE__ */ new Map();
 	const steps = /* @__PURE__ */ new Map();
 	let lastOpenStepKey;
@@ -1143,6 +1187,7 @@ function foldSession(events, subscriptionProviders, officialProviderIds) {
 			key = resolveCatalogKey(model);
 			subscription = subscriptionProviders.has(provider);
 			official = officialProviderIds === void 0 ? isOfficialProvider(provider) : officialProviderIds.has(provider);
+			siteBucket = siteBucketKey(siteRefOf(provider, routes));
 			if (lastOpenStepKey !== void 0) {
 				const stepState = steps.get(lastOpenStepKey);
 				if (stepState !== void 0 && stepState.requestTime === void 0) stepState.requestTime = event.time;
@@ -1172,6 +1217,7 @@ function foldSession(events, subscriptionProviders, officialProviderIds) {
 		foldUsage(usageCell(fold.byModel, modelKey), usage, modelKey, subscription, event.time, official);
 		foldUsage(usageCell(fold.byDay, day), usage, modelKey, subscription, event.time, official);
 		foldUsage(modelDayCell(fold.byDayModels, day, modelKey), usage, modelKey, subscription, event.time, official);
+		foldUsage(usageCell(fold.bySite, siteBucket), usage, modelKey, subscription, event.time, official);
 		if (subscription) fold.planCalls.set(modelKey, (fold.planCalls.get(modelKey) ?? 0) + 1);
 		const turn = event.data.turn ?? -1;
 		const state = turnState(turns, turn);
@@ -1287,9 +1333,12 @@ function percentile(values, p) {
 function createUsageAggregator(persistence, options = {}) {
 	const subscriptionProviders = new Set(options.subscriptionProviders ?? DEFAULT_SUBSCRIPTION_PROVIDERS);
 	const officialProviderIds = options.officialProviderIds === void 0 ? void 0 : new Set(options.officialProviderIds);
+	const maxCacheSessions = options.maxCacheSessions ?? 400;
 	const cache = /* @__PURE__ */ new Map();
 	let lastDoc;
 	let lastAt = 0;
+	/** 每次聚合取最新的 provider 路由视图（中转站零配置发现）；缺省按空处理（全部未知路由）。 */
+	const routesOf = () => options.resolveRoutes?.() ?? {};
 	/** 失效键：日志文件的 mtime+size；拿不到（后端无 locate / 文件丢失）时每次重折。 */
 	const stampOf = async (meta) => {
 		const location = persistence.locate?.(meta);
@@ -1314,6 +1363,8 @@ function createUsageAggregator(persistence, options = {}) {
 			const stamp = await stampOf(meta);
 			const hit = cache.get(id);
 			if (hit !== void 0 && stamp !== null && hit.stamp === stamp) {
+				cache.delete(id);
+				cache.set(id, hit);
 				folds.push({
 					meta,
 					fold: hit.fold
@@ -1322,7 +1373,9 @@ function createUsageAggregator(persistence, options = {}) {
 			}
 			try {
 				const { events } = await persistence.readFrom(meta.id, 0);
-				const fold = foldSession(events, subscriptionProviders, officialProviderIds);
+				const after = await stampOf(meta);
+				if (stamp !== null && after !== stamp) continue;
+				const fold = foldSession(events, subscriptionProviders, officialProviderIds, routesOf());
 				cache.set(id, {
 					stamp,
 					fold
@@ -1337,11 +1390,17 @@ function createUsageAggregator(persistence, options = {}) {
 			}
 		}
 		for (const key of [...cache.keys()]) if (!seen.has(key)) cache.delete(key);
+		while (cache.size > maxCacheSessions) {
+			const oldest = cache.keys().next();
+			if (oldest.done === true) break;
+			cache.delete(oldest.value);
+		}
 		if (skipped.length > 0) console.warn(`[usage-billing] aggregated ${folds.length} sessions, skipped ${skipped.length} unreadable:`, skipped);
 		const total = emptyUsage();
 		const byModel = /* @__PURE__ */ new Map();
 		const byDay = /* @__PURE__ */ new Map();
 		const byDayModels = /* @__PURE__ */ new Map();
+		const bySite = /* @__PURE__ */ new Map();
 		const planCalls = /* @__PURE__ */ new Map();
 		const sessionRows = [];
 		const turnRows = [];
@@ -1364,6 +1423,7 @@ function createUsageAggregator(persistence, options = {}) {
 			for (const [modelKey, cell] of fold.byModel) mergeUsageInto(usageCell(byModel, modelKey), cell);
 			for (const [day, cell] of fold.byDay) mergeUsageInto(usageCell(byDay, day), cell);
 			for (const [day, models] of fold.byDayModels) for (const [modelKey, cell] of models) mergeUsageInto(modelDayCell(byDayModels, day, modelKey), cell);
+			for (const [siteKey, cell] of fold.bySite) mergeUsageInto(usageCell(bySite, siteKey), cell);
 			for (const [modelKey, count] of fold.planCalls) planCalls.set(modelKey, (planCalls.get(modelKey) ?? 0) + count);
 			for (const sample of fold.perf) {
 				let modelAccum = perfModel.get(sample.model);
@@ -1395,7 +1455,7 @@ function createUsageAggregator(persistence, options = {}) {
 				sessionId,
 				...row
 			});
-			const wsName = workspaceNameOf(meta.cwd);
+			const wsName = options.resolveWorkspaceTitle !== void 0 && meta.cwd !== void 0 ? options.resolveWorkspaceTitle(meta.cwd) ?? workspaceNameOf(meta.cwd) : workspaceNameOf(meta.cwd);
 			const ws = workspaceMap.get(wsName) ?? {
 				name: wsName,
 				calls: 0,
@@ -1459,6 +1519,7 @@ function createUsageAggregator(persistence, options = {}) {
 			bySession: sessionRows.slice(0, 100),
 			byTurn: turnRows.slice(0, 200),
 			byWorkspace: workspaces.slice(0, 100),
+			...bySite.size === 0 ? {} : { bySite: toRecord(bySite) },
 			...perf === void 0 ? {} : { perf },
 			byRole: (() => {
 				const chars = roles.userChars + roles.toolChars;
@@ -1475,24 +1536,110 @@ function createUsageAggregator(persistence, options = {}) {
 	} };
 }
 //#endregion
+//#region lib/types/resilience.js
+/**
+* 上游网络请求的稳定性工具：有限重试（指数退避）与每平台熔断冷却门。
+*
+* 计费插件对三类上游做实时请求——pricing（汇率 / OpenRouter / models.dev）、
+* balance（各厂商余额）、subscriptions（各订阅额度）。单次失败会被调用方降级，
+* 但反复的瞬时失败（网络波动 / 5xx / 429）会让 30 秒轮询每次打满超时。这里提供
+* 两个纯工具：`withRetry` 对可重试错误做指数退避，`createCooldownGate` 在单一
+* 上游连续失败后短路一段时间，避免把请求打到已不可用的服务上。
+*/
+/** 是否是可重试的错误：网络性失败（TypeError / Abort / Timeout）或 5xx / 429。
+*  401 / 403 鉴权失败与 404 不可重试——重试只放大错误、不会变好。 */
+function isRetryableError(error) {
+	if (error instanceof Error) {
+		if (error.name === "AbortError" || error.name === "TimeoutError") return true;
+		if (error instanceof TypeError) return true;
+		const status = error.httpStatus;
+		if (typeof status === "number") return status === 429 || status >= 500;
+	}
+	return false;
+}
+/** 休眠指定毫秒（Promise 化 setTimeout）。 */
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* 对一次上游请求做有限重试：可重试错误时按指数退避（+同量级抖动）重试。
+* @param fn - 发起请求的异步函数。
+* @param options - 重试策略（见 {@link RetryOptions}）。
+* @returns fn 的结果；重试耗尽后抛出最后一次错误。
+*/
+async function withRetry(fn, options = {}) {
+	const { retries = 1, baseDelayMs = 250, maxDelayMs = 2e3, shouldRetry = isRetryableError } = options;
+	let lastError;
+	for (let attempt = 0; attempt <= retries; attempt += 1) try {
+		return await fn();
+	} catch (error) {
+		lastError = error;
+		if (attempt >= retries || !shouldRetry(error)) throw error;
+		const delay = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
+		await sleep(delay / 2 + Math.random() * (delay / 2));
+	}
+	throw lastError;
+}
+/** 每平台冷熔断：连续失败达阈值后短路一段真实时间，成功后复位。 */
+function createCooldownGate(options = {}) {
+	const { failures = 3, cooldownMs = 3e4 } = options;
+	const state = /* @__PURE__ */ new Map();
+	return {
+		check(key) {
+			const s = state.get(key);
+			if (s === void 0) return true;
+			if (s.until > 0 && Date.now() < s.until) return false;
+			return true;
+		},
+		fail(key) {
+			const s = state.get(key) ?? {
+				count: 0,
+				until: 0
+			};
+			s.count += 1;
+			if (s.count >= failures) {
+				s.until = Date.now() + cooldownMs;
+				s.count = 0;
+			}
+			state.set(key, s);
+		},
+		success(key) {
+			state.delete(key);
+		}
+	};
+}
+//#endregion
 //#region lib/types/balance.js
 /**
 * Account-balance queries for the billing dashboard.
 *
 * Only providers with a public balance endpoint can report one. Today that is
-* DeepSeek (`GET https://api.deepseek.com/user/balance`) and Moonshot/Kimi
-* (`GET https://api.moonshot.cn/v1/users/me/balance`), both Bearer 鉴权 with a
-* documented JSON shape; the other mainstream providers expose no standard
-* balance API (or require a non-Bearer auth flow), so their rows in the model
-* table show an unavailable state. The lookup map below is the extension point
-* for future providers.
+* DeepSeek, Moonshot/Kimi, StepFun, SiliconFlow, and xAI (Grok) — all Bearer
+* 鉴权 with a documented JSON shape; the other mainstream providers expose no
+* standard balance API (or require a non-Bearer auth flow), so their rows in
+* the model table show an unavailable state. The lookup map below is the
+* extension point for future providers.
 *
 * API keys are read from the `llm-pi-ai` settings namespace (`providers.<id>.apiKeyEnv`),
 * the same source the subscription adapter uses, so a deployment configures a
 * provider's key once and every surface reuses it.
 */
 /** Abort a balance fetch when the upstream hangs beyond this budget. */
-const FETCH_TIMEOUT_MS$1 = 8e3;
+const FETCH_TIMEOUT_MS$2 = 8e3;
+/**
+* 每平台熔断门：单个 provider 连续可重试失败（网络波动 / 5xx / 429）达阈值后
+* 短路一段真实时间，避免 30 秒轮询在已不可用的上游上反复打满超时。
+* 鉴权失败（unauthorized）是配置问题而非暂时故障，不计入熔断。
+*/
+const balanceGate = createCooldownGate({
+	failures: 3,
+	cooldownMs: 6e4
+});
+/** 自定义 Provider 余额的熔断门：按端点 URL 独立熔断（各配置端点互不干扰）。 */
+const customGate = createCooldownGate({
+	failures: 3,
+	cooldownMs: 6e4
+});
 /** DeepSeek 官方余额接口（官方文档 api-docs.deepseek.com/api/get-user-balance）。 */
 const DEEPSEEK_BALANCE_URL = "https://api.deepseek.com/user/balance";
 /** Moonshot/Kimi 官方余额接口（platform.kimi.com/docs/api/balance）。 */
@@ -1501,6 +1648,10 @@ const MOONSHOT_BALANCE_URL = "https://api.moonshot.cn/v1/users/me/balance";
 const STEPFUN_BALANCE_URL = "https://api.stepfun.com/v1/accounts";
 /** 硅基流动 SiliconFlow 官方用户信息接口（docs.siliconflow.cn/cn/api-reference/user/query-user-info）。 */
 const SILICONFLOW_BALANCE_URL = "https://api.siliconflow.cn/v1/user/info";
+/** xAI 官方账单接口（docs.x.ai/developers/api/credits）；total.val 为美分。 */
+const XAI_CREDITS_URL = "https://api.x.ai/v1/billing/credits";
+/** 智谱 GLM（大模型国内域）官方余额接口（open.bigmodel.cn/api/paas/v4/balance）。 */
+const ZHIPU_BALANCE_URL = "https://open.bigmodel.cn/api/paas/v4/balance";
 /** 数字归一化：接口返回的余额是字符串（如 `"110.00"`），统一转 number。 */
 function toNumber(value) {
 	if (typeof value === "number" && Number.isFinite(value)) return value;
@@ -1528,35 +1679,60 @@ async function queryBearerBalance(ctx, url, apiKeyEnv, provider, displayName, pa
 		displayName,
 		error: "unconfigured"
 	};
-	const controller = new AbortController();
-	const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS$1);
+	if (!balanceGate.check(provider)) return {
+		provider,
+		displayName,
+		error: "unreachable"
+	};
+	const doRequest = async () => {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS$2);
+		try {
+			const response = await fetch(url, {
+				headers: {
+					accept: "application/json",
+					authorization: `Bearer ${hit.value}`
+				},
+				signal: controller.signal
+			});
+			if (response.status === 401 || response.status === 403) return {
+				provider,
+				displayName,
+				error: "unauthorized"
+			};
+			if (!response.ok) {
+				const error = /* @__PURE__ */ new Error(`HTTP ${String(response.status)}`);
+				error.httpStatus = response.status;
+				throw error;
+			}
+			const row = parse(await response.json());
+			if (row.totalBalance === void 0 && row.grantedBalance === void 0 && row.toppedUpBalance === void 0 && row.isAvailable === void 0) {
+				console.warn(`[usage-billing] balance response drifted for ${displayName}: no balance field parsed from ${url}`);
+				return {
+					...row,
+					error: "invalid"
+				};
+			}
+			return row;
+		} finally {
+			clearTimeout(timer);
+		}
+	};
 	try {
-		const response = await fetch(url, {
-			headers: {
-				accept: "application/json",
-				authorization: `Bearer ${hit.value}`
-			},
-			signal: controller.signal
+		const row = await withRetry(doRequest, {
+			retries: 1,
+			baseDelayMs: 250,
+			maxDelayMs: 2e3
 		});
-		if (response.status === 401 || response.status === 403) return {
-			provider,
-			displayName,
-			error: "unauthorized"
-		};
-		if (!response.ok) return {
-			provider,
-			displayName,
-			error: "unreachable"
-		};
-		return parse(await response.json());
+		balanceGate.success(provider);
+		return row;
 	} catch {
+		balanceGate.fail(provider);
 		return {
 			provider,
 			displayName,
 			error: "unreachable"
 		};
-	} finally {
-		clearTimeout(timer);
 	}
 }
 /**
@@ -1648,6 +1824,45 @@ function querySiliconFlow(ctx, apiKeyEnv) {
 		};
 	});
 }
+/**
+* Query the xAI (Grok) credit balance.
+* @param ctx - host context carrying the credentials seam.
+* @param apiKeyEnv - credential reference resolving the xAI API key.
+* @returns the balance row, or an error row when the key/endpoint misbehaves.
+*/
+function queryXai(ctx, apiKeyEnv) {
+	return queryBearerBalance(ctx, XAI_CREDITS_URL, apiKeyEnv, "xAI", "xAI", (data) => {
+		const cents = toNumber(data.total?.val);
+		const totalBalance = cents === void 0 ? void 0 : Math.abs(cents) / 100;
+		return {
+			provider: "xAI",
+			displayName: "xAI",
+			currency: "USD",
+			...totalBalance !== void 0 ? { totalBalance } : {}
+		};
+	});
+}
+/**
+* Query the Zhipu GLM / Z.ai (国内 bigmodel-cn 域) account balance.
+* 与订阅（zai-coding-cn 的 Coding Plan）互补：一个平台可同时有钱包余额与订阅
+* 套餐，两者各读各的（TokenLedger 同款双读姿态）。Z.ai global 域币种为 USD，
+* 本函数固定走国内 CNY 域（open.bigmodel.cn），币种不猜，仅覆盖国内域。
+* @param ctx - host context carrying the credentials seam.
+* @param apiKeyEnv - credential reference resolving the Zhipu API key.
+* @returns the balance row, or an error row when the key/endpoint misbehaves.
+*/
+function queryZhipu(ctx, apiKeyEnv) {
+	return queryBearerBalance(ctx, ZHIPU_BALANCE_URL, apiKeyEnv, "智谱 AI", "智谱 AI", (data) => {
+		const doc = data;
+		const totalBalance = toNumber(doc.balance?.available) ?? toNumber(doc.balance?.total);
+		return {
+			provider: "智谱 AI",
+			displayName: "智谱 AI",
+			currency: "CNY",
+			...totalBalance !== void 0 ? { totalBalance } : {}
+		};
+	});
+}
 const QUERIERS = [
 	{
 		route: "deepseek",
@@ -1668,6 +1883,21 @@ const QUERIERS = [
 		route: "siliconflow",
 		displayName: "硅基流动",
 		querier: querySiliconFlow
+	},
+	{
+		route: "xai",
+		displayName: "xAI",
+		querier: queryXai
+	},
+	{
+		route: "zhipu",
+		displayName: "智谱 AI",
+		querier: queryZhipu
+	},
+	{
+		route: "zai-coding-cn",
+		displayName: "智谱 AI",
+		querier: queryZhipu
 	}
 ];
 /**
@@ -1764,47 +1994,64 @@ async function queryCustomBalances(ctx, configs) {
 			displayName,
 			error: "unconfigured"
 		};
-		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS$1);
+		if (!customGate.check(config.url)) return {
+			provider,
+			displayName,
+			error: "unreachable"
+		};
+		const doRequest = async () => {
+			const controller = new AbortController();
+			const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS$2);
+			try {
+				const response = await fetch(config.url, {
+					method: config.method ?? "GET",
+					headers: {
+						accept: "application/json",
+						...headers
+					},
+					signal: controller.signal
+				});
+				if (response.status === 401 || response.status === 403) return {
+					provider,
+					displayName,
+					error: "unauthorized"
+				};
+				if (!response.ok) {
+					const error = /* @__PURE__ */ new Error(`HTTP ${String(response.status)}`);
+					error.httpStatus = response.status;
+					throw error;
+				}
+				const remaining = evalExtract(config.extract.remaining, await response.json());
+				if (remaining === void 0) return {
+					provider,
+					displayName,
+					error: "invalid"
+				};
+				return {
+					provider,
+					displayName,
+					currency: config.unit ?? "CNY",
+					totalBalance: remaining
+				};
+			} finally {
+				clearTimeout(timer);
+			}
+		};
 		try {
-			const response = await fetch(config.url, {
-				method: config.method ?? "GET",
-				headers: {
-					accept: "application/json",
-					...headers
-				},
-				signal: controller.signal
+			const row = await withRetry(doRequest, {
+				retries: 1,
+				baseDelayMs: 250,
+				maxDelayMs: 2e3
 			});
-			if (response.status === 401 || response.status === 403) return {
-				provider,
-				displayName,
-				error: "unauthorized"
-			};
-			if (!response.ok) return {
-				provider,
-				displayName,
-				error: "unreachable"
-			};
-			const remaining = evalExtract(config.extract.remaining, await response.json());
-			if (remaining === void 0) return {
-				provider,
-				displayName,
-				error: "unreachable"
-			};
-			return {
-				provider,
-				displayName,
-				currency: config.unit ?? "CNY",
-				totalBalance: remaining
-			};
+			customGate.success(config.url);
+			return row;
 		} catch {
+			customGate.fail(config.url);
 			return {
 				provider,
 				displayName,
 				error: "unreachable"
 			};
-		} finally {
-			clearTimeout(timer);
 		}
 	}));
 }
@@ -1820,7 +2067,13 @@ async function queryCustomBalances(ctx, configs) {
 * catalog for the rest — a total outage answers `{ source: 'builtin' }`.
 */
 /** Abort a fetch when the upstream hangs beyond this budget. */
-const FETCH_TIMEOUT_MS = 8e3;
+const FETCH_TIMEOUT_MS$1 = 8e3;
+/** 每平台熔断门：单个定价上游连续可重试失败（网络 / 5xx / 429）达阈值后短路，
+*  避免 6 小时刷新循环与每次启动在已故障的上游上反复打满超时。按 URL 独立。 */
+const pricingGate = createCooldownGate({
+	failures: 3,
+	cooldownMs: 6e4
+});
 /**
 * USD → CNY 汇率源，按顺序尝试：国内可达的腾讯财经行情（免 key、`~` 分隔
 * 第 4 个字段为价格）优先，国外 open.er-api.com 兜底。任一源失败自动落到
@@ -1903,18 +2156,35 @@ const ROUTER_ID_HINTS = {
 	"llama": ["llama-4"],
 	"kimi": ["kimi-k2"]
 };
-/** GET a URL's text body with a hard timeout; null on any failure. */
+/** GET a URL's text body with a hard timeout and retry; null on any failure. */
 async function fetchText(url) {
-	const controller = new AbortController();
-	const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+	if (!pricingGate.check(url)) return null;
+	const doFetch = async () => {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS$1);
+		try {
+			const response = await fetch(url, { signal: controller.signal });
+			if (!response.ok) {
+				const error = /* @__PURE__ */ new Error(`HTTP ${String(response.status)}`);
+				error.httpStatus = response.status;
+				throw error;
+			}
+			return await response.text();
+		} finally {
+			clearTimeout(timer);
+		}
+	};
 	try {
-		const response = await fetch(url, { signal: controller.signal });
-		if (!response.ok) return null;
-		return await response.text();
+		const text = await withRetry(doFetch, {
+			retries: 1,
+			baseDelayMs: 250,
+			maxDelayMs: 2e3
+		});
+		pricingGate.success(url);
+		return text;
 	} catch {
+		pricingGate.fail(url);
 		return null;
-	} finally {
-		clearTimeout(timer);
 	}
 }
 /** GET a JSON endpoint with a hard timeout; null on any failure. */
@@ -1941,7 +2211,10 @@ async function fetchRouterModels() {
 	const data = await fetchJson(ROUTER_URL);
 	if (data === null || typeof data !== "object") return void 0;
 	const list = data.data;
-	if (!Array.isArray(list)) return void 0;
+	if (!Array.isArray(list)) {
+		console.warn("[usage-billing] openrouter models response drifted: expected a `data` array");
+		return;
+	}
 	const models = [];
 	for (const item of list) {
 		if (item === null || typeof item !== "object") continue;
@@ -2061,6 +2334,13 @@ async function fetchLivePricing() {
 * "no quota API" marker rather than hidden. API keys come from the `llm-pi-ai`
 * settings namespace (`apiKeyEnv` refs) resolved through the credentials seam.
 */
+/** 每平台熔断门：某个订阅适配器连续可重试失败（网络 / 5xx / 429）达阈值后
+*  短路由不可用，避免 30 秒轮询对已故障的上游反复打满超时。鉴权失败（unauthorized）
+*  是配置问题，不计入熔断。 */
+const subscriptionGate = createCooldownGate({
+	failures: 3,
+	cooldownMs: 6e4
+});
 /** 空凭据：全部未配置时的初始值。 */
 const EMPTY_SUBSCRIPTION_KEYS = {
 	kimiApiKey: "",
@@ -2132,7 +2412,7 @@ function identifySubscriptionPlans(providers) {
 }
 const DEFAULT_TIMEOUT_MS = 15e3;
 /** Number, or null when the value is not a finite number (nor numeric string). */
-function numberOrNull(value) {
+function numberOrNull$1(value) {
 	if (typeof value === "number" && Number.isFinite(value)) return value;
 	if (typeof value === "string" && value.trim() !== "") {
 		const parsed = Number(value);
@@ -2141,11 +2421,11 @@ function numberOrNull(value) {
 	return null;
 }
 /** Clamp a percentage to 0–100. */
-function clampPercent(value) {
+function clampPercent$1(value) {
 	return value === null ? null : Math.max(0, Math.min(100, value));
 }
 /** Round to one decimal. */
-function round1(value) {
+function round1$1(value) {
 	return Math.round(value * 10) / 10;
 }
 /** Number → ISO string (seconds treated as epoch seconds, ms as epoch ms). */
@@ -2159,7 +2439,7 @@ function toIso(value) {
 	return Number.isNaN(date.getTime()) ? null : date.toISOString();
 }
 /** Map a fetch error to a stable status. */
-function statusOf(error) {
+function statusOf$1(error) {
 	if (error instanceof Error) {
 		if (error.name === "TimeoutError" || error.name === "AbortError") return "unavailable";
 		const status = error.httpStatus;
@@ -2169,38 +2449,46 @@ function statusOf(error) {
 	}
 	return "unavailable";
 }
-/** One JSON fetch with a timeout, mapping HTTP failures to typed errors. */
+/** One JSON fetch with a timeout, mapping HTTP failures to typed errors.
+*  可重试错误（网络 / 5xx / 429）用指数退避重试一次；401/403/404 不重试。 */
 async function requestJson(url, init, timeoutMs) {
-	const response = await fetch(url, {
-		...init,
-		signal: AbortSignal.timeout(timeoutMs)
+	const doFetch = async () => {
+		const response = await fetch(url, {
+			...init,
+			signal: AbortSignal.timeout(timeoutMs)
+		});
+		if (!response.ok) {
+			const error = /* @__PURE__ */ new Error(`HTTP ${String(response.status)}`);
+			error.httpStatus = response.status;
+			throw error;
+		}
+		return await response.json();
+	};
+	return await withRetry(doFetch, {
+		retries: 1,
+		baseDelayMs: 250,
+		maxDelayMs: 2e3
 	});
-	if (!response.ok) {
-		const error = /* @__PURE__ */ new Error(`HTTP ${String(response.status)}`);
-		error.httpStatus = response.status;
-		throw error;
-	}
-	return await response.json();
 }
 /** Parse one Kimi limit window entry. */
 function kimiWindow(value, kind) {
 	if (value === null || typeof value !== "object") return null;
 	const record = value;
-	const limit = numberOrNull(record.limit ?? record.total);
-	const remaining = numberOrNull(record.remaining);
-	if (remaining === null && limit === null && numberOrNull(record.percentage ?? record.usedPercent ?? record.used_percent) === null) return null;
+	const limit = numberOrNull$1(record.limit ?? record.total);
+	const remaining = numberOrNull$1(record.remaining);
+	if (remaining === null && limit === null && numberOrNull$1(record.percentage ?? record.usedPercent ?? record.used_percent) === null) return null;
 	const hasLimit = limit !== null && limit > 0;
 	let usedPercent;
-	if (hasLimit) usedPercent = round1(clampPercent((limit - (remaining ?? 0)) / limit * 100) ?? 0);
+	if (hasLimit) usedPercent = round1$1(clampPercent$1((limit - (remaining ?? 0)) / limit * 100) ?? 0);
 	else {
-		const percent = numberOrNull(record.percentage ?? record.usedPercent ?? record.used_percent);
-		usedPercent = percent !== null ? round1(clampPercent(percent) ?? 0) : remaining === null || remaining <= 0 ? 100 : 0;
+		const percent = numberOrNull$1(record.percentage ?? record.usedPercent ?? record.used_percent);
+		usedPercent = percent !== null ? round1$1(clampPercent$1(percent) ?? 0) : remaining === null || remaining <= 0 ? 100 : 0;
 	}
 	const resetsAt = toIso(record.resetTime ?? record.reset_time ?? record.resetsAt);
 	return {
 		kind,
 		usedPercent,
-		remainingPercent: round1(100 - usedPercent),
+		remainingPercent: round1$1(100 - usedPercent),
 		...remaining !== null ? { remaining } : {},
 		...resetsAt === null ? {} : { resetsAt }
 	};
@@ -2242,15 +2530,15 @@ async function collectKimi(keys, config, timeoutMs) {
 		return {
 			provider: config.provider,
 			displayName: "Kimi For Coding",
-			status: statusOf(error),
+			status: statusOf$1(error),
 			windows: []
 		};
 	}
 }
 /** Window length in minutes for a Z.ai limit row; null when unknown. */
 function zaiWindowMinutes(limit) {
-	const unit = numberOrNull(limit.unit);
-	const number = numberOrNull(limit.number);
+	const unit = numberOrNull$1(limit.unit);
+	const number = numberOrNull$1(limit.number);
 	if (unit === null || number === null || number <= 0) return null;
 	if (unit === 5) return number;
 	if (unit === 3) return number * 60;
@@ -2260,14 +2548,14 @@ function zaiWindowMinutes(limit) {
 }
 /** Used percent for a Z.ai limit row. */
 function zaiUsedPercent(limit) {
-	const total = numberOrNull(limit.usage);
-	const remaining = numberOrNull(limit.remaining);
-	const current = numberOrNull(limit.currentValue ?? limit.current_value);
+	const total = numberOrNull$1(limit.usage);
+	const remaining = numberOrNull$1(limit.remaining);
+	const current = numberOrNull$1(limit.currentValue ?? limit.current_value);
 	if (total !== null && total > 0) {
 		const used = remaining === null ? current : current === null ? total - remaining : Math.max(total - remaining, current);
-		if (used !== null) return clampPercent(Math.max(0, Math.min(total, used)) / total * 100);
+		if (used !== null) return clampPercent$1(Math.max(0, Math.min(total, used)) / total * 100);
 	}
-	return clampPercent(numberOrNull(limit.percentage ?? limit.usedPercent ?? limit.used_percent));
+	return clampPercent$1(numberOrNull$1(limit.percentage ?? limit.usedPercent ?? limit.used_percent));
 }
 /** One Z.ai quota window row. */
 function zaiWindow(limit, kind, fallbackReset = null) {
@@ -2276,8 +2564,8 @@ function zaiWindow(limit, kind, fallbackReset = null) {
 	const resetsAt = toIso(limit.nextResetTime ?? limit.next_reset_time) ?? fallbackReset;
 	return {
 		kind,
-		usedPercent: round1(usedPercent),
-		remainingPercent: round1(100 - usedPercent),
+		usedPercent: round1$1(usedPercent),
+		remainingPercent: round1$1(100 - usedPercent),
 		...resetsAt === null ? {} : { resetsAt }
 	};
 }
@@ -2362,7 +2650,7 @@ async function collectZai(keys, config, timeoutMs) {
 		return {
 			provider: config.provider,
 			displayName: "Z.ai Coding Plan",
-			status: statusOf(error),
+			status: statusOf$1(error),
 			windows: []
 		};
 	}
@@ -2372,20 +2660,20 @@ function goWindow(value, kind) {
 	if (value === null || typeof value !== "object") return null;
 	const record = value;
 	const percentSource = record.usagePercent ?? record.usedPercent ?? record.percentUsed ?? record.percentage ?? record.percent;
-	let usedPercent = clampPercent(numberOrNull(percentSource));
+	let usedPercent = clampPercent$1(numberOrNull$1(percentSource));
 	if (usedPercent === null) {
-		const used = numberOrNull(record.used ?? record.consumed);
-		const limit = numberOrNull(record.limit ?? record.total ?? record.quota);
-		if (used !== null && limit !== null && limit > 0) usedPercent = clampPercent(used / limit * 100);
+		const used = numberOrNull$1(record.used ?? record.consumed);
+		const limit = numberOrNull$1(record.limit ?? record.total ?? record.quota);
+		if (used !== null && limit !== null && limit > 0) usedPercent = clampPercent$1(used / limit * 100);
 	}
 	if (usedPercent === null) return null;
 	if (usedPercent <= 1 && usedPercent >= 0 && record.percent === void 0 && percentSource !== void 0) usedPercent *= 100;
-	const resetSeconds = numberOrNull(record.resetInSec ?? record.resetInSeconds ?? record.resetSeconds);
+	const resetSeconds = numberOrNull$1(record.resetInSec ?? record.resetInSeconds ?? record.resetSeconds);
 	const resetsAt = resetSeconds === null ? toIso(record.resetAt ?? record.resetsAt ?? record.nextReset) : new Date(Date.now() + Math.max(0, resetSeconds) * 1e3).toISOString();
 	return {
 		kind,
-		usedPercent: round1(clampPercent(usedPercent) ?? 0),
-		remainingPercent: round1(100 - (clampPercent(usedPercent) ?? 0)),
+		usedPercent: round1$1(clampPercent$1(usedPercent) ?? 0),
+		remainingPercent: round1$1(100 - (clampPercent$1(usedPercent) ?? 0)),
 		...resetsAt === null ? {} : { resetsAt }
 	};
 }
@@ -2425,7 +2713,7 @@ async function collectOpenCodeGo(keys, config, timeoutMs) {
 		return {
 			provider: config.provider,
 			displayName: "OpenCode Go",
-			status: statusOf(error),
+			status: statusOf$1(error),
 			windows: []
 		};
 	}
@@ -2442,14 +2730,14 @@ async function collectOpenCodeGo(keys, config, timeoutMs) {
 function minmaxWindow(record, kind, remainPctKey, statusKey, resetKey) {
 	if (record === void 0) return null;
 	if (Number(record[statusKey]) === 3) return null;
-	const remain = numberOrNull(record[remainPctKey]);
+	const remain = numberOrNull$1(record[remainPctKey]);
 	if (remain === null) return null;
-	const usedPercent = round1(clampPercent(100 - (remain <= 1 ? remain * 100 : remain)) ?? 0);
+	const usedPercent = round1$1(clampPercent$1(100 - (remain <= 1 ? remain * 100 : remain)) ?? 0);
 	const resetsAt = toIso(record[resetKey]);
 	return {
 		kind,
 		usedPercent,
-		remainingPercent: round1(100 - usedPercent),
+		remainingPercent: round1$1(100 - usedPercent),
 		...resetsAt === null ? {} : { resetsAt }
 	};
 }
@@ -2496,7 +2784,7 @@ async function collectMiniMax(keys, config, timeoutMs) {
 		return {
 			provider: config.provider,
 			displayName: "MiniMax Coding Plan",
-			status: statusOf(error),
+			status: statusOf$1(error),
 			windows: []
 		};
 	}
@@ -2510,15 +2798,15 @@ async function collectMiniMax(keys, config, timeoutMs) {
 function parseOpenRouterCredits(body) {
 	const doc = body ?? {};
 	const data = doc.data ?? doc;
-	const total = numberOrNull(data.total_credits ?? data.credits);
-	const used = numberOrNull(data.total_usage ?? data.usage);
+	const total = numberOrNull$1(data.total_credits ?? data.credits);
+	const used = numberOrNull$1(data.total_usage ?? data.usage);
 	if (total === null || total <= 0 || used === null) return [];
-	const usedPercent = round1(clampPercent(used / total * 100) ?? 0);
+	const usedPercent = round1$1(clampPercent$1(used / total * 100) ?? 0);
 	const resetsAt = toIso(data.resets_at ?? data.next_reset_time);
 	return [{
 		kind: "billing",
 		usedPercent,
-		remainingPercent: round1(100 - usedPercent),
+		remainingPercent: round1$1(100 - usedPercent),
 		...resetsAt === null ? {} : { resetsAt }
 	}];
 }
@@ -2547,7 +2835,7 @@ async function collectOpenRouter(keys, config, timeoutMs) {
 		return {
 			provider: config.provider,
 			displayName: "OpenRouter",
-			status: statusOf(error),
+			status: statusOf$1(error),
 			windows: []
 		};
 	}
@@ -2562,18 +2850,297 @@ async function collectOpenRouter(keys, config, timeoutMs) {
 * @returns the quotas in plan order (unknown providers degrade to `unavailable`).
 */
 async function collectSubscriptions(keys, plans = [], timeoutMs = DEFAULT_TIMEOUT_MS) {
-	return await Promise.all(plans.map((plan) => {
+	return await Promise.all(plans.map(async (plan) => {
 		const adapter = SUBSCRIPTION_ADAPTERS[plan.provider];
-		if (adapter === void 0) return Promise.resolve({
+		if (adapter === void 0) return {
 			provider: plan.provider,
 			displayName: plan.provider,
 			status: "unavailable",
 			windows: []
-		});
-		return adapter.collect(keys, plan, timeoutMs);
+		};
+		if (!subscriptionGate.check(plan.provider)) return {
+			provider: plan.provider,
+			displayName: plan.provider,
+			status: "unavailable",
+			windows: []
+		};
+		const quota = await adapter.collect(keys, plan, timeoutMs);
+		if (quota.status === "unavailable" || quota.status === "rate-limited") subscriptionGate.fail(plan.provider);
+		else subscriptionGate.success(plan.provider);
+		return quota;
 	}));
 }
 //#endregion
+//#region lib/types/relay.js
+/**
+* 中转站额度查询（node 半区）：识别并读取 New API 系与 Sub2API 的「余额 / 额度窗口」。
+*
+* 适用场景：用户把某条 llm-pi-ai provider 路由的 `baseURL` 指向第三方中转站
+* （New API / One API / VoAPI / Sub2API 等）。这类站点不卖官方余额，卖的是
+* 按 key 的额度（used/total）或多个滚动窗口。本模块对**配了 baseURL 且有
+* apiKeyEnv** 的路由逐个探测两个已知端点，能解析出额度就返回；解析不出的
+* 静默标记 unavailable，绝不臆造金额（与 balance/subscriptions 一致的姿态）。
+*
+* 探测顺序：先 Sub2API `/v1/usage`（标准化程度高），再 New API `/api/status`；
+* 404 = 不是该套程序，继续试下一种；401/403 = 是但 key 不对（unauthorized）；
+* 网络/5xx 走熔断门短路一段时间。同一站点多把 key 是独立额度，分别列出。
+*/
+/** 单个中转站额度请求的熔断门：按 baseURL 独立熔断（各站点互不干扰）。 */
+const relayGate = createCooldownGate({
+	failures: 3,
+	cooldownMs: 6e4
+});
+/** Abort a relay fetch when the upstream hangs beyond this budget. */
+const FETCH_TIMEOUT_MS = 8e3;
+/** Number, or null when the value is not a finite number (nor numeric string). */
+function numberOrNull(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim() !== "") {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+	return null;
+}
+/** Clamp a percentage to 0–100. */
+function clampPercent(value) {
+	return value === null ? null : Math.max(0, Math.min(100, value));
+}
+/** Round to one decimal. */
+function round1(value) {
+	return Math.round(value * 10) / 10;
+}
+/** Map a fetch error to a stable status (same taxonomy as subscriptions). */
+function statusOf(error) {
+	if (error instanceof Error) {
+		if (error.name === "TimeoutError" || error.name === "AbortError") return "unavailable";
+		const status = error.httpStatus;
+		if (status === 401 || status === 403) return "unauthorized";
+		if (status === 429) return "rate-limited";
+		if (status === 404) return "unavailable";
+	}
+	return "unavailable";
+}
+/**
+* GET 一个中转站端点并返回 JSON。可重试错误（网络 / 5xx / 429）退避重试一次；
+* 401/403/404 不重试。返回 `{ ok, status, data }`，由调用方区分"不是这套程序
+* （404）"与"是但读取失败（其他非 2xx）"。
+*/
+async function fetchRelayJson(url, apiKey) {
+	const doFetch = async () => {
+		const response = await fetch(url, {
+			headers: {
+				accept: "application/json",
+				authorization: `Bearer ${apiKey}`
+			},
+			signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+		});
+		if (!response.ok) {
+			if (response.status === 404) return {
+				ok: false,
+				status: 404
+			};
+			const error = /* @__PURE__ */ new Error(`HTTP ${String(response.status)}`);
+			error.httpStatus = response.status;
+			throw error;
+		}
+		return {
+			ok: true,
+			status: response.status,
+			data: await response.json()
+		};
+	};
+	return await withRetry(doFetch, {
+		retries: 1,
+		baseDelayMs: 250,
+		maxDelayMs: 2e3
+	});
+}
+/** 新建一个额度窗口行（未解析出百分比时不产出）。 */
+function windowOf(kind, usedPercent, resetsAt) {
+	const used = clampPercent(usedPercent);
+	if (used === null) return null;
+	return {
+		kind,
+		usedPercent: round1(used),
+		remainingPercent: round1(Math.max(0, 100 - used)),
+		...resetsAt === void 0 ? {} : { resetsAt }
+	};
+}
+/**
+* 解析 Sub2API `/v1/usage` 响应：能取到 balance 或 quota/used 就识别为 sub2api。
+* 三种形态（窗口 / 分组 / 钱包余额）都宽容处理：有 `quota/total` 给出窗口，
+* 有 `balance` 给出余额，两者可同时存在。
+* @param data - `/v1/usage` 的 JSON 响应。
+* @returns 解析结果；两者都取不到返回 null（不是 Sub2API 或响应漂移）。
+*/
+function parseSub2ApiUsage(data) {
+	if (data === null || typeof data !== "object") return null;
+	const doc = data;
+	const balance = numberOrNull(doc.balance);
+	const total = numberOrNull(doc.quota ?? doc.total_quota ?? doc.limit);
+	const used = numberOrNull(doc.used_quota ?? doc.usage);
+	if (balance === null && total === null) return null;
+	const windows = [];
+	if (total !== null && used !== null) {
+		const pct = used / total * 100;
+		const window = windowOf("weekly", Number.isFinite(pct) ? pct : null);
+		if (window !== null) windows.push(window);
+	}
+	return {
+		...balance !== null ? { balance } : {},
+		...windows.length === 0 ? {} : { windows }
+	};
+}
+/**
+* 解析 New API `/api/status` 响应：New API 系（One API / VoAPI 分支）的额度是
+* 按记录行的 ratio（已用比例）。只给出窗口，不猜金额（币种防猜）。
+* @param data - `/api/status` 的 JSON 响应。
+* @returns 窗口；取不到比例返回 null（响应漂移）。
+*/
+function parseNewApiStatus(data) {
+	if (data === null || typeof data !== "object") return null;
+	const inner = data.data;
+	if (inner === null || typeof inner !== "object") return null;
+	const ratio = numberOrNull(inner.ratio);
+	const used = numberOrNull(inner.used_quota);
+	const total = numberOrNull(inner.total_quota ?? inner.quota);
+	let pct = null;
+	if (ratio !== null) pct = ratio * 100;
+	else if (total !== null && used !== null) pct = used / total * 100;
+	if (pct === null) return null;
+	const window = windowOf("billing", Number.isFinite(pct) ? pct : null);
+	return window === null ? null : { windows: [window] };
+}
+/** 归一化站点 origin（与聚合层 `siteOriginOf` 同口径）。 */
+function originOf(baseURL) {
+	try {
+		return new URL(baseURL).origin;
+	} catch {
+		return baseURL;
+	}
+}
+/** 构造端点 URL：`/v1/usage` 与 `/api/status` 都以 baseURL 为宿主解析。 */
+function endpointOf(baseURL, path) {
+	return new URL(path, baseURL).toString();
+}
+/**
+* 查询单个中转站路由的额度。先试 Sub2API，再试 New API；任一读出额度即返回。
+* @param ctx - host context carrying the credentials seam.
+* @param route - 待探测的路由（baseURL + apiKeyEnv）。
+* @returns 该路由的一行额度结果（status 标记成败）。
+*/
+async function queryRelayQuota(ctx, route) {
+	const base = {
+		route: route.route,
+		origin: originOf(route.baseURL),
+		displayName: route.displayName ?? route.route
+	};
+	if (!relayGate.check(route.baseURL)) return {
+		...base,
+		kind: "unknown",
+		status: "unavailable"
+	};
+	const hit = await ctx.credentials.resolve(credentialRef(route.apiKeyEnv));
+	if (hit === void 0 || hit.value === "") return {
+		...base,
+		kind: "unknown",
+		status: "not-configured"
+	};
+	try {
+		const sub2 = await fetchRelayJson(endpointOf(route.baseURL, "/v1/usage"), hit.value);
+		if (sub2.ok) {
+			const parsed = parseSub2ApiUsage(sub2.data);
+			if (parsed !== null) {
+				relayGate.success(route.baseURL);
+				return {
+					...base,
+					kind: "sub2api",
+					status: "ok",
+					...parsed.balance !== void 0 ? { balance: parsed.balance } : {},
+					...parsed.windows !== void 0 ? { windows: parsed.windows } : {}
+				};
+			}
+			relayGate.fail(route.baseURL);
+			return {
+				...base,
+				kind: "sub2api",
+				status: "invalid-response"
+			};
+		}
+		if (sub2.status === 401 || sub2.status === 403) {
+			relayGate.fail(route.baseURL);
+			return {
+				...base,
+				kind: "unknown",
+				status: "unauthorized"
+			};
+		}
+		const na = await fetchRelayJson(endpointOf(route.baseURL, "/api/status"), hit.value);
+		if (na.status === 401 || na.status === 403) {
+			relayGate.fail(route.baseURL);
+			return {
+				...base,
+				kind: "unknown",
+				status: "unauthorized"
+			};
+		}
+		if (na.ok) {
+			const parsed = parseNewApiStatus(na.data);
+			if (parsed !== null) {
+				relayGate.success(route.baseURL);
+				return {
+					...base,
+					kind: "new-api",
+					status: "ok",
+					...parsed.windows !== void 0 ? { windows: parsed.windows } : {}
+				};
+			}
+			relayGate.fail(route.baseURL);
+			return {
+				...base,
+				kind: "new-api",
+				status: "invalid-response"
+			};
+		}
+		relayGate.fail(route.baseURL);
+		return {
+			...base,
+			kind: "unknown",
+			status: "unavailable"
+		};
+	} catch (error) {
+		relayGate.fail(route.baseURL);
+		return {
+			...base,
+			kind: "unknown",
+			status: statusOf(error)
+		};
+	}
+}
+/**
+* 批量查询多个中转站路由的额度（每个独立成败，互不影响）。
+* @param ctx - host context carrying the credentials seam.
+* @param routes - 配了 baseURL 且 apiKeyEnv 有值的路由列表。
+* @returns 每个路由一行的额度结果。
+*/
+async function queryRelayQuotas(ctx, routes) {
+	return await Promise.all(routes.map(async (route) => queryRelayQuota(ctx, route)));
+}
+//#endregion
+//#region lib/types/client/usage-billing-settings.js
+/**
+* usage-stats 工具开关的共享设置契约（node 与 client 两端共用）。
+*
+* 宿主把已注册的设置命名空间服务给浏览器；node 半区在 apply 阶段读一次该值决定
+* 是否向模型注入 `usage_stats` 工具（工具注入是启动期决策，改开关后重载应用生效），
+* client 半区在「设置」Tab 渲染开关并写入同一命名空间。缺省的默认行为是关闭——
+* 避免该工具默认占用模型每次请求的上下文（coding 场景通常在仪表盘看用量）。
+*/
+/** 设置命名空间 id（小写 kebab-case）。 */
+const BILLING_SETTINGS_NAMESPACE = "ui-usage-billing";
+/** 该命名空间下用户可编辑的字段名。 */
+const ENABLE_USAGE_STATS_TOOL_FIELD = "enableUsageStatsTool";
+//#endregion
 //#region lib/types/index.js
 /**
 * Usage billing surface plugin, node half.
@@ -2586,6 +3153,10 @@ async function collectSubscriptions(keys, plans = [], timeoutMs = DEFAULT_TIMEOU
 * missing file answers `{ error }` so the dashboard shows zeros, never
 * fabricated samples.
 */
+/** usage_stats 工具开关的设置命名空间 id（下端与 node 共用同一常量）。 */
+const usageBillingSettingsNs = settingsNamespace(BILLING_SETTINGS_NAMESPACE);
+/** 该命名空间的 wire schema：`enableUsageStatsTool` 布尔，默认关闭（issue 诉求）。 */
+const UsageBillingSettingsSchema = z.object({ [ENABLE_USAGE_STATS_TOOL_FIELD]: z.boolean().default(false) });
 /** 实时定价的后台刷新间隔（毫秒）：汇率/模型价低频变化，6 小时一次足够。 */
 const PRICING_REFRESH_INTERVAL_MS = 360 * 60 * 1e3;
 /** 订阅套餐额度缓存时长（毫秒）：上游配额 API 低频变化，5 分钟足够。 */
@@ -2599,6 +3170,21 @@ const DEFAULT_BALANCE_API_KEY_ENV = "DEEPSEEK_API_KEY";
 const PACKAGE_VERSION = createRequire(import.meta.url)("../package.json").version ?? "0.0.0";
 /** 统计快照的落盘节流（毫秒）：前端 30 秒轮询，快照最多每 30 秒写一次。 */
 const SNAPSHOT_INTERVAL_MS = 3e4;
+/** 鉴权失败告警冷却（毫秒）：同一 provider 在窗口内只提示一次，避免 30 秒轮询刷屏。 */
+const AUTH_WARN_COOLDOWN_MS = 1800 * 1e3;
+/**
+* 鉴权失败分类告警（P1-5）：余额 / 订阅查询返回 unauthorized 时，按
+* `source:provider` 去重并冷却告警，提示检查 llm-pi-ai 里该 provider 的 apiKeyEnv。
+*/
+const authWarnedAt = /* @__PURE__ */ new Map();
+function warnAuthOnce(source, provider, displayName) {
+	const key = `${source}:${provider}`;
+	const now = Date.now();
+	const last = authWarnedAt.get(key);
+	if (last !== void 0 && now - last < AUTH_WARN_COOLDOWN_MS) return;
+	authWarnedAt.set(key, now);
+	console.warn(`[usage-billing] ${displayName}（${provider}）鉴权失败：请检查 llm-pi-ai 设置中该 provider 的 apiKeyEnv 凭据是否正确/有效。`);
+}
 /** Required services: the web server, the persisted session log store, and user settings. */
 const inject = [
 	"webServer",
@@ -2641,19 +3227,80 @@ const SUBSCRIPTION_KEY_SOURCES = [
 		key: "openrouterApiKey"
 	}
 ];
-/**
-* 读取 llm-pi-ai 设置的 `providers` 字典（`<route> → { apiKeyEnv? }`）。
-* 余额查询复用同一份来源：部署为某个 provider 配一次 key，多个 surface 共享。
+/** 读 llm-pi-ai 设置的 `providers` 字典（`<route> → { apiKeyEnv?, baseURL?, displayName? }`）。
+*  余额与订阅查询复用同一份来源：部署为某个 provider 配一次，多 surface 共享。
 * @param settings - the settings service (reads the llm-pi-ai namespace).
 * @returns the providers dict; empty when the namespace is unreadable.
 */
 async function readPiAiProviders(settings) {
 	try {
-		return (settings.describe({ redactSecrets: true }).find((descriptor) => descriptor.ns === "llm-pi-ai")?.value)?.providers ?? {};
+		const providers = (settings.describe({ redactSecrets: true }).find((descriptor) => descriptor.ns === "llm-pi-ai")?.value)?.providers;
+		const out = {};
+		for (const [route, entry] of Object.entries(providers ?? {})) {
+			if (entry === null || typeof entry !== "object") continue;
+			const { apiKeyEnv, baseURL, displayName } = entry;
+			out[route] = {
+				...typeof apiKeyEnv === "string" ? { apiKeyEnv } : {},
+				...typeof baseURL === "string" ? { baseURL } : {},
+				...typeof displayName === "string" ? { displayName } : {}
+			};
+		}
+		return out;
 	} catch {
 		return {};
 	}
 }
+/** 同步读取 provider 路由的 baseURL 视图（中转站零配置发现来源）。
+*  `settings.describe` 是同步调用，聚合器每次折叠取最新站点映射，无需缓存/过期。
+*  注意：返回**全部可读路由**（baseURL 可选），聚合层据此区分「路由存在但无
+*  baseURL=直连」与「路由已删除=未知路由」两种不同归属。
+* @param settings - the settings service (reads the llm-pi-ai namespace).
+* @returns `<route> → { baseURL? }`；命名空间不可读时返回空。
+*/
+function readPiAiProviderRoutes(settings) {
+	try {
+		const providers = (settings.describe({ redactSecrets: true }).find((descriptor) => descriptor.ns === "llm-pi-ai")?.value)?.providers;
+		const out = {};
+		for (const [route, entry] of Object.entries(providers ?? {})) {
+			if (entry === null || typeof entry !== "object") continue;
+			const baseURL = entry.baseURL;
+			out[route] = typeof baseURL === "string" && baseURL !== "" ? { baseURL } : {};
+		}
+		return out;
+	} catch {
+		return {};
+	}
+}
+/**
+* 构造「cwd → 工作区标题」解析器（host 的 `workspaceRegistry` 为可选依赖）。
+* 匹配与 TokenLedger 同口径：会话 cwd 等于某工作区 path、或位于其子目录时，用
+* 工作区标题命名该项目（子目录的会话也计入）；否则返回 undefined（回退到目录名）。
+* registry 缺席/读取失败都返回 undefined，绝不抛错（可选依赖，不影响主流程）。
+* @param ctx - host context carrying the optional workspace registry.
+* @returns 标题解析函数；registry 不可用时 undefined。
+*/
+function buildWorkspaceTitleResolver(ctx) {
+	let registry;
+	try {
+		registry = ctx.get("workspaceRegistry");
+	} catch {
+		return;
+	}
+	if (registry === void 0 || typeof registry.list !== "function") return void 0;
+	const reg = registry;
+	return (cwd) => {
+		if (cwd === "") return void 0;
+		try {
+			const records = reg.list() ?? [];
+			const exact = records.find((record) => record.path === cwd);
+			if (exact !== void 0) return exact.title;
+			for (const record of records) if (record.path !== "" && cwd.startsWith(`${record.path}/`)) return record.title;
+			return;
+		} catch {
+			return;
+		}
+	};
+}
 /**
 * 解析订阅适配器需要的 API Key：从 llm-pi-ai 设置的 `providers.<id>.apiKeyEnv`
 * 读引用（如 kimi-coding → KIMI_CODING_API_KEY），再经凭据 seam 解析成实际值。
@@ -2692,7 +3339,13 @@ async function resolveSubscriptionKeys(settings, credentials) {
 * @param config - optional statsPath override.
 */
 function apply(ctx, config = {}) {
-	const aggregator = createUsageAggregator(ctx.sessionPersistence, { ...config.subscriptionProviders === void 0 ? {} : { subscriptionProviders: config.subscriptionProviders } });
+	let usageSettingsScope;
+	const workspaceTitleResolver = buildWorkspaceTitleResolver(ctx);
+	const aggregator = createUsageAggregator(ctx.sessionPersistence, {
+		...config.subscriptionProviders === void 0 ? {} : { subscriptionProviders: config.subscriptionProviders },
+		resolveRoutes: () => readPiAiProviderRoutes(ctx.settings),
+		...workspaceTitleResolver === void 0 ? {} : { resolveWorkspaceTitle: workspaceTitleResolver }
+	});
 	const cwd = process.cwd();
 	const snapshotPath = join(homedir(), ".dsh/.dsh-usage-stats.json");
 	const candidates = [
@@ -2706,16 +3359,35 @@ function apply(ctx, config = {}) {
 		const now = Date.now();
 		if (now - lastSnapshotAt < SNAPSHOT_INTERVAL_MS) return;
 		lastSnapshotAt = now;
-		writeFileAtomic(snapshotPath, JSON.stringify({
+		const payload = JSON.stringify({
 			...doc,
 			_writer: {
 				pid: process.pid,
 				at: now
 			}
-		}), {
-			mode: 384,
-			dirMode: 448
-		}).catch(() => {});
+		});
+		(async () => {
+			try {
+				const existing = await readFile(snapshotPath, "utf8");
+				await writeFileAtomic(`${snapshotPath}.bak`, existing, {
+					mode: 384,
+					dirMode: 448
+				});
+			} catch {}
+			try {
+				await writeFileAtomic(snapshotPath, payload, {
+					mode: 384,
+					dirMode: 448
+				});
+			} catch {}
+		})();
+	};
+	/** 读一个快照候选并解析成对象：主文件优先；主文件损坏时回退上一版 `.bak`（P0-3 崩溃恢复）。 */
+	const readSnapshot = async (candidate) => {
+		for (const path of [candidate, `${candidate}.bak`]) try {
+			return JSON.parse(await readFile(path, "utf8"));
+		} catch {}
+		return null;
 	};
 	(async () => {
 		try {
@@ -2724,94 +3396,118 @@ function apply(ctx, config = {}) {
 			if (writer?.pid !== void 0 && writer.pid !== process.pid && writer.at !== void 0 && Date.now() - writer.at < 6e4) console.warn(`[usage-billing] 检测到另一实例（pid ${writer.pid}）正在提供用量统计，双实例可能导致提醒重复。`);
 		} catch {}
 	})();
-	ctx.inject(["tools"], (toolsCtx) => {
-		toolsCtx.tools.register(defineTool({
-			name: "usage_stats",
-			description: "查询本机 DeepSeek Harness 的模型用量与估算费用（人民币，按官方目录价估算，非账单）。range 取值：today=今天，month=本月，session=当前会话，all=累计。",
-			parameters: { range: {
-				type: "string",
-				enum: [
-					"today",
-					"month",
-					"session",
-					"all"
-				],
-				required: true,
-				description: "统计范围：today / month / session / all"
-			} },
-			output: {
-				schema: {
-					type: "object",
-					additionalProperties: false,
-					properties: {
-						range: {
-							type: "string",
-							required: true
-						},
-						cost: {
-							type: "number",
-							required: true,
-							description: "估算费用（人民币元）"
-						},
-						calls: {
-							type: "number",
-							required: true
-						},
-						input: {
-							type: "number",
-							required: true,
-							description: "输入 tokens"
-						},
-						output: {
-							type: "number",
-							required: true,
-							description: "输出 tokens"
+	ctx.inject(["settings"], (sctx) => {
+		const scope = sctx.settings.register(usageBillingSettingsNs, UsageBillingSettingsSchema, { base: { enableUsageStatsTool: config.enableUsageStatsTool ?? false } });
+		usageSettingsScope = scope;
+		ctx.inject(["tools"], (toolsCtx) => {
+			if (scope.get().enableUsageStatsTool) toolsCtx.tools.register(defineTool({
+				name: "usage_stats",
+				description: "查询本机 DeepSeek Harness 的模型用量与估算费用（人民币，按官方目录价估算，非账单）。range 取值：today=今天，month=本月，session=当前会话，all=累计。",
+				parameters: { range: {
+					type: "string",
+					enum: [
+						"today",
+						"month",
+						"session",
+						"all"
+					],
+					required: true,
+					description: "统计范围：today / month / session / all"
+				} },
+				output: {
+					schema: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							range: {
+								type: "string",
+								required: true
+							},
+							cost: {
+								type: "number",
+								required: true,
+								description: "估算费用（人民币元）"
+							},
+							calls: {
+								type: "number",
+								required: true
+							},
+							input: {
+								type: "number",
+								required: true,
+								description: "输入 tokens"
+							},
+							output: {
+								type: "number",
+								required: true,
+								description: "输出 tokens"
+							}
 						}
-					}
+					},
+					render: (_args, value) => [{
+						type: "text",
+						text: `用量（${value.range}）：估算费用 ${formatMoney(value.cost)}，调用 ${value.calls} 次，输入 ${formatTokens(value.input)} tokens，输出 ${formatTokens(value.output)} tokens`
+					}]
 				},
-				render: (_args, value) => [{
-					type: "text",
-					text: `用量（${value.range}）：估算费用 ${formatMoney(value.cost)}，调用 ${value.calls} 次，输入 ${formatTokens(value.input)} tokens，输出 ${formatTokens(value.output)} tokens`
-				}]
-			},
-			async execute(args, exec) {
-				const stats = await aggregator.aggregate();
-				const zero = {
-					range: args.range,
-					cost: 0,
-					calls: 0,
-					input: 0,
-					output: 0
-				};
-				if (args.range === "all") return {
-					range: args.range,
-					cost: stats.total.cost,
-					calls: stats.total.calls,
-					input: stats.total.input,
-					output: stats.total.output
-				};
-				if (args.range === "today") {
-					const day = stats.byDay[dayStamp(Date.now())];
-					return day === void 0 ? zero : {
+				async execute(args, exec) {
+					const stats = await aggregator.aggregate();
+					const zero = {
 						range: args.range,
-						cost: day.cost,
-						calls: day.calls,
-						input: day.input,
-						output: day.output
+						cost: 0,
+						calls: 0,
+						input: 0,
+						output: 0
 					};
-				}
-				if (args.range === "month") {
-					const prefix = dayStamp(Date.now()).slice(0, 7);
+					if (args.range === "all") return {
+						range: args.range,
+						cost: stats.total.cost,
+						calls: stats.total.calls,
+						input: stats.total.input,
+						output: stats.total.output
+					};
+					if (args.range === "today") {
+						const day = stats.byDay[dayStamp(Date.now())];
+						return day === void 0 ? zero : {
+							range: args.range,
+							cost: day.cost,
+							calls: day.calls,
+							input: day.input,
+							output: day.output
+						};
+					}
+					if (args.range === "month") {
+						const prefix = dayStamp(Date.now()).slice(0, 7);
+						let cost = 0;
+						let calls = 0;
+						let input = 0;
+						let output = 0;
+						for (const [date, day] of Object.entries(stats.byDay)) {
+							if (!date.startsWith(prefix)) continue;
+							cost += day.cost;
+							calls += day.calls;
+							input += day.input;
+							output += day.output;
+						}
+						return {
+							range: args.range,
+							cost,
+							calls,
+							input,
+							output
+						};
+					}
+					const sessionId = exec.agent?.id;
+					if (sessionId === void 0) throw new Error("usage_stats 的 session 范围需要 agent 会话上下文");
 					let cost = 0;
 					let calls = 0;
 					let input = 0;
 					let output = 0;
-					for (const [date, day] of Object.entries(stats.byDay)) {
-						if (!date.startsWith(prefix)) continue;
-						cost += day.cost;
-						calls += day.calls;
-						input += day.input;
-						output += day.output;
+					for (const turn of stats.byTurn ?? []) {
+						if (turn.sessionId !== String(sessionId)) continue;
+						cost += turn.cost;
+						calls += 1;
+						input += turn.input;
+						output += turn.output;
 					}
 					return {
 						range: args.range,
@@ -2821,28 +3517,8 @@ function apply(ctx, config = {}) {
 						output
 					};
 				}
-				const sessionId = exec.agent?.id;
-				if (sessionId === void 0) throw new Error("usage_stats 的 session 范围需要 agent 会话上下文");
-				let cost = 0;
-				let calls = 0;
-				let input = 0;
-				let output = 0;
-				for (const turn of stats.byTurn ?? []) {
-					if (turn.sessionId !== String(sessionId)) continue;
-					cost += turn.cost;
-					calls += 1;
-					input += turn.input;
-					output += turn.output;
-				}
-				return {
-					range: args.range,
-					cost,
-					calls,
-					input,
-					output
-				};
-			}
-		}));
+			}));
+		});
 	});
 	let live = { source: "builtin" };
 	const refreshPricing = async () => {
@@ -2875,9 +3551,44 @@ function apply(ctx, config = {}) {
 			if (providers["deepseek"] === void 0) providers["deepseek"] = { apiKeyEnv: config.balanceApiKeyEnv ?? DEFAULT_BALANCE_API_KEY_ENV };
 			const balances = await queryBalances(ctx, providers);
 			const custom = await queryCustomBalances(ctx, config.customBalances ?? []);
+			for (const row of [...balances, ...custom]) if (row.error === "unauthorized") warnAuthOnce("balance", row.provider, row.displayName);
 			res.end(JSON.stringify({ balances: [...balances, ...custom] }));
 		}
 	}), "usage-billing: balance route");
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: "/api/billing/usage-tool",
+		handler: async (req, res) => {
+			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+			const enabled = usageSettingsScope?.get().enableUsageStatsTool ?? false;
+			if (req.method === "GET") {
+				res.end(JSON.stringify({ enabled }));
+				return;
+			}
+			if (req.method !== "POST") {
+				res.writeHead(405, { "content-type": "application/json; charset=utf-8" });
+				res.end(JSON.stringify({ error: "method not allowed" }));
+				return;
+			}
+			try {
+				let body = "";
+				for await (const chunk of req) body += String(chunk);
+				const parsed = JSON.parse(body === "" ? "{}" : body);
+				if (usageSettingsScope === void 0) {
+					res.end(JSON.stringify({ error: "settings unavailable" }));
+					return;
+				}
+				const next = parsed.enabled === true;
+				await usageSettingsScope.update({ enableUsageStatsTool: next });
+				res.end(JSON.stringify({
+					ok: true,
+					enabled: next
+				}));
+			} catch {
+				res.end(JSON.stringify({ error: "invalid" }));
+			}
+		}
+	}), "usage-billing: usage-tool route");
 	let quotaCache = {
 		at: 0,
 		quotas: []
@@ -2889,7 +3600,7 @@ function apply(ctx, config = {}) {
 			...item.region === void 0 ? {} : { region: item.region }
 		})))].map((row) => {
 			const planType = planTypeOf(row.provider);
-			const subscriptionAmount = subscriptionCnyOf(row.provider);
+			const subscriptionAmount = subscriptionFeeCnyOf(row.provider, live.rate);
 			return {
 				...row,
 				planType,
@@ -2903,6 +3614,7 @@ function apply(ctx, config = {}) {
 			windows: [],
 			planType: planTypeOf(item.provider)
 		});
+		for (const row of rows) if (row.status === "unauthorized") warnAuthOnce("subscription", row.provider, row.displayName);
 		quotaCache = {
 			at: Date.now(),
 			quotas: rows
@@ -2917,6 +3629,36 @@ function apply(ctx, config = {}) {
 			res.end(JSON.stringify({ quotas: quotaCache.quotas }));
 		}
 	}), "usage-billing: subscriptions route");
+	let relayCache = {
+		at: 0,
+		quotas: []
+	};
+	const refreshRelay = async () => {
+		const providers = await readPiAiProviders(ctx.settings);
+		const routes = [];
+		for (const [route, entry] of Object.entries(providers)) {
+			if (entry.baseURL === void 0 || entry.apiKeyEnv === void 0) continue;
+			routes.push({
+				route,
+				baseURL: entry.baseURL,
+				apiKeyEnv: entry.apiKeyEnv,
+				...entry.displayName === void 0 ? {} : { displayName: entry.displayName }
+			});
+		}
+		relayCache = {
+			at: Date.now(),
+			quotas: await queryRelayQuotas(ctx, routes)
+		};
+	};
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: "/api/billing/relay-quotas",
+		handler: async (_req, res) => {
+			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+			if (Date.now() - relayCache.at >= SUBSCRIPTION_CACHE_MS) await refreshRelay();
+			res.end(JSON.stringify({ quotas: relayCache.quotas }));
+		}
+	}), "usage-billing: relay-quotas route");
 	ctx.effect(() => ctx.webServer.register({
 		kind: "exact",
 		path: "/api/billing/usage-stats",
@@ -2939,18 +3681,18 @@ function apply(ctx, config = {}) {
 			} catch (error) {
 				console.error("[usage-billing] usage-stats aggregate failed, falling back to snapshot:", error);
 			}
-			for (const candidate of candidates) try {
-				const text = await readFile(candidate, "utf8");
-				const doc = JSON.parse(text);
+			for (const candidate of candidates) {
+				const doc = await readSnapshot(candidate);
+				if (doc === null) continue;
 				if (config.monthlyBudget !== void 0) doc["budget"] = config.monthlyBudget;
 				if (config.lowBalanceThreshold !== void 0) doc["lowBalanceThreshold"] = config.lowBalanceThreshold;
 				doc["pluginVersion"] = PACKAGE_VERSION;
 				res.end(JSON.stringify(doc));
 				return;
-			} catch {}
+			}
 			res.end(JSON.stringify({ error: "usage stats unavailable" }));
 		}
 	}), "usage-billing: usage-stats route");
 }
 //#endregion
-export { apply, inject, resolveSubscriptionKeys };
+export { apply, inject, readPiAiProviderRoutes, resolveSubscriptionKeys };