@ychris12138/dsh-usage-stats 0.3.0 → 0.3.2

package/lib/index.js

@@ -1,7 +1,8 @@
 /**
  * dsh-usage-stats — server half.
  *
- * Registers nine read-only, loopback-only endpoints on the web server:
+ * Registers nine read-only, loopback-only data endpoints plus one explicit
+ * loopback-only OrcaRouter settings action 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>)
@@ -11,6 +12,7 @@
  *   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
+ *   GET|POST /api/usage-stats/integrations/orcarouter — status / explicit add
  *
  * Provider configuration is read straight from the harness settings
  * (`llm-deepseek` for the official DeepSeek route, `llm-pi-ai` for every
@@ -41,6 +43,7 @@ import { applyUsageDelta, createUsageState, currentSessionContext, mergeBillingI
 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";
+import { addOrcaRouterPreset, orcaRouterIntegrationState } from "./orcarouter.js";
 
 /** Stable Cordis plugin name. */
 const name = "usage-stats";
@@ -57,6 +60,7 @@ 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 ORCAROUTER_INTEGRATION_PATH = "/api/usage-stats/integrations/orcarouter";
 const UPSTREAM_TIMEOUT_MS = 15000;
 const CACHE_VERSION = 5;
 
@@ -138,6 +142,29 @@ function rejectForeignCaller(req, res) {
 	return true;
 }
 
+/**
+ * Fence the sole settings mutation. The custom action header makes this a
+ * non-simple browser request, so a foreign page cannot CSRF the loopback route
+ * without a CORS preflight (the exact route never grants CORS).
+ */
+function rejectForeignMutation(req, res) {
+	if (req.method !== "POST") {
+		json(res, 405, { ok: false, error: "method-not-allowed" });
+		return true;
+	}
+	const peer = req.socket?.remoteAddress;
+	if (!isLoopbackAddress(peer) || !isLoopbackHostHeader(req)) {
+		json(res, 403, { ok: false, error: "forbidden" });
+		return true;
+	}
+	const contentType = typeof req.headers["content-type"] === "string" ? req.headers["content-type"].toLowerCase() : "";
+	if (!contentType.startsWith("application/json") || req.headers["x-dsh-usage-stats-action"] !== "add-orcarouter") {
+		json(res, 403, { ok: false, error: "forbidden-action" });
+		return true;
+	}
+	return false;
+}
+
 //#region incremental cache
 /** Cache file location under the dsh home. */
 function cachePath() {
@@ -149,6 +176,37 @@ let loadedCache = null;
 let loadPromise = null;
 let inflight = null;
 
+// Runtime-only cache bookkeeping. Nothing in this WeakMap is serialized to
+// disk: the on-disk schema remains CACHE_VERSION=5. Keeping the aggregate and
+// dirty flags out of the persisted shape also means old cache files remain
+// valid while hot UI reads can skip redundant work.
+const cacheRuntime = new WeakMap();
+
+function runtimeOf(cache) {
+	let runtime = cacheRuntime.get(cache);
+	if (runtime === void 0) {
+		runtime = {
+			dirty: false,
+			aggregate: null,
+			aggregateDirty: true
+		};
+		cacheRuntime.set(cache, runtime);
+	}
+	return runtime;
+}
+
+function markCacheChanged(cache) {
+	const runtime = runtimeOf(cache);
+	runtime.dirty = true;
+	runtime.aggregateDirty = true;
+}
+
+function diagnostic(ctx, name) {
+	const stats = ctx?.__usageStatsDiagnostics;
+	if (stats === null || typeof stats !== "object") return;
+	stats[name] = (stats[name] ?? 0) + 1;
+}
+
 /** Serialize one session's fold state (Maps → plain objects). */
 function serializeSession(state) {
 	const days = {};
@@ -282,6 +340,7 @@ function parsePricingIdentityCutoffs(raw) {
 }
 
 function freshCache(pricingFingerprintValue, previous = null, transitionAt = Date.now()) {
+	const fingerprintChanged = previous !== null && previous.pricingFingerprint !== pricingFingerprintValue;
 	const pricingIdentityCutoffs = parsePricingIdentityCutoffs(previous?.pricingIdentityCutoffs);
 	let pricingIdentityCutoffAll = Number.isFinite(previous?.pricingIdentityCutoffAll) && previous.pricingIdentityCutoffAll >= 0
 		? previous.pricingIdentityCutoffAll
@@ -291,13 +350,19 @@ function freshCache(pricingFingerprintValue, previous = null, transitionAt = Dat
 		if (changedRoutes === null) pricingIdentityCutoffAll = Math.max(pricingIdentityCutoffAll ?? 0, transitionAt);
 		else for (const routeId of changedRoutes) pricingIdentityCutoffs[routeId] = Math.max(pricingIdentityCutoffs[routeId] ?? 0, transitionAt);
 	}
-	return {
+	const cache = {
 		version: CACHE_VERSION,
 		pricingFingerprint: pricingFingerprintValue,
 		pricingIdentityCutoffAll,
 		pricingIdentityCutoffs,
 		sessions: {}
 	};
+	const runtime = runtimeOf(cache);
+	// A pricing identity/catalog change invalidates all derived billing. Mark
+	// the replacement dirty even when the next collection deliberately avoids
+	// a persisted scan, so the stale fingerprint cannot survive a restart.
+	if (fingerprintChanged) runtime.dirty = true;
+	return cache;
 }
 
 function restoredCache(parsed, pricingFingerprintValue) {
@@ -305,7 +370,7 @@ function restoredCache(parsed, pricingFingerprintValue) {
 	for (const [id, entry] of Object.entries(parsed.sessions)) {
 		if (typeof id === "string" && id.length > 0) sessions[id] = parseSession(entry);
 	}
-	return {
+	const cache = {
 		version: CACHE_VERSION,
 		pricingFingerprint: pricingFingerprintValue,
 		pricingIdentityCutoffAll: Number.isFinite(parsed.pricingIdentityCutoffAll) && parsed.pricingIdentityCutoffAll >= 0
@@ -314,6 +379,8 @@ function restoredCache(parsed, pricingFingerprintValue) {
 		pricingIdentityCutoffs: parsePricingIdentityCutoffs(parsed.pricingIdentityCutoffs),
 		sessions
 	};
+	runtimeOf(cache);
+	return cache;
 }
 
 /** Load against the current runtime provider/pricing fingerprint. */
@@ -347,6 +414,8 @@ async function loadCache(pricingFingerprintValue) {
 
 /** Persist the cache atomically (temp + rename); failures are logged, never fatal. */
 async function saveCache(ctx, cache) {
+	const runtime = runtimeOf(cache);
+	if (!runtime.dirty) return false;
 	try {
 		const path = cachePath();
 		await mkdir(dirname(path), { recursive: true });
@@ -361,18 +430,32 @@ async function saveCache(ctx, cache) {
 		const tmp = `${path}.tmp`;
 		await writeFile(tmp, JSON.stringify(serialized), "utf8");
 		await rename(tmp, path);
+		runtime.dirty = false;
+		diagnostic(ctx, "cacheWrites");
+		return true;
 	} catch (error) {
 		ctx.logger.warn(`usage-stats: saving usage cache failed: ${String(error)}`);
+		return false;
 	}
 }
 
-/** Single-flight guard: concurrent requests share one aggregation run. */
-function withLock(run) {
-	if (inflight !== null) return inflight;
-	inflight = run().finally(() => {
-		inflight = null;
+/**
+ * Single-flight guard: concurrent requests share compatible aggregation work.
+ * A full persisted scan cannot be satisfied by an already-running live-only
+ * collection; it waits for that run and then performs its own full pass.
+ */
+function withCollectionLock(scanPersisted, run) {
+	if (inflight !== null) {
+		if (!scanPersisted || inflight.scanPersisted) return inflight.promise;
+		const waitForLive = () => withCollectionLock(true, run);
+		return inflight.promise.then(waitForLive, waitForLive);
+	}
+	const entry = { scanPersisted, promise: null };
+	entry.promise = run().finally(() => {
+		if (inflight === entry) inflight = null;
 	});
-	return inflight;
+	inflight = entry;
+	return entry.promise;
 }
 //#endregion
 
@@ -389,10 +472,47 @@ function withLock(run) {
  * to be contiguous with the last folded seq — a gap or an empty delta means
  * the log was truncated/rewritten, so the session is refolded from scratch.
  * Sessions that vanished are dropped, and a session switching between
- * live/persisted is refolded from scratch to stay exact.
+ * live/persisted is refolded from scratch to stay exact. High-frequency UI
+ * reads pass `{ scanPersisted: false }`: cached persisted folds remain in the
+ * aggregate, but the persistence backend is not enumerated or read. The
+ * five-minute background fold and exports use the default full scan.
  */
-export async function collectUsage(ctx, config = { monitors: {}, budgets: validateBudgetConfig() }) {
-	return withLock(async () => {
+function liveSessionAdapter(session) {
+	if (session === null || typeof session !== "object") throw new TypeError("live session must be an object");
+	if (typeof session.snapshotEvents === "function") {
+		if (!("seq" in session)) throw new TypeError("live session exposes an incomplete snapshot API");
+		return {
+			count() {
+				const count = session.seq;
+				if (!Number.isSafeInteger(count) || count < 0) throw new TypeError("live session seq must be a non-negative safe integer");
+				return count;
+			},
+			tail(fromSeq) {
+				const events = session.snapshotEvents(fromSeq);
+				if (!Array.isArray(events)) throw new TypeError("live session snapshotEvents() must return an array");
+				return events;
+			}
+		};
+	}
+	const legacyEvents = session.events;
+	if (!Array.isArray(legacyEvents)) throw new TypeError("live session does not expose a supported snapshot API");
+	return {
+		count() {
+			const events = session.events;
+			if (!Array.isArray(events)) throw new TypeError("legacy live session events must be an array");
+			return events.length;
+		},
+		tail(fromSeq) {
+			const events = session.events;
+			if (!Array.isArray(events)) throw new TypeError("legacy live session events must be an array");
+			return events.slice(fromSeq);
+		}
+	};
+}
+
+export async function collectUsage(ctx, config = { monitors: {}, budgets: validateBudgetConfig() }, options = {}) {
+	const scanPersisted = options?.scanPersisted !== false;
+	return withCollectionLock(scanPersisted, async () => {
 		const providers = await configuredProviders(ctx);
 		const runtimePricingFingerprint = pricingFingerprint({ providers, config });
 		const cache = await loadCache(runtimePricingFingerprint);
@@ -410,13 +530,23 @@ export async function collectUsage(ctx, config = { monitors: {}, budgets: valida
 		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;
+				const liveAdapter = liveSessionAdapter(session);
+				let state = cache.sessions[session.id];
+				let stateChanged = false;
+				if (state === void 0) {
+					state = createUsageState();
+					stateChanged = true;
+				}
+				if (typeof session.title === "string" && state.title !== session.title) {
+					state.title = session.title;
+					stateChanged = true;
+				}
 				if (state.kind !== "live") {
 					// Live/persisted transition: refold the whole in-memory log.
 					resetUsageState(state);
+					stateChanged = true;
 				}
-				const count = session.events.length;
+				const count = liveAdapter.count();
 				if (count < (state.consumed ?? 0)) {
 					// The in-memory log shrank below the folded cursor — DSH
 					// restores sessions from disk as compressed summaries after
@@ -425,76 +555,127 @@ export async function collectUsage(ctx, config = { monitors: {}, budgets: valida
 					// forever (#23). The cursor is meaningless against the
 					// rebuilt log: refold it from scratch.
 					resetUsageState(state);
+					stateChanged = true;
 				}
 				if ((state.consumed ?? 0) < count) {
-					applyUsageDelta(state, session.events.slice(state.consumed ?? 0), { estimateCost });
+					applyUsageDelta(state, liveAdapter.tail(state.consumed ?? 0), { estimateCost });
 					state.consumed = count;
+					stateChanged = true;
+				}
+				if (state.kind !== "live") {
+					state.kind = "live";
+					stateChanged = true;
 				}
-				state.kind = "live";
 				cache.sessions[session.id] = state;
+				if (stateChanged) markCacheChanged(cache);
 			}
 		}
 		const persistence = ctx.get("sessionPersistence");
 		const persistedIds = new Set();
-		if (persistence !== void 0) {
+		if (scanPersisted && persistence !== void 0) {
 			// Prefer the backend's opaque per-log revisions (no file I/O in the
 			// plugin, works for any backend that exposes listSnapshots).
 			let snapshots = null;
 			if (typeof persistence.listSnapshots === "function") {
 				try {
+					diagnostic(ctx, "listSnapshots");
 					snapshots = await persistence.listSnapshots();
 				} catch (error) {
 					ctx.logger.warn(`usage-stats: listSnapshots failed, falling back to list(): ${String(error)}`);
 				}
 			}
-			const metas = snapshots !== null ? snapshots.map((entry) => entry.header) : await persistence.list();
+			let metas;
+			if (snapshots !== null) metas = snapshots.map((entry) => entry.header);
+			else {
+				diagnostic(ctx, "list");
+				metas = typeof persistence.list === "function" ? await persistence.list() : [];
+			}
 			const revisionOf = new Map();
 			if (snapshots !== null) for (const entry of snapshots) revisionOf.set(entry.header.id, entry.revision);
 			for (const meta of metas) {
 				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;
+				let state = cache.sessions[meta.id];
+				let stateChanged = false;
+				if (state === void 0) {
+					state = createUsageState();
+					stateChanged = true;
+				}
+				if (typeof meta.title === "string" && state.title !== meta.title) {
+					state.title = meta.title;
+					stateChanged = true;
+				}
 				const revision = revisionOf.get(meta.id);
-				const changed = state.kind !== "persisted" || (revision !== void 0 && revision !== state.revision) || revision === void 0;
+				const revisionChanged = revision !== void 0 && revision !== state.revision;
+				const changed = state.kind !== "persisted" || revisionChanged || revision === void 0;
+				if (revisionChanged) stateChanged = true;
 				if (changed) {
 					try {
 						const wasPersisted = state.kind === "persisted";
 						const fromSeq = wasPersisted ? state.consumed : 0;
+						diagnostic(ctx, "readFrom");
 						const { events } = await persistence.readFrom(meta.id, fromSeq);
 						if (!wasPersisted) {
 							resetUsageState(state);
+							stateChanged = true;
 						}
 						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;
+						// readFrom is inclusive: an unchanged log returns exactly the
+						// already-folded cursor event (seq === consumed). An empty
+						// fresh slice with the cursor still present is therefore NOT a
+						// rewrite — only a log that no longer contains the cursor
+						// (truncated/rewritten) must refold from scratch.
+						const contiguous = fresh.length === 0
+							? wasPersisted && events.some((event) => event.seq === (state.consumed ?? 0))
+							: fresh[0].seq === state.consumed + 1;
 						if (!contiguous && state.consumed > 0) {
 							// Log truncated or rewritten: refold the whole log.
 							resetUsageState(state);
+							stateChanged = true;
+							diagnostic(ctx, "readFrom");
 							const { events: allEvents } = await persistence.readFrom(meta.id, 0);
 							applyUsageDelta(state, allEvents, { estimateCost });
 							state.consumed = allEvents.length > 0 ? allEvents[allEvents.length - 1].seq : 0;
 						} else if (fresh.length > 0) {
 							applyUsageDelta(state, fresh, { estimateCost });
 							state.consumed = fresh[fresh.length - 1].seq;
+							stateChanged = true;
+						}
+						if (state.kind !== "persisted") {
+							state.kind = "persisted";
+							stateChanged = true;
+						}
+						if (revision !== void 0 && state.revision !== revision) {
+							state.revision = revision;
+							stateChanged = true;
 						}
-						state.kind = "persisted";
-						if (revision !== void 0) state.revision = revision;
 					} catch (error) {
 						ctx.logger.warn(`usage-stats: reading persisted session "${meta.id}" failed: ${String(error)}`);
 					}
 				}
 				cache.sessions[meta.id] = state;
+				if (stateChanged) markCacheChanged(cache);
+			}
+			for (const id of Object.keys(cache.sessions)) {
+				if (!attached.has(id) && !persistedIds.has(id)) {
+					delete cache.sessions[id];
+					markCacheChanged(cache);
+				}
 			}
 		}
-		for (const id of Object.keys(cache.sessions)) {
-			if (!attached.has(id) && !persistedIds.has(id)) delete cache.sessions[id];
-		}
-		const byDay = new Map();
-		const billingByDay = new Map();
-		for (const state of Object.values(cache.sessions)) {
-			mergeInto(byDay, state.days);
-			mergeBillingInto(billingByDay, state.billing.days);
+		const runtime = runtimeOf(cache);
+		if (runtime.aggregate === null || runtime.aggregateDirty) {
+			diagnostic(ctx, "aggregateRebuilds");
+			const byDay = new Map();
+			const billingByDay = new Map();
+			for (const state of Object.values(cache.sessions)) {
+				mergeInto(byDay, state.days);
+				mergeBillingInto(billingByDay, state.billing.days);
+			}
+			runtime.aggregate = { byDay, billingByDay };
+			runtime.aggregateDirty = false;
 		}
+		const { byDay, billingByDay } = runtime.aggregate;
 		// Keep the atomic cache write inside the single-flight section. Otherwise
 		// overlapping saves can race on the same temporary file.
 		await saveCache(ctx, cache);
@@ -511,7 +692,7 @@ export async function collectUsage(ctx, config = { monitors: {}, budgets: valida
 async function handleUsage(ctx, config, req, res) {
 	if (rejectForeignCaller(req, res)) return;
 	try {
-		const result = await collectUsage(ctx, config);
+		const result = await collectUsage(ctx, config, { scanPersisted: false });
 		json(res, 200, { ok: true, ...result });
 	} catch (error) {
 		ctx.logger.warn(`usage-stats: usage aggregation failed: ${String(error)}`);
@@ -528,7 +709,7 @@ function exportFailure(ctx, kind, error, res) {
 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)));
+		attachment(res, "text/csv; charset=utf-8", "dsh-usage-daily.csv", dailyCsv(await collectUsage(ctx, config, { scanPersisted: true })));
 	} catch (error) {
 		exportFailure(ctx, "daily CSV", error, res);
 	}
@@ -537,7 +718,7 @@ async function handleDailyExport(ctx, config, req, 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)));
+		attachment(res, "text/csv; charset=utf-8", "dsh-usage-sessions.csv", sessionsCsv(await collectUsage(ctx, config, { scanPersisted: true })));
 	} catch (error) {
 		exportFailure(ctx, "session CSV", error, res);
 	}
@@ -546,7 +727,10 @@ async function handleSessionsExport(ctx, config, req, 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()]);
+		const [usage, providerViews] = await Promise.all([
+			collectUsage(ctx, config, { scanPersisted: true }),
+			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);
@@ -601,7 +785,7 @@ async function configuredProviders(ctx) {
  * 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);
+	await collectUsage(ctx, config, { scanPersisted: false });
 	const sessions = ctx.get("sessions");
 	const live = sessions?.get?.(sessionId) ?? sessions?.list?.().find((session) => session.id === sessionId);
 	if (live === void 0) return null;
@@ -621,8 +805,8 @@ export async function collectSessionContext(ctx, sessionId, config = { monitors:
 }
 
 /** 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);
+export async function collectActiveAccountIds(ctx, config = { monitors: {} }, options = { scanPersisted: false }) {
+	await collectUsage(ctx, config, options);
 	const sessions = ctx.get("sessions")?.list?.() ?? [];
 	const cache = loadedCache;
 	if (cache === null) return [];
@@ -644,9 +828,8 @@ export async function collectActiveAccountIds(ctx, config = { monitors: {} }) {
 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.
+		// Preserve the v0.3.0 API response for the legacy display flag even though
+		// the current client no longer renders any composer UI.
 		if (config.display?.currentSessionPill === false) {
 			json(res, 200, { ok: true, context: null, display: { currentSessionPill: false } });
 			return;
@@ -703,6 +886,37 @@ async function handleProviders(ctx, accounts, req, res) {
 	}
 }
 
+/** Read secret-free preset state or perform the user's explicit path mutation. */
+async function handleOrcaRouterIntegration(ctx, req, res) {
+	if (req.method === "GET") {
+		if (rejectForeignCaller(req, res)) return;
+		try {
+			json(res, 200, { ok: true, integration: orcaRouterIntegrationState(ctx.get("settings")) });
+		} catch (error) {
+			ctx.logger.warn(`usage-stats: OrcaRouter integration status failed: ${String(error)}`);
+			json(res, 500, { ok: false, error: "internal", message: "settings status unavailable" });
+		}
+		return;
+	}
+	if (rejectForeignMutation(req, res)) return;
+	try {
+		const integration = await addOrcaRouterPreset(ctx.get("settings"));
+		if (!integration.available) {
+			json(res, 409, { ok: false, error: "settings-unavailable", message: "DSH provider settings are not writable" });
+			return;
+		}
+		json(res, 200, { ok: true, integration });
+	} catch (error) {
+		const conflict = error?.code === "SETTINGS_CONFLICT";
+		ctx.logger.warn(`usage-stats: OrcaRouter settings mutation failed (${conflict ? "conflict" : "rejected"})`);
+		json(res, conflict ? 409 : 422, {
+			ok: false,
+			error: conflict ? "settings-conflict" : "settings-update-rejected",
+			message: conflict ? "provider settings changed; retry the action" : "DSH rejected the provider preset"
+		});
+	}
+}
+
 async function selectedProviderId(req, accounts) {
 	const url = new URL(req.url ?? "/", "http://x");
 	const requested = url.searchParams.get("provider");
@@ -853,8 +1067,8 @@ export function startBackgroundRefresh(ctx, accounts, deps = {}) {
 			const at = now();
 			if (force || at >= nextUsageAt) {
 				try {
-					if (accountRefreshEnabled) accounts.setActiveProviders(await collectActiveAccountIds(ctx, config));
-					else await collectUsage(ctx, config);
+					if (accountRefreshEnabled) accounts.setActiveProviders(await collectActiveAccountIds(ctx, config, { scanPersisted: true }));
+					else await collectUsage(ctx, config, { scanPersisted: true });
 				} catch (error) {
 					ctx.logger.warn(`usage-stats: background usage refresh failed: ${String(error)}`);
 				}
@@ -895,7 +1109,8 @@ export function startBackgroundRefresh(ctx, accounts, deps = {}) {
 }
 
 /**
- * Plugin body: register the nine exact routes and start background refresh.
+ * Plugin body: register nine data routes plus the explicit integration route,
+ * then start background refresh.
  * @param ctx - plugin context carrying webServer, credentials, sessions, sessionPersistence, settings, and llm.
  */
 const Config = {
@@ -967,6 +1182,11 @@ async function apply(ctx, rawConfig = {}, deps = {}) {
 		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: ORCAROUTER_INTEGRATION_PATH,
+		handler: (req, res) => handleOrcaRouterIntegration(ctx, req, res)
+	}), "usage-stats: optional OrcaRouter integration route");
 	ctx.effect(() => ctx.webServer.register({
 		kind: "exact",
 		path: DAILY_EXPORT_PATH,
@@ -988,4 +1208,4 @@ async function apply(ctx, rawConfig = {}, deps = {}) {
 	}), "usage-stats: background usage/account refresh");
 }
 
-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 };
+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, ORCAROUTER_INTEGRATION_PATH, configuredProviders, totalTokens, validateConfig, zeroBuckets };

package/lib/orcarouter.js

@@ -0,0 +1,79 @@
+/**
+ * Optional OrcaRouter provider preset and its narrow DSH settings mutation.
+ *
+ * The plugin never edits settings.yaml directly and never installs this route
+ * during startup. A caller must explicitly request the single path mutation;
+ * an existing `orcarouter` profile always wins unchanged.
+ *
+ * @module dsh-usage-stats/orcarouter
+ */
+
+const SETTINGS_NAMESPACE = "llm-pi-ai";
+const PROVIDER_ID = "orcarouter";
+
+export const ORCAROUTER_PROFILE = Object.freeze({
+	displayName: "OrcaRouter",
+	apiKeyEnv: "ORCAROUTER_API_KEY",
+	api: "openai-completions",
+	baseURL: "https://api.orcarouter.ai/v1",
+	models: Object.freeze([Object.freeze({ id: "orcarouter/auto", name: "OrcaRouter Auto" })])
+});
+
+function descriptorOf(settings) {
+	if (typeof settings?.describe !== "function") return null;
+	const descriptors = settings.describe({ redactSecrets: true });
+	if (!Array.isArray(descriptors)) return null;
+	return descriptors.find((entry) => entry?.ns === SETTINGS_NAMESPACE) ?? null;
+}
+function hasOrcaRouter(descriptor) {
+	const providers = descriptor?.value?.providers;
+	return providers !== null && typeof providers === "object" && !Array.isArray(providers)
+		&& Object.hasOwn(providers, PROVIDER_ID);
+}
+
+/** Secret-free availability state suitable for the browser integration card. */
+export function orcaRouterIntegrationState(settings) {
+	const descriptor = descriptorOf(settings);
+	const available = descriptor !== null && typeof settings?.mutate === "function" && settings.writable !== false;
+	return {
+		available,
+		installed: descriptor !== null && hasOrcaRouter(descriptor)
+	};
+}
+
+function detachedProfile() {
+	return {
+		displayName: ORCAROUTER_PROFILE.displayName,
+		apiKeyEnv: ORCAROUTER_PROFILE.apiKeyEnv,
+		api: ORCAROUTER_PROFILE.api,
+		baseURL: ORCAROUTER_PROFILE.baseURL,
+		models: ORCAROUTER_PROFILE.models.map((model) => ({ ...model }))
+	};
+}
+
+/**
+ * Add the preset with one revision-guarded path mutation. This preserves all
+ * unrelated providers and converges cleanly if another writer adds the same
+ * route between our read and write.
+ */
+export async function addOrcaRouterPreset(settings) {
+	const before = descriptorOf(settings);
+	const available = before !== null && typeof settings?.mutate === "function" && settings.writable !== false;
+	if (!available) return { available: false, installed: hasOrcaRouter(before), added: false };
+	if (hasOrcaRouter(before)) return { available: true, installed: true, added: false };
+
+	try {
+		await settings.mutate(SETTINGS_NAMESPACE, [{
+			op: "set",
+			path: ["providers", PROVIDER_ID],
+			value: detachedProfile()
+		}], before.revision);
+		return { available: true, installed: true, added: true };
+	} catch (error) {
+		if (error?.code === "SETTINGS_CONFLICT") {
+			const after = descriptorOf(settings);
+			if (hasOrcaRouter(after)) return { available: true, installed: true, added: false };
+		}
+		throw error;
+	}
+}

package/lib/provider-identity.js

@@ -20,6 +20,7 @@ const ADAPTER_IDENTITIES = Object.freeze({
 	"openrouter-balance": { providerFamily: "openrouter", pricingFamily: "openrouter" },
 	"moonshot-balance": { providerFamily: "moonshot", pricingFamily: "moonshot" },
 	"zai-balance": { providerFamily: "zai", pricingFamily: "zai" },
+	"orcarouter-balance": { providerFamily: "orcarouter", pricingFamily: "unknown" },
 	general: { providerFamily: "unknown", pricingFamily: "unknown" },
 	"new-api": { providerFamily: "new-api", pricingFamily: "unknown" },
 	sub2api: { providerFamily: "sub2api", pricingFamily: "unknown" },
@@ -48,6 +49,7 @@ const CANONICAL_ROUTES = Object.freeze({
 	minimaxi: { providerFamily: "minimax", accountAdapter: "minimax-token-plan", balanceScheme: null },
 	"minimax-cn": { providerFamily: "minimax", accountAdapter: "minimax-token-plan", balanceScheme: null },
 	"minimax-coding": { providerFamily: "minimax", accountAdapter: "minimax-token-plan", balanceScheme: null },
+	orcarouter: { providerFamily: "orcarouter", accountAdapter: "orcarouter-balance", pricingFamily: "unknown", balanceScheme: "orcarouter" },
 	passion: { providerFamily: "sub2api", accountAdapter: "sub2api", pricingFamily: "unknown", balanceScheme: null }
 });
 
@@ -66,6 +68,7 @@ function hostnameOf(baseURL) {
 
 function hostRule(hostname) {
 	if (hostname === "api.deepseek.com") return { providerFamily: "deepseek", accountAdapter: "deepseek-balance" };
+	if (hostname === "api.orcarouter.ai") return { providerFamily: "orcarouter", accountAdapter: "orcarouter-balance", pricingFamily: "unknown" };
 	if (hostname === "passionapi.com" || hostname.endsWith(".passionapi.com")) return { providerFamily: "sub2api", accountAdapter: "sub2api", pricingFamily: "unknown" };
 	if (hostname === "ollama.com" || hostname.endsWith(".ollama.com")) return { providerFamily: "ollama", accountAdapter: "ollama" };
 	return null;