@ychris12138/dsh-usage-stats 0.2.10 → 0.3.0

package/lib/accounts.js

@@ -9,15 +9,46 @@
  * @module dsh-usage-stats/accounts
  */
 
-import { balanceSchemeOf, queryBalance } from "./balance.js";
+import { queryBalance } from "./balance.js";
+import { isPrivateAddress, isPrivateHostname } from "./network.js";
+import { resolveProviderIdentity } from "./provider-identity.js";
 import { collectSubscription } from "./subscriptions.js";
 import { lookup as dnsLookup } from "node:dns/promises";
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
 import { isIP } from "node:net";
 
+export { isPrivateAddress } from "./network.js";
+
 const DEFAULT_TIMEOUT_MS = 15000;
 const DEFAULT_REFRESH_MS = 300000;
+const MAX_REFRESH_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_REFRESH_CONFIG = Object.freeze({
+	enabled: true,
+	activeMs: 60000,
+	detailMs: 120000,
+	backgroundMs: 900000
+});
+const DEFAULT_REFRESH_POLICY = Object.freeze({
+	activeMs: DEFAULT_REFRESH_CONFIG.activeMs,
+	detailMs: DEFAULT_REFRESH_CONFIG.detailMs,
+	backgroundMs: DEFAULT_REFRESH_CONFIG.backgroundMs,
+	rateLimitBaseMs: 300000,
+	rateLimitMaxMs: 3600000
+});
+const PROVENANCE_KINDS = new Set(["official", "provider", "configured", "experimental", "unknown"]);
+const OFFICIAL_ADAPTERS = new Set([
+	"deepseek-balance",
+	"openrouter-balance",
+	"moonshot-balance",
+	"zai-balance",
+	"opencode-go",
+	"zai-token-plan",
+	"kimi-token-plan",
+	"minimax-token-plan",
+	"ollama"
+]);
+const PROVIDER_ADAPTERS = new Set(["new-api", "sub2api", "sub2api-auth"]);
 const MAX_RESPONSE_BYTES = 1024 * 1024;
 const OPENROUTER_MANAGEMENT_REF = "OPENROUTER_MANAGEMENT_KEY";
 /**
@@ -39,6 +70,23 @@ const ACCOUNT_STATUSES = new Set([
 	"blocked",
 	"unsupported"
 ]);
+const SAFE_REASON_CODES = new Set([
+	"dns-resolution-failed",
+	"timeout",
+	"rate-limited",
+	"unauthorized",
+	"upstream-invalid-json",
+	"upstream-not-json",
+	"upstream-too-large",
+	"upstream-invalid-response",
+	"blocked-network",
+	"all-addresses-unreachable",
+	"no-validated-address",
+	"sub2api-balance-shape-unrecognized",
+	"unknown"
+]);
+const HEALTH_ATTEMPTED = Symbol("account-health-attempted");
+const HEALTH_SUCCEEDED = Symbol("account-health-succeeded");
 const ADAPTERS = new Set([
 	"deepseek-balance",
 	"openrouter-balance",
@@ -93,6 +141,48 @@ function round1(value) {
 	return Math.round(value * 10) / 10;
 }
 
+/** Normalize how trustworthy an account endpoint binding is. */
+export function accountProvenance(spec) {
+	if (PROVENANCE_KINDS.has(spec?.provenanceHint)) return spec.provenanceHint;
+	const adapter = nonEmptyString(spec?.adapter);
+	if (adapter === null) return "unknown";
+	if (adapter === "declarative" || adapter === "general") return "configured";
+	if (OFFICIAL_ADAPTERS.has(adapter)) return "official";
+	if (PROVIDER_ADAPTERS.has(adapter)) return "provider";
+	return "unknown";
+}
+
+/** Derive health age from the last successful sample without mutating cache state. */
+export function withHealthAge(snapshot, now = Date.now()) {
+	if (snapshot === null || snapshot === void 0 || typeof snapshot !== "object") return snapshot;
+	const lastSuccessAt = typeof snapshot.lastSuccessAt === "number" && Number.isFinite(snapshot.lastSuccessAt)
+		? snapshot.lastSuccessAt
+		: null;
+	return {
+		...snapshot,
+		ageMs: lastSuccessAt === null ? null : Math.max(0, now - lastSuccessAt)
+	};
+}
+
+/** Pure central refresh policy; scheduling and I/O stay outside this function. */
+export function refreshPolicy(state, now = Date.now(), overrides = {}) {
+	const intervals = { ...DEFAULT_REFRESH_POLICY, ...overrides };
+	const activity = state?.activity === "active" || state?.activity === "detail" ? state.activity : "background";
+	const lastAttemptAt = typeof state?.lastAttemptAt === "number" && Number.isFinite(state.lastAttemptAt)
+		? state.lastAttemptAt
+		: null;
+	const priority = activity === "active" ? 3 : activity === "detail" ? 2 : 1;
+	if (lastAttemptAt === null) return { activity, priority, delayMs: 0, nextRefreshAt: now };
+	const normalDelayMs = activity === "active" ? intervals.activeMs : activity === "detail" ? intervals.detailMs : intervals.backgroundMs;
+	let delayMs = normalDelayMs;
+	if ((Number(state?.rateLimitFailures) || 0) > 0) {
+		const failures = Math.max(1, Math.floor(Number(state.rateLimitFailures) || 1));
+		const backoffDelayMs = Math.min(intervals.rateLimitMaxMs, intervals.rateLimitBaseMs * 2 ** Math.min(20, failures - 1));
+		delayMs = Math.max(normalDelayMs, backoffDelayMs);
+	}
+	return { activity, priority, delayMs, nextRefreshAt: lastAttemptAt + delayMs };
+}
+
 function toIso(value) {
 	if (value === null || value === void 0 || value === "") return null;
 	if (typeof value === "number" && Number.isFinite(value)) {
@@ -119,7 +209,34 @@ function statusOf(error) {
 
 function safeReasonOf(error) {
 	const reason = nonEmptyString(error?.safeReason);
-	return reason === null ? null : reason.slice(0, 120);
+	if (reason !== null && SAFE_REASON_CODES.has(reason)) return reason;
+	const status = statusOf(error);
+	if (error?.name === "TimeoutError" || error?.name === "AbortError") return "timeout";
+	if (status === "rate-limited") return "rate-limited";
+	if (status === "unauthorized") return "unauthorized";
+	if (status === "blocked") return "blocked-network";
+	if (status === "invalid-response") return "upstream-invalid-response";
+	return status === "unavailable" ? "unknown" : null;
+}
+
+function providerReasonOf(reason, status) {
+	const value = nonEmptyString(reason);
+	if (value !== null && SAFE_REASON_CODES.has(value)) return value;
+	if (status === "rate-limited") return "rate-limited";
+	if (status === "unauthorized") return "unauthorized";
+	if (status === "blocked") return "blocked-network";
+	if (status === "invalid-response") return "upstream-invalid-response";
+	if (status === "unavailable") return "unknown";
+	return null;
+}
+
+/** Attach service-internal query facts without expanding the wire protocol. */
+function annotateQuerySnapshot(snapshot, { attempted, succeeded }) {
+	Object.defineProperties(snapshot, {
+		[HEALTH_ATTEMPTED]: { value: attempted === true },
+		[HEALTH_SUCCEEDED]: { value: succeeded === true }
+	});
+	return snapshot;
 }
 
 async function resolveCredential(credentials, ref) {
@@ -172,40 +289,10 @@ async function requestJson(url, init, deps = {}) {
 	return parseJsonResponse(response, deps.maxResponseBytes ?? MAX_RESPONSE_BYTES);
 }
 
-function schemeAdapter(scheme) {
-	return `${scheme}-balance`;
-}
-
 function schemeOfAdapter(adapter) {
 	return adapter.endsWith("-balance") ? adapter.slice(0, -8) : null;
 }
 
-function defaultAdapter(provider) {
-	const providerId = provider.id;
-	if (providerId === "opencode-go") return "opencode-go";
-	if (providerId === "zai" || providerId === "zai-coding-cn") return "zai-token-plan";
-	if (providerId === "kimi-coding" || providerId === "kimi-for-coding") return "kimi-token-plan";
-	if (["minimax", "minimaxi", "minimax-cn", "minimax-coding"].includes(providerId)) return "minimax-token-plan";
-	if (providerId === "passion") return "sub2api";
-	try {
-		const hostname = new URL(provider.baseURL).hostname.toLowerCase();
-		if (hostname === "passionapi.com" || hostname.endsWith(".passionapi.com")) return "sub2api";
-		// Ollama Cloud is detected by its canonical host so a user-configured
-		// provider with a custom id still gets the quota adapter; local Ollama
-		// (localhost:11434) never matches and stays without an account adapter.
-		// The id check is gated on the hostname so a local install that happens
-		// to use the canonical "ollama" id is not misread as a cloud account.
-		// Subdomains (e.g. api.ollama.com) are recognized for identification
-		// only: the usage query always targets the canonical ollama.com host,
-		// which is where the /api/usage endpoint is served.
-		if ((providerId === "ollama" || hostname === "ollama.com" || hostname.endsWith(".ollama.com")) && !privateHostname(hostname)) return "ollama";
-	} catch {
-		// A malformed provider URL is handled by the adapter when it is queried.
-	}
-	const scheme = balanceSchemeOf(providerId);
-	return scheme === null ? null : schemeAdapter(scheme);
-}
-
 function adapterMode(adapter, monitor) {
 	if (adapter === "declarative") return monitor.mode;
 	if (["opencode-go", "zai-token-plan", "kimi-token-plan", "minimax-token-plan", "ollama"].includes(adapter)) return "subscription";
@@ -260,9 +347,34 @@ function validateDeclarative(monitor, label) {
 	if (monitor.extract.divisor !== void 0 && (numberOrNull(monitor.extract.divisor) === null || Number(monitor.extract.divisor) === 0)) throw new Error(`${label}.extract.divisor must be a non-zero number`);
 }
 
+function validateRefreshInterval(value, label, fallback) {
+	if (value === void 0) return fallback;
+	if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value)
+		|| value < 60000 || value > MAX_REFRESH_INTERVAL_MS) {
+		throw new Error(`${label} must be an integer from 60000 to ${MAX_REFRESH_INTERVAL_MS} ms`);
+	}
+	return value;
+}
+
+function validateRefreshConfig(raw, disableBackgroundRefresh) {
+	if (raw === void 0) raw = {};
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new Error("refresh must be an object");
+	if (disableBackgroundRefresh !== void 0 && typeof disableBackgroundRefresh !== "boolean") {
+		throw new Error("disableBackgroundRefresh must be a boolean");
+	}
+	if (raw.enabled !== void 0 && typeof raw.enabled !== "boolean") throw new Error("refresh.enabled must be a boolean");
+	return {
+		enabled: raw.enabled ?? (disableBackgroundRefresh === true ? false : DEFAULT_REFRESH_CONFIG.enabled),
+		activeMs: validateRefreshInterval(raw.activeMs, "refresh.activeMs", DEFAULT_REFRESH_CONFIG.activeMs),
+		detailMs: validateRefreshInterval(raw.detailMs, "refresh.detailMs", DEFAULT_REFRESH_CONFIG.detailMs),
+		backgroundMs: validateRefreshInterval(raw.backgroundMs, "refresh.backgroundMs", DEFAULT_REFRESH_CONFIG.backgroundMs)
+	};
+}
+
 /** Validate and freeze the non-secret account-monitor configuration shape. */
 export function validateAccountConfig(raw = {}) {
 	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new Error("account config must be an object");
+	const refresh = validateRefreshConfig(raw.refresh, raw.disableBackgroundRefresh);
 	const monitors = raw.monitors ?? {};
 	if (monitors === null || typeof monitors !== "object" || Array.isArray(monitors)) throw new Error("monitors must be an object keyed by provider id");
 	const normalized = {};
@@ -282,13 +394,13 @@ export function validateAccountConfig(raw = {}) {
 		if (adapter === "declarative") validateDeclarative(value, label);
 		normalized[providerId] = { ...value, providerId, adapter };
 	}
-	return { monitors: normalized };
+	return { monitors: normalized, refresh };
 }
 
 /** Bind one configured Harness provider to its explicit or built-in adapter. */
 export function resolveAccountSpec(provider, config = { monitors: {} }) {
 	const monitor = config.monitors?.[provider.id] ?? {};
-	const adapter = monitor.adapter ?? defaultAdapter(provider);
+	const adapter = resolveProviderIdentity(provider, config).accountAdapter;
 	const mode = adapter === null ? null : adapterMode(adapter, monitor);
 	const apiKeyRef = monitor.credentialRef
 		?? (adapter === "openrouter-balance" ? OPENROUTER_MANAGEMENT_REF : provider.apiKeyEnv);
@@ -336,74 +448,6 @@ function mapped(root, mapping) {
 	return void 0;
 }
 
-function ipv4Private(octets) {
-	const [a, b, c] = octets;
-	return a === 0
-		|| a === 10
-		|| a === 127
-		|| a === 169 && b === 254
-		|| a === 172 && b >= 16 && b <= 31
-		|| a === 192 && b === 168
-		|| a === 192 && b === 0 && (c === 0 || c === 2)
-		|| a === 192 && b === 88 && c === 99
-		|| a === 100 && b >= 64 && b <= 127
-		|| a === 198 && (b === 18 || b === 19)
-		|| a === 198 && b === 51 && c === 100
-		|| a === 203 && b === 0 && c === 113
-		|| a >= 224;
-}
-
-function ipv6Bytes(address) {
-	let value = address.toLowerCase().split("%")[0];
-	let ipv4Tail = null;
-	const lastColon = value.lastIndexOf(":");
-	if (value.slice(lastColon + 1).includes(".")) {
-		const octets = value.slice(lastColon + 1).split(".").map(Number);
-		if (octets.length !== 4 || octets.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return null;
-		ipv4Tail = [(octets[0] << 8) | octets[1], (octets[2] << 8) | octets[3]];
-		value = `${value.slice(0, lastColon)}:${ipv4Tail[0].toString(16)}:${ipv4Tail[1].toString(16)}`;
-	}
-	const halves = value.split("::");
-	if (halves.length > 2) return null;
-	const left = halves[0] === "" ? [] : halves[0].split(":");
-	const right = halves.length === 1 || halves[1] === "" ? [] : halves[1].split(":");
-	const missing = 8 - left.length - right.length;
-	if (missing < 0 || halves.length === 1 && missing !== 0) return null;
-	const words = [...left, ...Array(missing).fill("0"), ...right].map((part) => Number.parseInt(part || "0", 16));
-	if (words.length !== 8 || words.some((part) => !Number.isInteger(part) || part < 0 || part > 0xffff)) return null;
-	const bytes = [];
-	for (const word of words) bytes.push(word >> 8, word & 0xff);
-	return bytes;
-}
-
-/** True for loopback, private, link-local, documentation, multicast, and other non-public IP space. */
-export function isPrivateAddress(address) {
-	const value = String(address ?? "").trim().replace(/^\[|\]$/g, "");
-	if (isIP(value) === 4) return ipv4Private(value.split(".").map(Number));
-	if (isIP(value) !== 6) return false;
-	const bytes = ipv6Bytes(value);
-	if (bytes === null) return true;
-	if (bytes.slice(0, 10).every((byte) => byte === 0) && bytes[10] === 0xff && bytes[11] === 0xff) return ipv4Private(bytes.slice(12));
-	// Public provider endpoints should resolve to global unicast (2000::/3).
-	// This conservative allow-range excludes loopback/unspecified, NAT64,
-	// discard-only, ULA, link/site-local, multicast, and other special space.
-	const globalUnicast = (bytes[0] & 0xe0) === 0x20;
-	const word0 = (bytes[0] << 8) | bytes[1];
-	const word1 = (bytes[2] << 8) | bytes[3];
-	// IETF protocol assignments 2001:0000::/23 include benchmarking, ORCHID,
-	// and tunnel mechanisms; 2002::/16 (6to4) embeds an unchecked IPv4 target.
-	const ietfSpecial = word0 === 0x2001 && word1 <= 0x01ff;
-	const sixToFour = word0 === 0x2002;
-	const documentation = word0 === 0x2001 && word1 === 0x0db8
-		|| word0 === 0x3fff && (word1 & 0xf000) === 0;
-	return !globalUnicast || ietfSpecial || sixToFour || documentation;
-}
-
-function privateHostname(hostname) {
-	const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
-	return host === "localhost" || host.endsWith(".localhost") || isPrivateAddress(host);
-}
-
 /**
  * RFC 2544 benchmarking range commonly used by proxy fake-IP DNS.
  *
@@ -477,7 +521,7 @@ export function selectResolvedAddress(url, rawAddresses, allowPrivateNetwork = f
 
 async function resolvePublicAddresses(url, spec, deps) {
 	const hostname = url.hostname.replace(/^\[|\]$/g, "");
-	if (privateHostname(hostname) && spec.monitor.allowPrivateNetwork !== true) throw statusError("blocked", "account monitor private-network access requires allowPrivateNetwork");
+	if (isPrivateHostname(hostname) && spec.monitor.allowPrivateNetwork !== true) throw statusError("blocked", "account monitor private-network access requires allowPrivateNetwork");
 	if (isIP(hostname) !== 0) return [{ address: hostname, family: isIP(hostname) }];
 	let addresses;
 	try {
@@ -562,7 +606,7 @@ function pinnedRequest(url, address, init, deps, signal) {
 			let size = 0;
 			response.on("data", (chunk) => {
 				size += chunk.length;
-				if (size > (deps.maxResponseBytes ?? MAX_RESPONSE_BYTES)) request.destroy(statusError("invalid-response", "upstream response exceeds the size limit"));
+				if (size > (deps.maxResponseBytes ?? MAX_RESPONSE_BYTES)) request.destroy(statusError("invalid-response", "upstream response exceeds the size limit", void 0, "upstream-too-large"));
 				else chunks.push(chunk);
 			});
 			response.on("end", () => {
@@ -614,7 +658,7 @@ function customURL(spec) {
 	const base = new URL(spec.baseURL);
 	const providerBase = nonEmptyString(spec.providerBaseURL) === null ? null : new URL(spec.providerBaseURL);
 	if (base.protocol !== "https:" && spec.monitor.allowInsecure !== true) throw statusError("blocked", "custom monitor requires HTTPS");
-	if (privateHostname(base.hostname) && spec.monitor.allowPrivateNetwork !== true) throw statusError("blocked", "custom monitor private-network access requires allowPrivateNetwork");
+	if (isPrivateHostname(base.hostname) && spec.monitor.allowPrivateNetwork !== true) throw statusError("blocked", "custom monitor private-network access requires allowPrivateNetwork");
 	if (providerBase !== null && base.origin !== providerBase.origin && spec.monitor.allowCrossOrigin !== true) throw statusError("blocked", "custom monitor cross-origin access requires allowCrossOrigin");
 	const url = new URL(spec.monitor.request.path, base);
 	if (url.origin !== base.origin) throw statusError("unsupported", "custom monitor request must stay on its configured origin");
@@ -665,6 +709,7 @@ function baseSnapshot(spec, status, now) {
 		displayName: spec.displayName,
 		mode: spec.mode ?? "balance",
 		adapter: spec.adapter,
+		provenance: accountProvenance(spec),
 		status,
 		fetchedAt: now
 	};
@@ -713,19 +758,58 @@ async function queryGeneral(spec, credential, deps, now) {
 	return { ...baseSnapshot(spec, "ok", now), balance, alert: balanceAlert(balance, spec.monitor.warning) };
 }
 
-async function quotaPerUnit(spec, deps) {
+const LEGACY_NEW_API_QUOTA_PER_UNIT = 500000;
+
+function legacyNewApiQuotaStatus() {
+	return {
+		quotaPerUnit: LEGACY_NEW_API_QUOTA_PER_UNIT,
+		quotaUnitFallback: true,
+		displayType: "USD",
+		usdExchangeRate: 1
+	};
+}
+
+function normalizeNewApiQuotaStatus(body) {
+	const rawUnit = numberOrNull(body?.data?.quota_per_unit);
+	const quotaUnitFallback = rawUnit === null || rawUnit <= 0;
+	const quotaPerUnit = quotaUnitFallback ? LEGACY_NEW_API_QUOTA_PER_UNIT : rawUnit;
+	const rawDisplayType = body?.data?.quota_display_type;
+	let displayType = "USD";
+	if (rawDisplayType !== void 0 && rawDisplayType !== null && rawDisplayType !== "") {
+		const normalized = nonEmptyString(rawDisplayType);
+		if (normalized === null) throw statusError("invalid-response", "New API quota display type is invalid");
+		displayType = normalized.toUpperCase();
+	}
+	if (displayType === "USD") {
+		return { quotaPerUnit, quotaUnitFallback, displayType, usdExchangeRate: 1 };
+	}
+	if (displayType === "CNY") {
+		const usdExchangeRate = numberOrNull(body?.data?.usd_exchange_rate);
+		if (usdExchangeRate === null || usdExchangeRate <= 0) {
+			throw statusError("invalid-response", "New API CNY display requires a positive USD exchange rate");
+		}
+		return { quotaPerUnit, quotaUnitFallback, displayType, usdExchangeRate };
+	}
+	throw statusError("unsupported", "New API quota display type is unsupported");
+}
+
+async function queryNewApiQuotaStatus(spec, deps) {
 	try {
 		const body = await requestJson(new URL("/api/status", spec.baseURL).href, { headers: { accept: "application/json" } }, deps);
-		const value = numberOrNull(body?.data?.quota_per_unit);
-		if (value !== null && value > 0) return { value, fallback: false };
-		// Old status schemas did not expose quota_per_unit.
-		return { value: 500000, fallback: true };
+		return normalizeNewApiQuotaStatus(body);
 	} catch (error) {
-		if (error?.httpStatus === 404 || error?.httpStatus === 405) return { value: 500000, fallback: true };
+		if (error?.httpStatus === 404 || error?.httpStatus === 405) return legacyNewApiQuotaStatus();
 		throw error;
 	}
 }
 
+function newApiQuotaAmount(value, quotaStatus) {
+	const rawQuota = numberOrNull(value);
+	// New API raw quota first converts to USD, then to the configured display
+	// currency. Both account paths share this exact factor for every component.
+	return rawQuota === null ? null : rawQuota / quotaStatus.quotaPerUnit * quotaStatus.usdExchangeRate;
+}
+
 async function queryNewApiFallback(spec, credentials, deps, now) {
 	const ref = spec.monitor.fallbackCredentialRef;
 	const token = await resolveCredential(credentials, ref);
@@ -733,19 +817,20 @@ async function queryNewApiFallback(spec, credentials, deps, now) {
 	const headers = { authorization: `Bearer ${token}`, accept: "application/json" };
 	const userId = await resolveCredential(credentials, spec.monitor.fallbackUserIdRef);
 	if (userId !== "") headers["new-api-user"] = userId;
-	const [body, quotaUnit] = await Promise.all([
+	const [body, quotaStatus] = await Promise.all([
 		requestJson(new URL("/api/user/self", spec.baseURL).href, { headers }, deps),
-		quotaPerUnit(spec, deps)
+		queryNewApiQuotaStatus(spec, deps)
 	]);
-	const unit = quotaUnit.value;
 	if (body?.success === false || body?.data === null || typeof body?.data !== "object") throw statusError("invalid-response", "New API user response is invalid");
 	const remainingQuota = numberOrNull(body.data.quota);
 	const usedQuota = numberOrNull(body.data.used_quota);
-	if (remainingQuota === null) throw statusError("invalid-response", "New API user response is missing quota");
+	const remaining = newApiQuotaAmount(remainingQuota, quotaStatus);
+	const used = newApiQuotaAmount(usedQuota, quotaStatus);
+	if (remaining === null) throw statusError("invalid-response", "New API user response is missing quota");
 	const balance = {
-		remaining: remainingQuota / unit,
-		...(usedQuota === null ? {} : { used: usedQuota / unit, total: (remainingQuota + usedQuota) / unit }),
-		currency: "USD",
+		remaining,
+		...(used === null ? {} : { used, total: newApiQuotaAmount(remainingQuota + usedQuota, quotaStatus) }),
+		currency: quotaStatus.displayType,
 		unlimited: false,
 		expiresAt: null
 	};
@@ -755,8 +840,8 @@ async function queryNewApiFallback(spec, credentials, deps, now) {
 		balance,
 		alert: balanceAlert(balance, spec.monitor.warning),
 		source: "management-fallback",
-		quotaUnit: unit,
-		quotaUnitFallback: quotaUnit.fallback
+		quotaUnit: quotaStatus.quotaPerUnit,
+		quotaUnitFallback: quotaStatus.quotaUnitFallback
 	};
 }
 
@@ -774,15 +859,14 @@ async function queryNewApi(spec, credentials, credential, deps, now) {
 	const granted = numberOrNull(body.data.total_granted);
 	const used = numberOrNull(body.data.total_used);
 	const available = numberOrNull(body.data.total_available);
-	const quotaUnit = await quotaPerUnit(spec, deps);
-	const unit = quotaUnit.value;
+	const quotaStatus = await queryNewApiQuotaStatus(spec, deps);
 	const unlimited = booleanOrNull(body.data.unlimited_quota) === true;
 	if (!unlimited && available === null) throw statusError("invalid-response", "New API token response is missing total_available");
 	const balance = {
-		remaining: available === null ? null : available / unit,
-		...(used === null ? {} : { used: used / unit }),
-		...(granted === null ? {} : { total: granted / unit }),
-		currency: "USD",
+		remaining: newApiQuotaAmount(available, quotaStatus),
+		...(used === null ? {} : { used: newApiQuotaAmount(used, quotaStatus) }),
+		...(granted === null ? {} : { total: newApiQuotaAmount(granted, quotaStatus) }),
+		currency: quotaStatus.displayType,
 		unlimited,
 		expiresAt: numberOrNull(body.data.expires_at) > 0 ? toIso(body.data.expires_at) : null
 	};
@@ -792,8 +876,8 @@ async function queryNewApi(spec, credentials, credential, deps, now) {
 		balance,
 		alert: unlimited ? { level: "normal", metric: "remaining-percent", value: 100 } : balanceAlert(balance, spec.monitor.warning),
 		source: "token",
-		quotaUnit: unit,
-		quotaUnitFallback: quotaUnit.fallback
+		quotaUnit: quotaStatus.quotaPerUnit,
+		quotaUnitFallback: quotaStatus.quotaUnitFallback
 	};
 }
 
@@ -958,7 +1042,8 @@ function sub2apiAuthSpec(spec) {
 	return {
 		...spec,
 		adapter: "sub2api-auth",
-		mode: "balance"
+		mode: "balance",
+		provenanceHint: "experimental"
 	};
 }
 
@@ -1036,7 +1121,7 @@ async function querySub2ApiAuth(spec, credentials, deps, now) {
 		// unrecognized shape. Never include upstream-controlled content (JSON
 		// property names, values, messages) in safeReason — a hostile upstream
 		// could otherwise echo sensitive material across the server→browser
-		// boundary, since safeReasonOf() only truncates.
+		// boundary. safeReasonOf() accepts only the fixed vocabulary above.
 		if (balanceBody !== null && typeof balanceBody === "object") {
 			error.safeReason = "sub2api-balance-shape-unrecognized";
 		}
@@ -1100,9 +1185,28 @@ async function queryDeclarative(spec, credentials, deps, now) {
 /** Query one adapter and return a secret-free normalized account snapshot. */
 export async function queryAccount(spec, credentials, deps = {}) {
 	const now = (deps.now ?? Date.now)();
-	if (spec === null || spec === void 0) return unavailableSnapshot({ id: "unknown", displayName: "Unknown", adapter: null, mode: "balance" }, "unsupported", now);
+	if (spec === null || spec === void 0) {
+		return annotateQuerySnapshot(
+			unavailableSnapshot({ id: "unknown", displayName: "Unknown", adapter: null, mode: "balance" }, "unsupported", now),
+			{ attempted: false, succeeded: false }
+		);
+	}
+	let attempted = false;
+	const upstreamFetch = deps.fetch === void 0
+		? (url, init) => pinnedFetch(url, init, spec, deps)
+		: deps.fetch;
+	const safeDeps = {
+		...deps,
+		fetch: (url, init) => {
+			attempted = true;
+			return upstreamFetch(url, init);
+		}
+	};
+	const finish = (snapshot, succeeded = snapshot.status === "ok") => annotateQuerySnapshot(snapshot, {
+		attempted: attempted || succeeded,
+		succeeded
+	});
 	try {
-		const safeDeps = deps.fetch === void 0 ? { ...deps, fetch: (url, init) => pinnedFetch(url, init, spec, deps) } : deps;
 		// A relay provider with no built-in/explicit adapter may be a real
 		// Sub2API panel. Only when it also has a model-configured API key do we
 		// probe its public settings endpoint; a matching fingerprint selects the
@@ -1110,21 +1214,21 @@ export async function queryAccount(spec, credentials, deps = {}) {
 		// adapters always win, and unkeyed relays are never probed.
 		if (spec.adapter === null || spec.mode === null) {
 			const providerKey = await resolveCredential(credentials, spec.apiKeyRef);
-			if (providerKey === "") return unavailableSnapshot(spec, "unsupported", now);
+			if (providerKey === "") return finish(unavailableSnapshot(spec, "unsupported", now), false);
 			const probeable = { ...spec, adapter: null, mode: "balance" };
 			if (await probeSub2ApiPanel(probeable, safeDeps)) {
-				return await querySub2ApiAuth(sub2apiAuthSpec(probeable), credentials, safeDeps, now);
+				return finish(await querySub2ApiAuth(sub2apiAuthSpec(probeable), credentials, safeDeps, now));
 			}
-			return unavailableSnapshot(spec, "unsupported", now);
+			return finish(unavailableSnapshot(spec, "unsupported", now), false);
 		}
-		if (spec.adapter === "declarative") return await queryDeclarative(spec, credentials, safeDeps, now);
-		if (spec.adapter === "sub2api-auth") return await querySub2ApiAuth(spec, credentials, safeDeps, now);
+		if (spec.adapter === "declarative") return finish(await queryDeclarative(spec, credentials, safeDeps, now));
+		if (spec.adapter === "sub2api-auth") return finish(await querySub2ApiAuth(spec, credentials, safeDeps, now));
 		const credential = await resolveCredential(credentials, spec.apiKeyRef);
-		if (spec.adapter !== "opencode-go" && credential === "") return unavailableSnapshot(spec, "not-configured", now, { missingCredentials: spec.apiKeyRef === void 0 ? [] : [spec.apiKeyRef] });
-		if (schemeOfAdapter(spec.adapter) !== null) return await queryBuiltInBalance(spec, credential, safeDeps, now);
-		if (spec.adapter === "general") return await queryGeneral(spec, credential, safeDeps, now);
-		if (spec.adapter === "new-api") return await queryNewApi(spec, credentials, credential, safeDeps, now);
-		if (spec.adapter === "sub2api") return await querySub2Api(spec, credential, safeDeps, now);
+		if (spec.adapter !== "opencode-go" && credential === "") return finish(unavailableSnapshot(spec, "not-configured", now, { missingCredentials: spec.apiKeyRef === void 0 ? [] : [spec.apiKeyRef] }), false);
+		if (schemeOfAdapter(spec.adapter) !== null) return finish(await queryBuiltInBalance(spec, credential, safeDeps, now), true);
+		if (spec.adapter === "general") return finish(await queryGeneral(spec, credential, safeDeps, now));
+		if (spec.adapter === "new-api") return finish(await queryNewApi(spec, credentials, credential, safeDeps, now));
+		if (spec.adapter === "sub2api") return finish(await querySub2Api(spec, credential, safeDeps, now));
 		const subscriptionId = spec.adapter === "zai-token-plan" ? "zai"
 			: spec.adapter === "kimi-token-plan" ? "kimi"
 				: spec.adapter === "minimax-token-plan" ? "minimax"
@@ -1138,10 +1242,11 @@ export async function queryAccount(spec, credentials, deps = {}) {
 			baseURL: spec.monitor.usageBaseURL
 		}, safeDeps);
 		const windows = Array.isArray(provider.windows) ? provider.windows : [];
-		return { ...baseSnapshot(spec, provider.status, now), plan: provider.plan, windows, alert: subscriptionAlert(windows), ...(provider.missingCredentials === void 0 ? {} : { missingCredentials: provider.missingCredentials }), ...(provider.reason === void 0 ? {} : { reason: provider.reason }) };
+		const reason = providerReasonOf(provider.reason, provider.status);
+		return finish({ ...baseSnapshot(spec, provider.status, now), plan: provider.plan, windows, alert: subscriptionAlert(windows), ...(provider.missingCredentials === void 0 ? {} : { missingCredentials: provider.missingCredentials }), ...(reason === null ? {} : { reason }) });
 	} catch (error) {
 		const reason = safeReasonOf(error);
-		return unavailableSnapshot(spec, statusOf(error), now, reason === null ? {} : { reason });
+		return finish(unavailableSnapshot(spec, statusOf(error), now, reason === null ? {} : { reason }), false);
 	}
 }
 
@@ -1149,29 +1254,65 @@ function isTransient(status) {
 	return status === "unavailable" || status === "rate-limited" || status === "invalid-response";
 }
 
-function withStaleData(previous, current) {
-	if (previous?.status !== "ok" || !isTransient(current.status)) return current;
-	return {
+function mergeRefreshHealth(previous, current) {
+	const lastSuccessAt = previous?.lastSuccessAt
+		?? (previous?.status === "ok" ? previous.fetchedAt : null);
+	const attempted = current[HEALTH_ATTEMPTED] === true;
+	const successful = current[HEALTH_SUCCEEDED] === true || current.status === "ok";
+	const attemptAt = attempted ? current.fetchedAt : previous?.lastAttemptAt ?? null;
+	const currentWithHealth = {
+		...current,
+		lastAttemptAt: attemptAt,
+		lastSuccessAt: successful ? attemptAt : lastSuccessAt,
+		stale: false
+	};
+	delete currentWithHealth.ageMs;
+	const canRetain = !successful
+		&& lastSuccessAt !== null
+		&& (previous?.status === "ok" || previous?.stale === true)
+		&& isTransient(current.status);
+	if (!canRetain) return currentWithHealth;
+	const stale = {
 		...previous,
 		status: current.status,
-		fetchedAt: current.fetchedAt,
-		lastSuccessAt: previous.lastSuccessAt ?? previous.fetchedAt,
+		fetchedAt: attemptAt,
+		lastAttemptAt: attemptAt,
+		lastSuccessAt,
+		provenance: current.provenance ?? previous.provenance ?? "unknown",
 		stale: true
 	};
+	delete stale.ageMs;
+	if (current.reason === void 0) delete stale.reason;
+	else stale.reason = current.reason;
+	return stale;
 }
 
 /**
- * In-memory account cache with per-provider single-flight and forced bulk
- * refresh. Background scheduling is owned by the server plugin so it can also
- * refresh local token-usage aggregation in the same five-minute cycle.
+ * In-memory account cache with per-provider single-flight, health history, and
+ * adaptive due-time calculation. One server-owned scheduler coordinates it
+ * with the existing local token-usage aggregation lifecycle.
  */
 export function createAccountService({ credentials, getProviders, config = { monitors: {} }, deps = {} }) {
 	const cache = new Map();
 	const inflight = new Map();
-	const refreshMs = deps.refreshMs ?? DEFAULT_REFRESH_MS;
+	const refreshGenerations = new Map();
+	const now = deps.now ?? Date.now;
+	const refreshConfig = { ...DEFAULT_REFRESH_CONFIG, ...(config.refresh ?? {}) };
+	const autoRefreshEnabled = refreshConfig.enabled !== false;
+	const policyOverrides = {
+		activeMs: refreshConfig.activeMs,
+		detailMs: refreshConfig.detailMs,
+		backgroundMs: refreshConfig.backgroundMs,
+		...(deps.refreshMs === void 0 ? {} : { backgroundMs: deps.refreshMs }),
+		...(deps.refreshPolicy ?? {})
+	};
+	const activeProviders = new Set();
+	const activityTouches = new Map();
+	const policyListeners = new Set();
+	const activityTtlMs = deps.activityTtlMs ?? 600000;
 	// Long-lived Sub2API panel-detection cache, keyed by the provider's config
 	// key. It lives on the service so auto-detection probes once per
-	// (provider × config) even across five-minute background refreshes; a caller
+	// (provider × config) even across background refreshes; a caller
 	// may still inject its own Map (e.g. tests) by passing deps.sub2apiDetection.
 	const sub2apiDetection = deps.sub2apiDetection ?? new Map();
 	const serviceDeps = { ...deps, sub2apiDetection };
@@ -1210,44 +1351,139 @@ export function createAccountService({ credentials, getProviders, config = { mon
 		return (await specs()).find((spec) => spec.id === providerId) ?? null;
 	}
 
+	function notifyPolicyChange() {
+		for (const listener of policyListeners) listener();
+	}
+
+	function subscribePolicyChanges(listener) {
+		if (typeof listener !== "function") return () => {};
+		policyListeners.add(listener);
+		return () => policyListeners.delete(listener);
+	}
+
+	function touch(providerId, activity) {
+		if (typeof providerId !== "string" || providerId === "") return;
+		if (activity !== "active" && activity !== "detail") return;
+		const at = now();
+		const before = activityOf(providerId, at);
+		const previous = activityTouches.get(providerId) ?? {};
+		activityTouches.set(providerId, { ...previous, [`${activity}At`]: at });
+		if (activityOf(providerId, at) !== before) notifyPolicyChange();
+	}
+
+	function setActiveProviders(providerIds) {
+		const next = new Set([...(providerIds ?? [])].filter((providerId) => typeof providerId === "string" && providerId !== ""));
+		const changed = next.size !== activeProviders.size || [...next].some((providerId) => !activeProviders.has(providerId));
+		activeProviders.clear();
+		for (const providerId of next) activeProviders.add(providerId);
+		if (changed) notifyPolicyChange();
+	}
+
+	function activityOf(providerId, at) {
+		const touched = activityTouches.get(providerId);
+		if (activeProviders.has(providerId) || at - (touched?.activeAt ?? -Infinity) < activityTtlMs) return "active";
+		if (at - (touched?.detailAt ?? -Infinity) < activityTtlMs) return "detail";
+		return "background";
+	}
+
+	function policyOf(spec, at) {
+		const hit = cache.get(spec.id);
+		if (hit?.configKey !== spec.configKey) return refreshPolicy({ activity: activityOf(spec.id, at), status: "pending", lastAttemptAt: null }, at, policyOverrides);
+		return refreshPolicy({
+			activity: activityOf(spec.id, at),
+			status: hit.account.status,
+			rateLimitFailures: hit.rateLimitFailures ?? 0,
+			// Scheduling must advance even when a local credential/config check
+			// correctly produces no provider attempt (and lastAttemptAt stays null).
+			lastAttemptAt: hit.lastEvaluatedAt ?? hit.account.lastAttemptAt ?? hit.account.fetchedAt ?? null
+		}, at, policyOverrides);
+	}
+
 	async function refresh(spec) {
 		const existing = inflight.get(spec.id);
-		if (existing !== void 0) return existing;
+		if (existing?.configKey === spec.configKey) return existing.promise;
+		const generation = (refreshGenerations.get(spec.id) ?? 0) + 1;
+		refreshGenerations.set(spec.id, generation);
 		const promise = queryAccount(spec, credentials, serviceDeps).then((current) => {
-			const next = withStaleData(cache.get(spec.id)?.account, current);
-			cache.set(spec.id, { configKey: spec.configKey, account: next });
-			return next;
-		}).finally(() => inflight.delete(spec.id));
-		inflight.set(spec.id, promise);
-		return promise;
+			const previous = cache.get(spec.id);
+			const sameConfig = previous?.configKey === spec.configKey;
+			const previousAccount = sameConfig ? previous.account : null;
+			const previousRateLimitFailures = sameConfig ? previous.rateLimitFailures ?? 0 : 0;
+			const next = mergeRefreshHealth(previousAccount, current);
+			const successful = current[HEALTH_SUCCEEDED] === true || current.status === "ok";
+			const rateLimitFailures = current.status === "rate-limited"
+				? previousRateLimitFailures + 1
+				: successful ? 0 : previousRateLimitFailures;
+			// A late completion from a replaced binding may resolve its own caller,
+			// but must never overwrite the newer binding's cache state.
+			if (refreshGenerations.get(spec.id) === generation) {
+				cache.set(spec.id, {
+					configKey: spec.configKey,
+					account: next,
+					rateLimitFailures,
+					lastEvaluatedAt: current.fetchedAt
+				});
+			}
+			return withHealthAge(next, now());
+		});
+		let entry;
+		const tracked = promise.finally(() => {
+			if (inflight.get(spec.id) === entry) inflight.delete(spec.id);
+		});
+		entry = { configKey: spec.configKey, promise: tracked };
+		inflight.set(spec.id, entry);
+		return tracked;
 	}
 
-	async function get(providerId, { force = false } = {}) {
+	async function get(providerId, { force = false, activity = null } = {}) {
 		const spec = await specById(providerId);
 		if (spec === null) return null;
+		if (activity !== null) touch(providerId, activity);
 		const hit = cache.get(providerId);
-		const age = (deps.now ?? Date.now)() - (hit?.account?.fetchedAt ?? 0);
-		if (!force && hit?.configKey === spec.configKey && age >= 0 && age < refreshMs) return hit.account;
+		const at = now();
+		if (!force && hit?.configKey === spec.configKey
+			&& (!autoRefreshEnabled || policyOf(spec, at).nextRefreshAt > at)) return withHealthAge(hit.account, at);
 		return refresh(spec);
 	}
 
-	async function refreshAll() {
+	async function refreshableSpecs() {
 		const all = await specs();
-		// Auto-detection only probes null-adapter relays that have a configured
-		// API key, so the background refresh stays bounded and never touches
-		// unrelated, unkeyed providers.
 		const keyed = await Promise.all(all.map(async (spec) => ({
 			spec,
 			probe: spec.adapter === null
 				? (await resolveCredential(credentials, spec.apiKeyRef)) !== ""
 				: true
 		})));
-		return Promise.all(keyed.filter((entry) => entry.probe).map((entry) => refresh(entry.spec)));
+		return keyed.filter((entry) => entry.probe).map((entry) => entry.spec);
+	}
+
+	async function refreshAll() {
+		// Auto-detection only probes null-adapter relays that have a configured
+		// API key, so the background refresh stays bounded and never touches
+		// unrelated, unkeyed providers.
+		return Promise.all((await refreshableSpecs()).map((spec) => refresh(spec)));
+	}
+
+	async function refreshDue({ force = false } = {}) {
+		if (!autoRefreshEnabled && !force) return [];
+		const at = now();
+		const all = await refreshableSpecs();
+		const due = force ? all : all.filter((spec) => policyOf(spec, at).nextRefreshAt <= at);
+		return Promise.all(due.map((spec) => refresh(spec)));
+	}
+
+	async function nextRefreshAt() {
+		if (!autoRefreshEnabled) return null;
+		const at = now();
+		const all = await refreshableSpecs();
+		if (all.length === 0) return null;
+		return Math.min(...all.map((spec) => policyOf(spec, at).nextRefreshAt));
 	}
 
 	async function providerViews() {
 		return Promise.all((await specs()).map(async (spec) => {
-			const account = cache.get(spec.id)?.account;
+			const hit = cache.get(spec.id);
+			const account = withHealthAge(hit?.configKey === spec.configKey ? hit.account : void 0, now());
 			const credentialConfigured = account === void 0 && spec.apiKeyRef !== void 0
 				? await resolveCredential(credentials, spec.apiKeyRef) !== ""
 				: false;
@@ -1259,6 +1495,12 @@ export function createAccountService({ credentials, getProviders, config = { mon
 				configured: account === void 0 ? credentialConfigured : account.status !== "not-configured",
 				status: account?.status ?? "pending",
 				fetchedAt: account?.fetchedAt ?? null,
+				stale: account?.stale ?? false,
+				lastAttemptAt: account?.lastAttemptAt ?? null,
+				lastSuccessAt: account?.lastSuccessAt ?? null,
+				ageMs: account?.ageMs ?? null,
+				provenance: account?.provenance ?? accountProvenance(spec),
+				reason: account?.reason ?? null,
 				alert: account?.alert ?? null
 			};
 		}));
@@ -1273,10 +1515,15 @@ export function createAccountService({ credentials, getProviders, config = { mon
 	return {
 		get,
 		refreshAll,
+		refreshDue,
+		nextRefreshAt,
+		touch,
+		setActiveProviders,
+		subscribePolicyChanges,
 		providerViews,
 		subscriptionAccounts,
 		validate: async () => { await specs(); },
-		cached: (providerId) => cache.get(providerId)?.account ?? null
+		cached: (providerId) => withHealthAge(cache.get(providerId)?.account ?? null, now())
 	};
 }