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

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 = [
 	{
@@ -1287,6 +1289,7 @@ 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;
@@ -1314,6 +1317,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,6 +1327,8 @@ function createUsageAggregator(persistence, options = {}) {
 			}
 			try {
 				const { events } = await persistence.readFrom(meta.id, 0);
+				const after = await stampOf(meta);
+				if (stamp !== null && after !== stamp) continue;
 				const fold = foldSession(events, subscriptionProviders, officialProviderIds);
 				cache.set(id, {
 					stamp,
@@ -1337,6 +1344,11 @@ 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();
@@ -1475,17 +1487,89 @@ 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
@@ -1493,6 +1577,20 @@ function createUsageAggregator(persistence, options = {}) {
 */
 /** Abort a balance fetch when the upstream hangs beyond this budget. */
 const FETCH_TIMEOUT_MS$1 = 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 +1599,8 @@ 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";
 /** 数字归一化：接口返回的余额是字符串（如 `"110.00"`），统一转 number。 */
 function toNumber(value) {
 	if (typeof value === "number" && Number.isFinite(value)) return value;
@@ -1528,35 +1628,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$1);
+		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 +1773,24 @@ 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 } : {}
+		};
+	});
+}
 const QUERIERS = [
 	{
 		route: "deepseek",
@@ -1668,6 +1811,11 @@ const QUERIERS = [
 		route: "siliconflow",
 		displayName: "硅基流动",
 		querier: querySiliconFlow
+	},
+	{
+		route: "xai",
+		displayName: "xAI",
+		querier: queryXai
 	}
 ];
 /**
@@ -1764,47 +1912,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$1);
+			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);
 		}
 	}));
 }
@@ -1821,6 +1986,12 @@ async function queryCustomBalances(ctx, configs) {
 */
 /** Abort a fetch when the upstream hangs beyond this budget. */
 const FETCH_TIMEOUT_MS = 8e3;
+/** 每平台熔断门：单个定价上游连续可重试失败（网络 / 5xx / 429）达阈值后短路，
+*  避免 6 小时刷新循环与每次启动在已故障的上游上反复打满超时。按 URL 独立。 */
+const pricingGate = createCooldownGate({
+	failures: 3,
+	cooldownMs: 6e4
+});
 /**
 * USD → CNY 汇率源，按顺序尝试：国内可达的腾讯财经行情（免 key、`~` 分隔
 * 第 4 个字段为价格）优先，国外 open.er-api.com 兜底。任一源失败自动落到
@@ -1903,18 +2074,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);
+		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 +2129,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 +2252,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: "",
@@ -2169,18 +2367,26 @@ 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) {
@@ -2562,18 +2768,41 @@ 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/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 +2815,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 +2832,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",
@@ -2692,6 +2940,7 @@ async function resolveSubscriptionKeys(settings, credentials) {
 * @param config - optional statsPath override.
 */
 function apply(ctx, config = {}) {
+	let usageSettingsScope;
 	const aggregator = createUsageAggregator(ctx.sessionPersistence, { ...config.subscriptionProviders === void 0 ? {} : { subscriptionProviders: config.subscriptionProviders } });
 	const cwd = process.cwd();
 	const snapshotPath = join(homedir(), ".dsh/.dsh-usage-stats.json");
@@ -2706,16 +2955,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 +2992,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 +3113,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 +3147,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 +3196,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 +3210,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
@@ -2939,15 +3247,15 @@ 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");