@ychris12138/dsh-usage-stats 0.2.9 → 0.3.0

package/lib/index.js

@@ -1,12 +1,16 @@
 /**
  * dsh-usage-stats — server half.
  *
- * Registers five read-only, loopback-only endpoints on the web server:
+ * Registers nine read-only, loopback-only endpoints on the web server:
  *   GET /api/usage-stats/usage         — per-day token usage across every session
  *   GET /api/usage-stats/providers     — configured providers + balance schemes
  *   GET /api/usage-stats/balance       — balance for one provider (?provider=<id>)
  *   GET /api/usage-stats/subscriptions — OpenCode Go + Z.ai quota windows
  *   GET /api/usage-stats/account       — unified account snapshot for one provider
+ *   GET /api/usage-stats/session-context — provider/model context for one live session
+ *   GET /api/usage-stats/export/daily.csv — daily provider/model usage export
+ *   GET /api/usage-stats/export/sessions.csv — per-session usage export
+ *   GET /api/usage-stats/export.json — versioned usage/account-safe export
  *
  * Provider configuration is read straight from the harness settings
  * (`llm-deepseek` for the official DeepSeek route, `llm-pi-ai` for every
@@ -33,8 +37,10 @@
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { applyUsageDelta, createUsageState, mergeInto, renderUsage, totalTokens, zeroBuckets } from "./usage.js";
+import { applyUsageDelta, createUsageState, currentSessionContext, mergeBillingInto, mergeInto, renderSessionUsage, renderUsage, resetUsageState, totalTokens, zeroBuckets } from "./usage.js";
 import { ACCOUNT_REFRESH_MS, createAccountService, validateAccountConfig } from "./accounts.js";
+import { changedProviderPricingRoutes, createUsageCostEstimator, parseCostAccumulator, pricingFingerprint, renderBudgetSummary, serializeCostAccumulator, validateBudgetConfig } from "./billing.js";
+import { dailyCsv, jsonExport, sessionsCsv } from "./export.js";
 
 /** Stable Cordis plugin name. */
 const name = "usage-stats";
@@ -47,8 +53,12 @@ const PROVIDERS_PATH = "/api/usage-stats/providers";
 const BALANCE_PATH = "/api/usage-stats/balance";
 const SUBSCRIPTIONS_PATH = "/api/usage-stats/subscriptions";
 const ACCOUNT_PATH = "/api/usage-stats/account";
+const SESSION_CONTEXT_PATH = "/api/usage-stats/session-context";
+const DAILY_EXPORT_PATH = "/api/usage-stats/export/daily.csv";
+const SESSIONS_EXPORT_PATH = "/api/usage-stats/export/sessions.csv";
+const JSON_EXPORT_PATH = "/api/usage-stats/export.json";
 const UPSTREAM_TIMEOUT_MS = 15000;
-const CACHE_VERSION = 3;
+const CACHE_VERSION = 5;
 
 /** Default DeepSeek connection facts when the settings namespace is absent. */
 const DEEPSEEK_DEFAULTS = {
@@ -66,6 +76,16 @@ function json(res, status, value) {
 	res.end(body);
 }
 
+function attachment(res, contentType, filename, body) {
+	res.writeHead(200, {
+		"content-type": contentType,
+		"content-disposition": `attachment; filename="${filename}"`,
+		"cache-control": "no-store",
+		"x-content-type-options": "nosniff"
+	});
+	res.end(body);
+}
+
 /**
  * Loopback fence, primary on the PEER SOCKET address (not the
  * client-controllable Host header): the request must come from a loopback
@@ -139,6 +159,7 @@ function serializeSession(state) {
 	}
 	return {
 		kind: state.kind ?? "persisted",
+		title: typeof state.title === "string" ? state.title : null,
 		consumed: state.consumed ?? 0,
 		...(state.revision === void 0 ? {} : { revision: state.revision }),
 		days,
@@ -146,9 +167,30 @@ function serializeSession(state) {
 			key: state.lastSample.key,
 			day: state.lastSample.day,
 			model: state.lastSample.model,
+			providerId: state.lastSample.providerId,
+			time: state.lastSample.time,
+			cost: state.lastSample.cost,
 			buckets: { ...state.lastSample.buckets }
 		},
-		currentModel: state.currentModel
+		billing: {
+			total: serializeCostAccumulator(state.billing.total),
+			days: Object.fromEntries([...state.billing.days].map(([date, entry]) => [date, {
+				total: serializeCostAccumulator(entry.total),
+				models: Object.fromEntries([...entry.models].map(([model, accumulator]) => [model, serializeCostAccumulator(accumulator)]))
+			}])),
+			providers: Object.fromEntries(state.billing.providers),
+			models: Object.fromEntries(state.billing.models),
+			sampleCount: state.billing.sampleCount,
+			firstAt: state.billing.firstAt,
+			lastAt: state.billing.lastAt,
+			penultimateAt: state.billing.penultimateAt
+		},
+		currentModel: state.currentModel,
+		currentRoute: state.currentRoute === null || state.currentRoute === void 0 ? null : {
+			providerId: state.currentRoute.providerId,
+			model: state.currentRoute.model,
+			updatedAt: state.currentRoute.updatedAt
+		}
 	};
 }
 
@@ -157,6 +199,7 @@ function parseSession(raw) {
 	const state = createUsageState();
 	if (raw === null || typeof raw !== "object") return state;
 	state.kind = typeof raw.kind === "string" ? raw.kind : "persisted";
+	state.title = typeof raw.title === "string" ? raw.title : null;
 	state.consumed = Number.isSafeInteger(raw.consumed) ? raw.consumed : 0;
 	if (typeof raw.revision === "string") state.revision = raw.revision;
 	if (raw.days !== null && typeof raw.days === "object") {
@@ -190,6 +233,9 @@ function parseSession(raw) {
 			key: raw.lastSample.key,
 			day: raw.lastSample.day,
 			model: typeof raw.lastSample.model === "string" ? raw.lastSample.model : "unknown",
+			providerId: typeof raw.lastSample.providerId === "string" ? raw.lastSample.providerId : "unknown",
+			time: Number.isFinite(raw.lastSample.time) ? raw.lastSample.time : null,
+			cost: raw.lastSample.cost !== null && typeof raw.lastSample.cost === "object" ? { ...raw.lastSample.cost } : { counted: true, complete: false },
 			buckets: {
 				inputTokens: Number.isFinite(buckets.inputTokens) ? buckets.inputTokens : 0,
 				outputTokens: Number.isFinite(buckets.outputTokens) ? buckets.outputTokens : 0,
@@ -198,24 +244,97 @@ function parseSession(raw) {
 			}
 		};
 	}
+	if (raw.billing !== null && typeof raw.billing === "object" && !Array.isArray(raw.billing)) {
+		state.billing.total = parseCostAccumulator(raw.billing.total);
+		for (const [date, entry] of Object.entries(raw.billing.days ?? {})) {
+			if (entry === null || typeof entry !== "object" || Array.isArray(entry)) continue;
+			const restored = { total: parseCostAccumulator(entry.total), models: new Map() };
+			for (const [model, accumulator] of Object.entries(entry.models ?? {})) restored.models.set(model, parseCostAccumulator(accumulator));
+			state.billing.days.set(date, restored);
+		}
+		for (const [providerId, count] of Object.entries(raw.billing.providers ?? {})) if (Number.isSafeInteger(count) && count > 0) state.billing.providers.set(providerId, count);
+		for (const [model, count] of Object.entries(raw.billing.models ?? {})) if (Number.isSafeInteger(count) && count > 0) state.billing.models.set(model, count);
+		state.billing.sampleCount = Number.isSafeInteger(raw.billing.sampleCount) && raw.billing.sampleCount >= 0 ? raw.billing.sampleCount : 0;
+		state.billing.firstAt = Number.isFinite(raw.billing.firstAt) ? raw.billing.firstAt : null;
+		state.billing.lastAt = Number.isFinite(raw.billing.lastAt) ? raw.billing.lastAt : null;
+		state.billing.penultimateAt = Number.isFinite(raw.billing.penultimateAt) ? raw.billing.penultimateAt : null;
+	}
 	if (typeof raw.currentModel === "string") state.currentModel = raw.currentModel;
+	if (raw.currentRoute !== null && typeof raw.currentRoute === "object"
+		&& typeof raw.currentRoute.providerId === "string" && raw.currentRoute.providerId.length > 0
+		&& typeof raw.currentRoute.model === "string" && raw.currentRoute.model.length > 0) {
+		state.currentRoute = {
+			providerId: raw.currentRoute.providerId,
+			model: raw.currentRoute.model,
+			updatedAt: Number.isFinite(raw.currentRoute.updatedAt) ? raw.currentRoute.updatedAt : null
+		};
+	}
 	return state;
 }
 
-/** Load the cache once per process; any corruption degrades to a fresh cache. */
-async function loadCache() {
-	if (loadedCache !== null) return loadedCache;
+function parsePricingIdentityCutoffs(raw) {
+	const cutoffs = Object.create(null);
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return cutoffs;
+	for (const [routeId, cutoff] of Object.entries(raw)) {
+		if (routeId !== "" && Number.isFinite(cutoff) && cutoff >= 0) cutoffs[routeId] = cutoff;
+	}
+	return cutoffs;
+}
+
+function freshCache(pricingFingerprintValue, previous = null, transitionAt = Date.now()) {
+	const pricingIdentityCutoffs = parsePricingIdentityCutoffs(previous?.pricingIdentityCutoffs);
+	let pricingIdentityCutoffAll = Number.isFinite(previous?.pricingIdentityCutoffAll) && previous.pricingIdentityCutoffAll >= 0
+		? previous.pricingIdentityCutoffAll
+		: null;
+	if (previous !== null && previous.pricingFingerprint !== pricingFingerprintValue) {
+		const changedRoutes = changedProviderPricingRoutes(previous.pricingFingerprint, pricingFingerprintValue);
+		if (changedRoutes === null) pricingIdentityCutoffAll = Math.max(pricingIdentityCutoffAll ?? 0, transitionAt);
+		else for (const routeId of changedRoutes) pricingIdentityCutoffs[routeId] = Math.max(pricingIdentityCutoffs[routeId] ?? 0, transitionAt);
+	}
+	return {
+		version: CACHE_VERSION,
+		pricingFingerprint: pricingFingerprintValue,
+		pricingIdentityCutoffAll,
+		pricingIdentityCutoffs,
+		sessions: {}
+	};
+}
+
+function restoredCache(parsed, pricingFingerprintValue) {
+	const sessions = {};
+	for (const [id, entry] of Object.entries(parsed.sessions)) {
+		if (typeof id === "string" && id.length > 0) sessions[id] = parseSession(entry);
+	}
+	return {
+		version: CACHE_VERSION,
+		pricingFingerprint: pricingFingerprintValue,
+		pricingIdentityCutoffAll: Number.isFinite(parsed.pricingIdentityCutoffAll) && parsed.pricingIdentityCutoffAll >= 0
+			? parsed.pricingIdentityCutoffAll
+			: null,
+		pricingIdentityCutoffs: parsePricingIdentityCutoffs(parsed.pricingIdentityCutoffs),
+		sessions
+	};
+}
+
+/** Load against the current runtime provider/pricing fingerprint. */
+async function loadCache(pricingFingerprintValue) {
+	if (loadedCache !== null) {
+		if (loadedCache.pricingFingerprint !== pricingFingerprintValue) {
+			loadedCache = freshCache(pricingFingerprintValue, loadedCache);
+			loadPromise = Promise.resolve(loadedCache);
+		}
+		return loadedCache;
+	}
 	loadPromise ??= (async () => {
-		const fresh = { version: CACHE_VERSION, sessions: {} };
+		const fresh = freshCache(pricingFingerprintValue);
 		try {
 			const raw = await readFile(cachePath(), "utf8");
 			const parsed = JSON.parse(raw);
-			if (parsed !== null && typeof parsed === "object" && parsed.version === CACHE_VERSION && parsed.sessions !== null && typeof parsed.sessions === "object") {
-				const sessions = {};
-				for (const [id, entry] of Object.entries(parsed.sessions)) {
-					if (typeof id === "string" && id.length > 0) sessions[id] = parseSession(entry);
-				}
-				return { version: CACHE_VERSION, sessions };
+			if (parsed !== null && typeof parsed === "object" && parsed.version === CACHE_VERSION
+				&& typeof parsed.pricingFingerprint === "string"
+				&& parsed.sessions !== null && typeof parsed.sessions === "object") {
+				if (parsed.pricingFingerprint === pricingFingerprintValue) return restoredCache(parsed, pricingFingerprintValue);
+				return freshCache(pricingFingerprintValue, parsed);
 			}
 		} catch {
 			/* first run or corrupt cache */
@@ -231,7 +350,13 @@ async function saveCache(ctx, cache) {
 	try {
 		const path = cachePath();
 		await mkdir(dirname(path), { recursive: true });
-		const serialized = { version: CACHE_VERSION, sessions: {} };
+		const serialized = {
+			version: CACHE_VERSION,
+			pricingFingerprint: cache.pricingFingerprint,
+			pricingIdentityCutoffAll: cache.pricingIdentityCutoffAll,
+			pricingIdentityCutoffs: cache.pricingIdentityCutoffs,
+			sessions: {}
+		};
 		for (const [id, state] of Object.entries(cache.sessions)) serialized.sessions[id] = serializeSession(state);
 		const tmp = `${path}.tmp`;
 		await writeFile(tmp, JSON.stringify(serialized), "utf8");
@@ -266,21 +391,30 @@ function withLock(run) {
  * Sessions that vanished are dropped, and a session switching between
  * live/persisted is refolded from scratch to stay exact.
  */
-export async function collectUsage(ctx) {
+export async function collectUsage(ctx, config = { monitors: {}, budgets: validateBudgetConfig() }) {
 	return withLock(async () => {
-		const cache = await loadCache();
+		const providers = await configuredProviders(ctx);
+		const runtimePricingFingerprint = pricingFingerprint({ providers, config });
+		const cache = await loadCache(runtimePricingFingerprint);
+		const estimateCurrentCost = createUsageCostEstimator(providers, config);
+		const estimateCost = (input) => {
+			const routeCutoff = Object.hasOwn(cache.pricingIdentityCutoffs, input.providerId)
+				? cache.pricingIdentityCutoffs[input.providerId]
+				: null;
+			const cutoff = Math.max(cache.pricingIdentityCutoffAll ?? 0, routeCutoff ?? 0);
+			if (cutoff > 0 && (!Number.isFinite(input.timestamp) || input.timestamp <= cutoff)) return null;
+			return estimateCurrentCost(input);
+		};
 		const live = ctx.get("sessions");
 		const attached = new Set();
 		if (live !== void 0) {
 			for (const session of live.list()) {
 				attached.add(session.id);
 				const state = cache.sessions[session.id] ?? createUsageState();
+				if (typeof session.title === "string") state.title = session.title;
 				if (state.kind !== "live") {
 					// Live/persisted transition: refold the whole in-memory log.
-					state.days = new Map();
-					state.lastSample = null;
-					state.currentModel = null;
-					state.consumed = 0;
+					resetUsageState(state);
 				}
 				const count = session.events.length;
 				if (count < (state.consumed ?? 0)) {
@@ -290,13 +424,10 @@ export async function collectUsage(ctx) {
 					// full log would silently freeze this session's stats
 					// forever (#23). The cursor is meaningless against the
 					// rebuilt log: refold it from scratch.
-					state.days = new Map();
-					state.lastSample = null;
-					state.currentModel = null;
-					state.consumed = 0;
+					resetUsageState(state);
 				}
 				if ((state.consumed ?? 0) < count) {
-					applyUsageDelta(state, session.events.slice(state.consumed ?? 0));
+					applyUsageDelta(state, session.events.slice(state.consumed ?? 0), { estimateCost });
 					state.consumed = count;
 				}
 				state.kind = "live";
@@ -323,6 +454,7 @@ export async function collectUsage(ctx) {
 				persistedIds.add(meta.id);
 				if (attached.has(meta.id)) continue;
 				const state = cache.sessions[meta.id] ?? createUsageState();
+				if (typeof meta.title === "string") state.title = meta.title;
 				const revision = revisionOf.get(meta.id);
 				const changed = state.kind !== "persisted" || (revision !== void 0 && revision !== state.revision) || revision === void 0;
 				if (changed) {
@@ -331,24 +463,18 @@ export async function collectUsage(ctx) {
 						const fromSeq = wasPersisted ? state.consumed : 0;
 						const { events } = await persistence.readFrom(meta.id, fromSeq);
 						if (!wasPersisted) {
-							state.days = new Map();
-							state.lastSample = null;
-							state.currentModel = null;
-							state.consumed = 0;
+							resetUsageState(state);
 						}
 						const fresh = wasPersisted ? events.filter((event) => event.seq > (state.consumed ?? 0)) : events;
 						const contiguous = fresh.length === 0 ? state.consumed === 0 : fresh[0].seq === state.consumed + 1;
 						if (!contiguous && state.consumed > 0) {
 							// Log truncated or rewritten: refold the whole log.
-							state.days = new Map();
-							state.lastSample = null;
-							state.currentModel = null;
-							state.consumed = 0;
+							resetUsageState(state);
 							const { events: allEvents } = await persistence.readFrom(meta.id, 0);
-							applyUsageDelta(state, allEvents);
+							applyUsageDelta(state, allEvents, { estimateCost });
 							state.consumed = allEvents.length > 0 ? allEvents[allEvents.length - 1].seq : 0;
 						} else if (fresh.length > 0) {
-							applyUsageDelta(state, fresh);
+							applyUsageDelta(state, fresh, { estimateCost });
 							state.consumed = fresh[fresh.length - 1].seq;
 						}
 						state.kind = "persisted";
@@ -364,18 +490,28 @@ export async function collectUsage(ctx) {
 			if (!attached.has(id) && !persistedIds.has(id)) delete cache.sessions[id];
 		}
 		const byDay = new Map();
-		for (const state of Object.values(cache.sessions)) mergeInto(byDay, state.days);
+		const billingByDay = new Map();
+		for (const state of Object.values(cache.sessions)) {
+			mergeInto(byDay, state.days);
+			mergeBillingInto(billingByDay, state.billing.days);
+		}
 		// Keep the atomic cache write inside the single-flight section. Otherwise
 		// overlapping saves can race on the same temporary file.
 		await saveCache(ctx, cache);
-		return renderUsage(byDay, Date.now());
+		const updatedAt = Date.now();
+		const rendered = renderUsage(byDay, updatedAt, billingByDay);
+		return {
+			...rendered,
+			sessions: Object.entries(cache.sessions).map(([sessionId, state]) => renderSessionUsage(sessionId, state)).filter((session) => session.tokens > 0),
+			budgets: renderBudgetSummary(billingByDay, config.budgets ?? validateBudgetConfig(), updatedAt)
+		};
 	});
 }
 
-async function handleUsage(ctx, req, res) {
+async function handleUsage(ctx, config, req, res) {
 	if (rejectForeignCaller(req, res)) return;
 	try {
-		const result = await collectUsage(ctx);
+		const result = await collectUsage(ctx, config);
 		json(res, 200, { ok: true, ...result });
 	} catch (error) {
 		ctx.logger.warn(`usage-stats: usage aggregation failed: ${String(error)}`);
@@ -383,6 +519,40 @@ async function handleUsage(ctx, req, res) {
 	}
 }
 
+function exportFailure(ctx, kind, error, res) {
+	const name = error instanceof Error && typeof error.name === "string" ? error.name : "Error";
+	ctx.logger.warn(`usage-stats: ${kind} export failed (${name})`);
+	json(res, 500, { ok: false, error: "internal", message: "export failed" });
+}
+
+async function handleDailyExport(ctx, config, req, res) {
+	if (rejectForeignCaller(req, res)) return;
+	try {
+		attachment(res, "text/csv; charset=utf-8", "dsh-usage-daily.csv", dailyCsv(await collectUsage(ctx, config)));
+	} catch (error) {
+		exportFailure(ctx, "daily CSV", error, res);
+	}
+}
+
+async function handleSessionsExport(ctx, config, req, res) {
+	if (rejectForeignCaller(req, res)) return;
+	try {
+		attachment(res, "text/csv; charset=utf-8", "dsh-usage-sessions.csv", sessionsCsv(await collectUsage(ctx, config)));
+	} catch (error) {
+		exportFailure(ctx, "session CSV", error, res);
+	}
+}
+
+async function handleJsonExport(ctx, config, accounts, req, res) {
+	if (rejectForeignCaller(req, res)) return;
+	try {
+		const [usage, providerViews] = await Promise.all([collectUsage(ctx, config), accounts.providerViews()]);
+		attachment(res, "application/json; charset=utf-8", "dsh-usage-stats.json", JSON.stringify(jsonExport(usage, providerViews)));
+	} catch (error) {
+		exportFailure(ctx, "JSON", error, res);
+	}
+}
+
 /**
  * Enumerate the harness's configured providers: the official DeepSeek route
  * (`llm-deepseek` settings namespace) plus every pi-ai provider profile
@@ -423,6 +593,106 @@ async function configuredProviders(ctx) {
 	return providers;
 }
 
+/**
+ * Resolve one live DSH session's provider/model pair. A bounded route hint from
+ * the formal per-session model selector wins for immediate pre-turn switches;
+ * the incremental event fold remains the no-hint source and history fallback.
+ * Both paths still pass through the shared identity resolver, remain O(new
+ * events), and add no stream listener, provider request, cache, or usage ledger.
+ */
+export async function collectSessionContext(ctx, sessionId, config = { monitors: {} }, selectedRoute = null) {
+	await collectUsage(ctx, config);
+	const sessions = ctx.get("sessions");
+	const live = sessions?.get?.(sessionId) ?? sessions?.list?.().find((session) => session.id === sessionId);
+	if (live === void 0) return null;
+	const cache = loadedCache;
+	if (cache === null) return null;
+	const state = cache.sessions[sessionId];
+	if (state?.kind !== "live") return null;
+	const currentRoute = selectedRoute ?? state.currentRoute;
+	if (currentRoute === null || currentRoute === void 0) return null;
+	const providers = await configuredProviders(ctx);
+	const provider = providers.find((entry) => entry.id === currentRoute.providerId)
+		?? { id: currentRoute.providerId, displayName: currentRoute.providerId };
+	return {
+		...currentSessionContext(sessionId, { ...state, currentRoute }, provider, config),
+		session: renderSessionUsage(sessionId, state)
+	};
+}
+
+/** Resolve the current account ids for every live session without a new ledger or provider guess. */
+export async function collectActiveAccountIds(ctx, config = { monitors: {} }) {
+	await collectUsage(ctx, config);
+	const sessions = ctx.get("sessions")?.list?.() ?? [];
+	const cache = loadedCache;
+	if (cache === null) return [];
+	const providers = await configuredProviders(ctx);
+	const byId = new Map(providers.map((provider) => [provider.id, provider]));
+	const accountIds = new Set();
+	for (const session of sessions) {
+		const state = cache.sessions[session.id];
+		if (state?.kind !== "live" || state.currentRoute === null || state.currentRoute === void 0) continue;
+		const provider = byId.get(state.currentRoute.providerId)
+			?? { id: state.currentRoute.providerId, displayName: state.currentRoute.providerId };
+		const context = currentSessionContext(session.id, state, provider, config);
+		if (typeof context?.accountId === "string" && context.accountId !== "") accountIds.add(context.accountId);
+	}
+	return [...accountIds];
+}
+
+/** Session context is explicit in multi-session DSH; a single live session is unambiguous. */
+async function handleSessionContext(ctx, config, accounts, req, res) {
+	if (rejectForeignCaller(req, res)) return;
+	try {
+		// Client loader entries carry module identity, not the server Cordis
+		// config. Keep the display policy server-owned on this existing request:
+		// a hidden Pill performs no usage fold or account read and renders null.
+		if (config.display?.currentSessionPill === false) {
+			json(res, 200, { ok: true, context: null, display: { currentSessionPill: false } });
+			return;
+		}
+		const url = new URL(req.url ?? "/", "http://x");
+		const requested = url.searchParams.get("session");
+		const selectedProvider = url.searchParams.get("provider");
+		const selectedModel = url.searchParams.get("model");
+		if ((selectedProvider === null) !== (selectedModel === null)
+			|| selectedProvider !== null && (selectedProvider === "" || selectedProvider.length > 256 || selectedProvider.includes("\0"))
+			|| selectedModel !== null && (selectedModel === "" || selectedModel.length > 512 || selectedModel.includes("\0"))) {
+			json(res, 400, { ok: false, error: "invalid-selection", message: "provider and model must be supplied together as bounded non-empty values" });
+			return;
+		}
+		const sessions = ctx.get("sessions")?.list?.() ?? [];
+		let sessionId = requested === null || requested === "" ? null : requested;
+		if (sessionId === null && sessions.length === 1) sessionId = sessions[0].id;
+		if (sessionId === null && sessions.length > 1) {
+			json(res, 400, { ok: false, error: "session-required", message: "session query parameter is required when multiple sessions are live" });
+			return;
+		}
+		if (sessionId === null) {
+			json(res, 200, { ok: true, context: null });
+			return;
+		}
+		if (!sessions.some((session) => session.id === sessionId)) {
+			json(res, 404, { ok: false, error: "unknown-session", message: `session "${sessionId}" is not live` });
+			return;
+		}
+		// The browser hint comes from DSH's formal per-session model directory.
+		// It carries route identity only; configuredProviders + the shared resolver
+		// below remain authoritative for family/account normalization.
+		const selectedRoute = selectedProvider === null ? null : {
+			providerId: selectedProvider,
+			model: selectedModel,
+			updatedAt: null
+		};
+		const context = await collectSessionContext(ctx, sessionId, config, selectedRoute);
+		if (typeof context?.accountId === "string" && context.accountId !== "") accounts.touch?.(context.accountId, "active");
+		json(res, 200, { ok: true, context, display: { currentSessionPill: true } });
+	} catch (error) {
+		ctx.logger.warn(`usage-stats: session context failed: ${String(error)}`);
+		json(res, 500, { ok: false, error: "internal", message: error instanceof Error ? error.message : String(error) });
+	}
+}
+
 async function handleProviders(ctx, accounts, req, res) {
 	if (rejectForeignCaller(req, res)) return;
 	try {
@@ -450,7 +720,9 @@ async function handleAccount(ctx, accounts, req, res) {
 	try {
 		const url = new URL(req.url ?? "/", "http://x");
 		const providerId = await selectedProviderId(req, accounts);
-		const account = providerId === null ? null : await accounts.get(providerId, { force: url.searchParams.get("refresh") === "1" });
+		const requestedActivity = url.searchParams.get("activity");
+		const activity = requestedActivity === "active" || requestedActivity === "detail" ? requestedActivity : null;
+		const account = providerId === null ? null : await accounts.get(providerId, { force: url.searchParams.get("refresh") === "1", activity });
 		if (account === null) {
 			json(res, 200, { ok: false, error: "unknown-provider", message: `provider "${providerId}" is not configured` });
 			return;
@@ -526,41 +798,104 @@ async function handleSubscriptions(ctx, accounts, req, res) {
 	}
 }
 
-/** Start an immediate refresh and repeat account + local usage refresh every 5 minutes. */
+/** Existing five-minute usage fold plus an optional adaptive account scheduler. */
 export function startBackgroundRefresh(ctx, accounts, deps = {}) {
 	let running = false;
 	let stopped = false;
 	let active = Promise.resolve();
-	const run = async () => {
-		if (running || stopped) return;
+	let timer = null;
+	let scheduleGeneration = 0;
+	let nextUsageAt = 0;
+	const now = deps.now ?? Date.now;
+	const usageIntervalMs = deps.usageIntervalMs ?? ACCOUNT_REFRESH_MS;
+	const setTimer = deps.setTimeout ?? setTimeout;
+	const clearTimer = deps.clearTimeout ?? clearTimeout;
+	const config = deps.config ?? { monitors: {} };
+	const accountRefreshEnabled = deps.accountRefreshEnabled !== false;
+
+	const clearScheduled = () => {
+		if (timer === null) return;
+		clearTimer(timer);
+		timer = null;
+	};
+
+	const schedule = async () => {
+		if (stopped) return;
+		const generation = ++scheduleGeneration;
+		clearScheduled();
+		let accountNext = null;
+		if (accountRefreshEnabled) {
+			try {
+				accountNext = await accounts.nextRefreshAt();
+			} catch (error) {
+				ctx.logger.warn(`usage-stats: refresh scheduling failed: ${String(error)}`);
+			}
+		}
+		if (stopped || generation !== scheduleGeneration) return;
+		const target = Math.min(accountNext ?? Infinity, nextUsageAt);
+		const delay = Math.max(1000, Number.isFinite(target) ? target - now() : usageIntervalMs);
+		timer = setTimer(() => {
+			timer = null;
+			void run();
+		}, delay);
+		timer?.unref?.();
+	};
+
+	const run = async (force = false) => {
+		if (stopped) return;
+		if (running) {
+			await active;
+			return force && !stopped ? run(true) : void 0;
+		}
+		clearScheduled();
 		running = true;
 		active = (async () => {
-			const results = await Promise.allSettled([accounts.refreshAll(), collectUsage(ctx)]);
-			for (const result of results) if (result.status === "rejected") ctx.logger.warn(`usage-stats: background refresh failed: ${String(result.reason)}`);
+			const at = now();
+			if (force || at >= nextUsageAt) {
+				try {
+					if (accountRefreshEnabled) accounts.setActiveProviders(await collectActiveAccountIds(ctx, config));
+					else await collectUsage(ctx, config);
+				} catch (error) {
+					ctx.logger.warn(`usage-stats: background usage refresh failed: ${String(error)}`);
+				}
+				nextUsageAt = now() + usageIntervalMs;
+			}
+			if (accountRefreshEnabled) {
+				try {
+					await accounts.refreshDue({ force });
+				} catch (error) {
+					ctx.logger.warn(`usage-stats: background account refresh failed: ${String(error)}`);
+				}
+			}
 		})().finally(() => {
 			running = false;
 		});
-		return active;
+		await active;
+		await schedule();
 	};
-	void run();
-	const setTimer = deps.setInterval ?? setInterval;
-	const clearTimer = deps.clearInterval ?? clearInterval;
-	const timer = setTimer(run, deps.intervalMs ?? ACCOUNT_REFRESH_MS);
-	timer?.unref?.();
+	let unsubscribePolicyChanges = () => {};
+	if (accountRefreshEnabled) {
+		unsubscribePolicyChanges = accounts.subscribePolicyChanges?.(() => {
+			// Activity changes only rearm this one central timer. The service remains
+			// responsible for deciding whether an upstream refresh is actually due.
+			if (!stopped && !running) void schedule();
+		}) ?? unsubscribePolicyChanges;
+	}
+	const ready = run();
 	const stop = async () => {
 		stopped = true;
-		clearTimer(timer);
-		await active;
-	};
-	stop.refreshNow = async () => {
+		scheduleGeneration += 1;
+		clearScheduled();
+		unsubscribePolicyChanges();
 		await active;
-		return run();
 	};
+	stop.ready = ready;
+	stop.refreshNow = () => run(true);
 	return stop;
 }
 
 /**
- * Plugin body: register the five exact routes and start background refresh.
+ * Plugin body: register the nine exact routes and start background refresh.
  * @param ctx - plugin context carrying webServer, credentials, sessions, sessionPersistence, settings, and llm.
  */
 const Config = {
@@ -569,7 +904,7 @@ const Config = {
 		vendor: "dsh-usage-stats",
 		validate(value) {
 			try {
-				return { value: validateAccountConfig(value ?? {}) };
+				return { value: validateConfig(value ?? {}) };
 			} catch (error) {
 				return { issues: [{ message: error instanceof Error ? error.message : String(error) }] };
 			}
@@ -577,8 +912,22 @@ const Config = {
 	}
 };
 
+function validateConfig(raw = {}) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new Error("plugin config must be an object");
+	const display = raw.display ?? {};
+	if (display === null || typeof display !== "object" || Array.isArray(display)) throw new Error("display must be an object");
+	if (display.currentSessionPill !== void 0 && typeof display.currentSessionPill !== "boolean") {
+		throw new Error("display.currentSessionPill must be a boolean");
+	}
+	return {
+		...validateAccountConfig(raw),
+		budgets: validateBudgetConfig(raw.budgets),
+		display: { currentSessionPill: display.currentSessionPill !== false }
+	};
+}
+
 async function apply(ctx, rawConfig = {}, deps = {}) {
-	const config = validateAccountConfig(rawConfig);
+	const config = validateConfig(rawConfig);
 	const accounts = deps.accounts ?? createAccountService({
 		credentials: ctx.get("credentials") ?? ctx.credentials,
 		getProviders: () => configuredProviders(ctx),
@@ -591,7 +940,7 @@ async function apply(ctx, rawConfig = {}, deps = {}) {
 	ctx.effect(() => ctx.webServer.register({
 		kind: "exact",
 		path: USAGE_PATH,
-		handler: (req, res) => handleUsage(ctx, req, res)
+		handler: (req, res) => handleUsage(ctx, config, req, res)
 	}), "usage-stats: usage route");
 	ctx.effect(() => ctx.webServer.register({
 		kind: "exact",
@@ -613,7 +962,30 @@ async function apply(ctx, rawConfig = {}, deps = {}) {
 		path: SUBSCRIPTIONS_PATH,
 		handler: (req, res) => handleSubscriptions(ctx, accounts, req, res)
 	}), "usage-stats: subscriptions route");
-	if (deps.disableBackgroundRefresh !== true) ctx.effect(() => startBackgroundRefresh(ctx, accounts), "usage-stats: background account refresh");
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: SESSION_CONTEXT_PATH,
+		handler: (req, res) => handleSessionContext(ctx, config, accounts, req, res)
+	}), "usage-stats: session context route");
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: DAILY_EXPORT_PATH,
+		handler: (req, res) => handleDailyExport(ctx, config, req, res)
+	}), "usage-stats: daily CSV export route");
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: SESSIONS_EXPORT_PATH,
+		handler: (req, res) => handleSessionsExport(ctx, config, req, res)
+	}), "usage-stats: sessions CSV export route");
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: JSON_EXPORT_PATH,
+		handler: (req, res) => handleJsonExport(ctx, config, accounts, req, res)
+	}), "usage-stats: JSON export route");
+	if (deps.disableBackgroundRefresh !== true) ctx.effect(() => startBackgroundRefresh(ctx, accounts, {
+		config,
+		accountRefreshEnabled: config.refresh.enabled
+	}), "usage-stats: background usage/account refresh");
 }
 
-export { apply, Config, inject, name, USAGE_PATH, PROVIDERS_PATH, BALANCE_PATH, SUBSCRIPTIONS_PATH, ACCOUNT_PATH, configuredProviders, totalTokens, zeroBuckets };
+export { apply, Config, inject, name, USAGE_PATH, PROVIDERS_PATH, BALANCE_PATH, SUBSCRIPTIONS_PATH, ACCOUNT_PATH, SESSION_CONTEXT_PATH, DAILY_EXPORT_PATH, SESSIONS_EXPORT_PATH, JSON_EXPORT_PATH, configuredProviders, totalTokens, validateConfig, zeroBuckets };