@ychris12138/dsh-usage-stats 0.2.6

package/lib/usage.js

@@ -0,0 +1,276 @@
+/**
+ * dsh-usage-stats — pure per-day, per-model token-usage aggregation over
+ * session event logs. Kept free of cordis imports so it can be unit-tested
+ * and validated against real logs outside the running harness.
+ *
+ * Aggregation semantics mirror `dsh-token-meter`'s `tokenUsage` projection:
+ * a usage sample rides an `assistant/chunk` (`data.chunk.type === "usage"`)
+ * or an `assistant/message` (`data.usage`); a repeated sample for the same
+ * (turn, step) REPLACES the earlier value instead of double counting it, and
+ * the replacement is re-attributed to the day of the later event.
+ *
+ * Each sample is additionally attributed to the model that produced it:
+ * `assistant/message` carries `data.message.source.model`; usage chunks fall
+ * back to the last `request/header` `data.header.config.model`; samples with
+ * no model information land in the `unknown` bucket.
+ *
+ * @module dsh-usage-stats/usage
+ */
+
+/** Local-calendar `YYYY-MM-DD` key for a millisecond epoch. */
+export function dayKey(timeMs) {
+	const date = new Date(timeMs);
+	const month = String(date.getMonth() + 1).padStart(2, "0");
+	const day = String(date.getDate()).padStart(2, "0");
+	return `${date.getFullYear()}-${month}-${day}`;
+}
+
+/** Empty token bucket. */
+export function zeroBuckets() {
+	return {
+		inputTokens: 0,
+		outputTokens: 0,
+		cacheReadTokens: 0,
+		cacheWriteTokens: 0
+	};
+}
+
+/** Provider usage → buckets (missing cache fields are absent in some reports). */
+export function bucketsOf(usage) {
+	return {
+		inputTokens: usage.inputTokens ?? 0,
+		outputTokens: usage.outputTokens ?? 0,
+		cacheReadTokens: usage.cacheReadTokens ?? 0,
+		cacheWriteTokens: usage.cacheWriteTokens ?? 0
+	};
+}
+
+/** Total tokens across all buckets. */
+export function totalTokens(buckets) {
+	return buckets.inputTokens + buckets.outputTokens + buckets.cacheReadTokens + buckets.cacheWriteTokens;
+}
+
+/**
+ * Prompt-side cache hit rate in percent (0–100, one decimal), or null when
+ * no prompt tokens were reported at all. Hits over the whole prompt side:
+ * cacheRead / (input + cacheRead + cacheWrite).
+ */
+export function cacheHitRate(buckets) {
+	const input = buckets.inputTokens ?? 0;
+	const cacheRead = buckets.cacheReadTokens ?? 0;
+	const cacheWrite = buckets.cacheWriteTokens ?? 0;
+	const promptTokens = input + cacheRead + cacheWrite;
+	if (promptTokens <= 0) return null;
+	return Math.round((cacheRead / promptTokens) * 1000) / 10;
+}
+
+function addInto(target, source) {
+	target.inputTokens += source.inputTokens;
+	target.outputTokens += source.outputTokens;
+	target.cacheReadTokens += source.cacheReadTokens;
+	target.cacheWriteTokens += source.cacheWriteTokens;
+	return target;
+}
+
+function subtractFrom(target, source) {
+	target.inputTokens -= source.inputTokens;
+	target.outputTokens -= source.outputTokens;
+	target.cacheReadTokens -= source.cacheReadTokens;
+	target.cacheWriteTokens -= source.cacheWriteTokens;
+	return target;
+}
+
+/** Extract the usage sample an event carries, if any. */
+function sampleOf(event) {
+	if (event.type === "assistant/chunk" && event.data?.chunk?.type === "usage") {
+		return {
+			key: `${event.data.turn}:${event.data.step}`,
+			usage: event.data.chunk.usage
+		};
+	}
+	if (event.type === "assistant/message" && event.data?.usage !== void 0) {
+		return {
+			key: `${event.data.turn}:${event.data.step}`,
+			usage: event.data.usage
+		};
+	}
+	return void 0;
+}
+
+/**
+ * The `provider/model` attribution key of a usage sample: the exact provider
+ * route (dsh adapter id or pi-ai route) plus the model id, so the SAME model
+ * served by different providers stays distinct. `assistant/message` names
+ * its provider via `data.message.source`; usage chunks fall back to the last
+ * `request/header` `data.header.config`; samples with no model information
+ * land in the `unknown/unknown` bucket.
+ */
+function modelOf(event) {
+	const source = event.data?.message?.source;
+	if (source !== void 0 && typeof source.model === "string") {
+		return `${typeof source.provider === "string" && source.provider.length > 0 ? source.provider : "unknown"}/${source.model}`;
+	}
+	const config = event.data?.header?.config;
+	if (config !== void 0 && typeof config.model === "string") {
+		return `${typeof config.provider === "string" && config.provider.length > 0 ? config.provider : "unknown"}/${config.model}`;
+	}
+	return void 0;
+}
+
+/** Day entry: totals plus a per-model bucket map. */
+function entryOf(byDay, day) {
+	let entry = byDay.get(day);
+	if (entry === void 0) {
+		entry = {
+			totals: zeroBuckets(),
+			models: new Map()
+		};
+		byDay.set(day, entry);
+	}
+	return entry;
+}
+
+/**
+ * One session's incremental fold state. `days` holds the already-folded
+ * per-day entries; `lastSample`/`currentModel` let a later event slice keep
+ * the replace-last-sample semantics and model attribution across fold
+ * boundaries without replaying the whole log.
+ */
+export function createUsageState() {
+	return {
+		days: new Map(),
+		lastSample: null,
+		currentModel: null,
+		consumed: 0
+	};
+}
+
+/**
+ * Fold a slice of NEW events onto an existing session state (mutating).
+ * Replacements for the same (turn, step) subtract the previous sample's
+ * buckets from the day/model bucket they were attributed to, so a slice
+ * starting mid-step (e.g. a usage chunk at the tail of the previous fold)
+ * stays exact.
+ * @param state - session fold state (mutated in place).
+ * @param events - the new events, in seq order, starting after the last fold.
+ */
+export function applyUsageDelta(state, events) {
+	let last = state.lastSample;
+	let currentModel = state.currentModel;
+	for (const event of events) {
+		if (event.type === "request/header") {
+			const model = modelOf(event);
+			if (model !== void 0) currentModel = model;
+		}
+		const sample = sampleOf(event);
+		if (sample === void 0) continue;
+		const buckets = bucketsOf(sample.usage);
+		const model = modelOf(event) ?? currentModel ?? "unknown/unknown";
+		const day = dayKey(event.time);
+		const entry = entryOf(state.days, day);
+		if (last !== null && last.key === sample.key) {
+			// Same turn/step re-reported: replace instead of double counting.
+			const previous = state.days.get(last.day);
+			if (previous !== void 0) {
+				subtractFrom(previous.totals, last.buckets);
+				const previousModel = previous.models.get(last.model);
+				if (previousModel !== void 0) subtractFrom(previousModel, last.buckets);
+			}
+		}
+		addInto(entry.totals, buckets);
+		let modelBucket = entry.models.get(model);
+		if (modelBucket === void 0) {
+			modelBucket = zeroBuckets();
+			entry.models.set(model, modelBucket);
+		}
+		addInto(modelBucket, buckets);
+		last = { key: sample.key, day, model, buckets };
+	}
+	state.lastSample = last;
+	state.currentModel = currentModel;
+}
+
+/**
+ * Fold one session's events into per-day, per-model token buckets.
+ * @param events - session event log in seq order.
+ * @returns Map<`YYYY-MM-DD`, { totals, models: Map<model, buckets> }> with
+ *   only days that saw usage.
+ */
+export function foldUsage(events) {
+	const state = createUsageState();
+	applyUsageDelta(state, events);
+	return state.days;
+}
+
+/**
+ * Merge one session's folded days into a global per-day map.
+ * @param byDay - global map to mutate.
+ * @param sessionDays - session day map (from foldUsage or a state).
+ */
+export function mergeInto(byDay, sessionDays) {
+	for (const [day, entry] of sessionDays) {
+		const target = entryOf(byDay, day);
+		addInto(target.totals, entry.totals);
+		for (const [model, buckets] of entry.models) {
+			let modelBucket = target.models.get(model);
+			if (modelBucket === void 0) {
+				modelBucket = zeroBuckets();
+				target.models.set(model, modelBucket);
+			}
+			addInto(modelBucket, buckets);
+		}
+	}
+}
+
+/**
+ * Merge one session fold into a global per-day map (convenience wrapper).
+ * @param byDay - global map to mutate.
+ * @param events - session events.
+ */
+export function consumeEvents(byDay, events) {
+	mergeInto(byDay, foldUsage(events));
+}
+
+/**
+ * Render a global per-day map into the wire shape for the usage endpoint.
+ * @param byDay - day → entry map.
+ * @param updatedAt - computation timestamp.
+ * @returns `{ days, total, updatedAt }` with `days` sorted ascending; each
+ *   day carries `models` (descending by tokens) and a `cacheHitRate` percent.
+ */
+export function renderUsage(byDay, updatedAt) {
+	const days = [...byDay.entries()]
+		.map(([date, entry]) => {
+			const models = [...entry.models.entries()]
+				.map(([model, buckets]) => ({
+					model,
+					...buckets,
+					tokens: totalTokens(buckets),
+					cacheHitRate: cacheHitRate(buckets)
+				}))
+				// All-zero buckets come from warmup requests that report
+				// {input:0, output:0}; rendering them produces empty "0 tokens"
+				// model rows (#23).
+				.filter((entry) => entry.tokens > 0)
+				.sort((a, b) => b.tokens - a.tokens);
+			return {
+				date,
+				...entry.totals,
+				tokens: totalTokens(entry.totals),
+				cacheHitRate: cacheHitRate(entry.totals),
+				models
+			};
+		})
+		.sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0));
+	const total = zeroBuckets();
+	for (const [, entry] of byDay) addInto(total, entry.totals);
+	return {
+		days,
+		total: {
+			...total,
+			tokens: totalTokens(total),
+			cacheHitRate: cacheHitRate(total)
+		},
+		updatedAt
+	};
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@ychris12138/dsh-usage-stats",
+  "description": "Token usage heatmap, provider balances, and subscription quotas for the dsh web GUI",
+  "version": "0.2.6",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ychris12138/dsh-usage-stats.git"
+  },
+  "homepage": "https://github.com/Ychris12138/dsh-usage-stats#readme",
+  "bugs": "https://github.com/Ychris12138/dsh-usage-stats/issues",
+  "keywords": [
+    "deepseek",
+    "deepseek-harness",
+    "dsh",
+    "token-usage"
+  ],
+  "bin": {
+    "dsh-usage-stats-install": "scripts/install.mjs"
+  },
+  "files": [
+    "lib/",
+    "cordis.patch.yml",
+    "docs/images/usage-panel.svg",
+    "scripts/install.mjs",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./usage": "./lib/usage.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-primitives"
+      ]
+    }
+  },
+  "scripts": {
+    "check": "node --check lib/index.js && node --check lib/usage.js && node --check lib/balance.js && node --check lib/subscriptions.js && node --check lib/accounts.js && node --check lib/client.js && node --check scripts/install.mjs && node --check scripts/smoke-client.mjs && node --check scripts/test-overlay-layering.mjs && node --check scripts/test-bundle.mjs && node --check scripts/test-install.mjs && node --check scripts/test-server.mjs && node --check scripts/test-balance.mjs && node --check scripts/test-subscriptions.mjs && node --check scripts/test-accounts.mjs && node --check scripts/validate-fold.mjs && node --check scripts/verify-raw.mjs && node --check scripts/check-balance.mjs",
+    "test": "npm run test:bundle && npm run test:client && npm run test:overlay && npm run test:server && npm run test:balance && npm run test:subscriptions && npm run test:accounts && npm run test:install",
+    "test:bundle": "node scripts/test-bundle.mjs",
+    "test:client": "node scripts/smoke-client.mjs",
+    "test:overlay": "node scripts/test-overlay-layering.mjs",
+    "test:install": "node scripts/test-install.mjs",
+    "test:server": "node scripts/test-server.mjs",
+    "test:balance": "node scripts/test-balance.mjs",
+    "test:subscriptions": "node scripts/test-subscriptions.mjs",
+    "test:accounts": "node scripts/test-accounts.mjs",
+    "validate:live": "node scripts/validate-fold.mjs && node scripts/verify-raw.mjs",
+    "prepublishOnly": "npm run check && npm test"
+  },
+  "devDependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/install.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+import { cp, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const knownFlags = new Set(["--check", "--dry-run", "--no-enable", "--help"]);
+const args = new Set(process.argv.slice(2));
+for (const arg of args) {
+	if (!knownFlags.has(arg)) {
+		console.error(`Unknown option: ${arg}`);
+		process.exit(2);
+	}
+}
+
+if (args.has("--help")) {
+	console.log(`dsh-usage-stats installer
+
+Usage:
+  npx --yes github:Ychris12138/dsh-usage-stats [options]
+
+Options:
+  --check      Verify the installed package and Cordis patch without changing them
+  --dry-run    Print the resolved paths and planned changes
+  --no-enable  Install files without editing cordis.patch.yml
+  --help       Show this help
+
+Set DSH_HOME to override the default ~/.dsh location.`);
+	process.exit(0);
+}
+
+const sourceRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const sourcePackage = JSON.parse(await readFile(join(sourceRoot, "package.json"), "utf8"));
+const dshHome = process.env.DSH_HOME ?? join(homedir(), ".dsh");
+const target = join(dshHome, "profiles", "node_modules", "dsh-usage-stats");
+const patchPath = join(dshHome, "profiles", "web", "cordis.patch.yml");
+const pluginLine = /^\s+name:\s*dsh-usage-stats\s*$/gm;
+const patchBlock = `# dsh-usage-stats: token usage heatmap + DeepSeek balance
+- insert:
+    - id: usage-stats
+      name: dsh-usage-stats
+`;
+const emptySequenceRoot = /^\[\](?:[ \t]+#.*)?$/;
+
+function meaningfulPatchLines(text) {
+	return String(text).split(/\r?\n/).map((line, index) => ({
+		index,
+		indent: line.match(/^[ \t]*/)?.[0].length ?? 0,
+		content: line.trim()
+	})).filter(({ content }) => content !== "" && !content.startsWith("#") && content !== "---" && content !== "...");
+}
+
+/** Remove a YAML document whose only value is the empty root sequence `[]`. */
+function withoutEmptySequenceRoot(text) {
+	const meaningful = meaningfulPatchLines(text);
+	if (meaningful.length === 0) return text;
+	const rootIndent = Math.min(...meaningful.map(({ indent }) => indent));
+	const emptyRoot = meaningful.find(({ indent, content }) => indent === rootIndent && emptySequenceRoot.test(content));
+	if (emptyRoot === void 0) return text;
+	const lines = String(text).split(/\r?\n/);
+	const inlineComment = lines[emptyRoot.index].match(/^([ \t]*)\[\][ \t]+(#.*)$/);
+	if (inlineComment === null) lines.splice(emptyRoot.index, 1);
+	else lines[emptyRoot.index] = `${inlineComment[1]}${inlineComment[2]}`;
+	return lines.filter((line) => line.trim() !== "...").join("\n").trimEnd();
+}
+
+/** Detect the exact invalid shape produced by older installers: `[]` plus list entries. */
+function assertNoEmptyRootConflict(text) {
+	const meaningful = meaningfulPatchLines(text);
+	if (meaningful.length < 2) return;
+	const rootIndent = Math.min(...meaningful.map(({ indent }) => indent));
+	const roots = meaningful.filter(({ indent }) => indent === rootIndent);
+	if (roots.some(({ content }) => emptySequenceRoot.test(content)) && roots.length > 1) {
+		throw new Error(`invalid YAML in ${patchPath}: empty root sequence [] cannot be combined with patch entries; rerun the installer to repair it`);
+	}
+}
+
+/** Preserve existing YAML/comments while adding exactly one plugin patch entry. */
+function enablePluginInPatch(text) {
+	const base = withoutEmptySequenceRoot(text);
+	if ([...base.matchAll(pluginLine)].length > 0) return base;
+	return base.trim() === "" ? patchBlock : `${base.trimEnd()}\n\n${patchBlock}`;
+}
+
+async function readOptional(path) {
+	try {
+		return await readFile(path, "utf8");
+	} catch (error) {
+		if (error?.code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+async function verify(expectEnabled) {
+	const installedRaw = await readOptional(join(target, "package.json"));
+	if (installedRaw === null) throw new Error(`package is not installed at ${target}`);
+	const installed = JSON.parse(installedRaw);
+	if (installed.name !== sourcePackage.name || installed.version !== sourcePackage.version) {
+		throw new Error(`installed package is ${installed.name ?? "unknown"}@${installed.version ?? "unknown"}; expected ${sourcePackage.name}@${sourcePackage.version}`);
+	}
+	if (expectEnabled) {
+		const patch = await readOptional(patchPath);
+		const count = patch === null ? 0 : [...patch.matchAll(pluginLine)].length;
+		if (count !== 1) throw new Error(`expected exactly one dsh-usage-stats entry in ${patchPath}; found ${count}`);
+		assertNoEmptyRootConflict(patch);
+	}
+	console.log(`Verified ${sourcePackage.name}@${sourcePackage.version}`);
+	console.log(`  package: ${target}`);
+	if (expectEnabled) console.log(`  patch:   ${patchPath}`);
+}
+
+const enable = !args.has("--no-enable");
+if (args.has("--dry-run")) {
+	console.log(`Would install ${sourcePackage.name}@${sourcePackage.version}`);
+	console.log(`  package: ${target}`);
+	console.log(`  patch:   ${enable ? patchPath : "unchanged (--no-enable)"}`);
+	process.exit(0);
+}
+
+if (args.has("--check")) {
+	await verify(enable);
+	process.exit(0);
+}
+
+await mkdir(target, { recursive: true });
+for (const entry of ["lib", "cordis.patch.yml", "package.json", "README.md", "LICENSE", "SECURITY.md"]) {
+	await cp(join(sourceRoot, entry), join(target, entry), { recursive: true, force: true });
+}
+await mkdir(join(target, "scripts"), { recursive: true });
+await cp(fileURLToPath(import.meta.url), join(target, "scripts", "install.mjs"), { force: true });
+
+if (enable) {
+	await mkdir(dirname(patchPath), { recursive: true });
+	const current = await readOptional(patchPath) ?? "";
+	const enabledPatch = enablePluginInPatch(current);
+	if (enabledPatch !== current) await writeFile(patchPath, enabledPatch, "utf8");
+}
+
+await verify(enable);
+console.log("Installation complete. Restart dsh web, then hard-refresh the browser.");
+console.log("Balance is optional: configure DEEPSEEK_API_KEY in <DSH_HOME>/.credentials.yaml.");