@oh-my-pi-zen/omp-stats 16.3.6-zen.1

package/src/server.ts

@@ -0,0 +1,352 @@
+import type { Dirent } from "node:fs";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { isEnoent } from "@oh-my-pi-zen/pi-utils";
+import { $ } from "bun";
+import {
+	getBehaviorDashboardStats,
+	getCostDashboardStats,
+	getDashboardStats,
+	getModelDashboardStats,
+	getOverviewStats,
+	getRecentErrors,
+	getRecentRequests,
+	getRequestDetails,
+	getToolDashboardStats,
+	getTotalMessageCount,
+	syncAllSessions,
+} from "./aggregator";
+import { decodeEmbeddedClientArchive } from "./embedded-client";
+import embeddedClientArchiveTxt from "./embedded-client.generated.txt";
+import { getGainDashboardStats } from "./gain-aggregator";
+
+const EMBEDDED_CLIENT_ARCHIVE = decodeEmbeddedClientArchive(embeddedClientArchiveTxt);
+
+const CLIENT_DIR = path.join(import.meta.dir, "client");
+const STATIC_DIR = path.join(import.meta.dir, "..", "dist", "client");
+const IS_BUN_COMPILED =
+	Boolean(process.env.PI_COMPILED || Bun.env.PI_COMPILED) ||
+	import.meta.url.includes("$bunfs") ||
+	import.meta.url.includes("~BUN") ||
+	import.meta.url.includes("%7EBUN");
+// The prepacked npm bundle (coding-agent dist/cli.js) constant-folds
+// process.env.PI_BUNDLED at build time. Like compiled binaries, it ships no
+// dashboard sources or prebuilt dist/client next to the bundle, so the
+// embedded archive is the only viable asset source.
+const IS_PREBUILT = IS_BUN_COMPILED || Boolean(process.env.PI_BUNDLED || Bun.env.PI_BUNDLED);
+const USE_EMBEDDED_CLIENT = EMBEDDED_CLIENT_ARCHIVE !== null || IS_PREBUILT;
+
+const EMBEDDED_CLIENT_DIR_ROOT = path.join(os.tmpdir(), "omp-stats-client");
+let embeddedClientDirPromise: Promise<string> | null = null;
+
+function sanitizeArchivePath(archivePath: string): string | null {
+	const normalized = archivePath.replaceAll("\\", "/").replace(/^\.\//, "");
+	if (!normalized || normalized === ".") return null;
+	if (normalized.includes("..") || path.isAbsolute(normalized)) return null;
+	return normalized;
+}
+
+async function extractEmbeddedClientArchive(archiveBytes: Buffer, outputDir: string): Promise<void> {
+	const archive = new Bun.Archive(archiveBytes);
+	const files = await archive.files();
+	const extractRoot = path.resolve(outputDir);
+
+	for (const [archivePath, file] of files) {
+		const sanitizedPath = sanitizeArchivePath(archivePath);
+		if (!sanitizedPath) continue;
+		const destinationPath = path.resolve(extractRoot, sanitizedPath);
+		if (!destinationPath.startsWith(extractRoot + path.sep)) {
+			throw new Error(`Archive entry escapes extraction directory: ${archivePath}`);
+		}
+		await Bun.write(destinationPath, file);
+	}
+}
+
+async function getEmbeddedClientDir(): Promise<string> {
+	if (!USE_EMBEDDED_CLIENT) return STATIC_DIR;
+	if (embeddedClientDirPromise) return embeddedClientDirPromise;
+
+	if (!EMBEDDED_CLIENT_ARCHIVE) {
+		throw new Error(
+			"Embedded stats client bundle missing. Rebuild the omp binary or npm bundle with embedded stats assets.",
+		);
+	}
+
+	embeddedClientDirPromise = (async () => {
+		const bundleHash = Bun.hash(EMBEDDED_CLIENT_ARCHIVE).toString(16);
+		const outputDir = path.join(EMBEDDED_CLIENT_DIR_ROOT, bundleHash);
+		const markerPath = path.join(outputDir, "index.html");
+		try {
+			const marker = await fs.stat(markerPath);
+			if (marker.isFile()) return outputDir;
+		} catch {}
+
+		await fs.rm(outputDir, { recursive: true, force: true });
+		await fs.mkdir(outputDir, { recursive: true });
+		await extractEmbeddedClientArchive(EMBEDDED_CLIENT_ARCHIVE, outputDir);
+		return outputDir;
+	})();
+
+	return embeddedClientDirPromise;
+}
+
+async function getLatestMtime(dir: string): Promise<number> {
+	let entries: Dirent[];
+	try {
+		entries = await fs.readdir(dir, { withFileTypes: true });
+	} catch (err) {
+		// Tolerate missing source trees (e.g. installs without the dashboard
+		// sources); the caller falls back to prebuilt assets or a clear build
+		// failure instead of crashing on the scan.
+		if (isEnoent(err)) return 0;
+		throw err;
+	}
+
+	const promises = [];
+	for (const entry of entries) {
+		const fullPath = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			promises.push(getLatestMtime(fullPath));
+		} else if (entry.isFile()) {
+			promises.push(fs.stat(fullPath).then(stats => stats.mtimeMs));
+		}
+	}
+
+	let latest = 0;
+	await Promise.allSettled(promises).then(results => {
+		for (const result of results) {
+			if (result.status === "fulfilled") {
+				latest = Math.max(latest, result.value);
+			}
+		}
+	});
+	return latest;
+}
+
+const ensureClientBuild = async () => {
+	if (USE_EMBEDDED_CLIENT) return;
+	const indexPath = path.join(STATIC_DIR, "index.html");
+	const cssPath = path.join(STATIC_DIR, "styles.css");
+	const clientSourceMtime = await getLatestMtime(CLIENT_DIR);
+	const tailwindConfigPath = path.join(import.meta.dir, "..", "tailwind.config.js");
+	let tailwindConfigMtime = 0;
+	try {
+		const tailwindConfigStats = await fs.stat(tailwindConfigPath);
+		tailwindConfigMtime = tailwindConfigStats.mtimeMs;
+	} catch {}
+	const sourceMtime = Math.max(clientSourceMtime, tailwindConfigMtime);
+	let shouldBuild = true;
+	try {
+		const [indexStats, cssStats] = await Promise.all([fs.stat(indexPath), fs.stat(cssPath)]);
+		if (
+			indexStats.isFile() &&
+			cssStats.isFile() &&
+			indexStats.mtimeMs >= sourceMtime &&
+			cssStats.mtimeMs >= sourceMtime
+		) {
+			shouldBuild = false;
+		}
+	} catch {
+		shouldBuild = true;
+	}
+
+	if (!shouldBuild) return;
+
+	await fs.rm(STATIC_DIR, { recursive: true, force: true });
+
+	console.log("Building stats client...");
+	const packageRoot = path.join(import.meta.dir, "..");
+	const buildResult = await $`bun run build.ts`.cwd(packageRoot).quiet().nothrow();
+	if (buildResult.exitCode !== 0) {
+		const output = buildResult.text().trim();
+		const details = output ? `\n${output}` : "";
+		throw new Error(`Failed to build stats client (exit ${buildResult.exitCode})${details}`);
+	}
+
+	const indexHtml = `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>AI Usage Statistics</title>
+    <link rel="stylesheet" href="styles.css">
+</head>
+<body>
+    <div id="root"></div>
+    <script src="index.js" type="module"></script>
+</body>
+</html>`;
+
+	await Bun.write(path.join(STATIC_DIR, "index.html"), indexHtml);
+};
+
+/**
+ * Handle API requests.
+ */
+async function handleApi(req: Request): Promise<Response> {
+	const url = new URL(req.url);
+	const path = url.pathname;
+
+	// Stats reads are DB-only; explicit /api/sync does the expensive session scan.
+	const range = url.searchParams.get("range");
+
+	if (path === "/api/stats") {
+		const stats = await getDashboardStats(range);
+		return Response.json(stats);
+	}
+
+	if (path === "/api/stats/overview") {
+		const stats = await getOverviewStats(range);
+		return Response.json(stats);
+	}
+
+	if (path === "/api/stats/model-dashboard") {
+		const stats = await getModelDashboardStats(range);
+		return Response.json(stats);
+	}
+
+	if (path === "/api/stats/costs") {
+		const stats = await getCostDashboardStats(range);
+		return Response.json(stats);
+	}
+
+	if (path === "/api/stats/behavior") {
+		const stats = await getBehaviorDashboardStats(range);
+		return Response.json(stats);
+	}
+
+	if (path === "/api/stats/tools") {
+		const stats = await getToolDashboardStats(range);
+		return Response.json(stats);
+	}
+
+	if (path === "/api/stats/recent") {
+		const limit = url.searchParams.get("limit");
+		const stats = await getRecentRequests(limit ? parseInt(limit, 10) : undefined);
+		return Response.json(stats);
+	}
+
+	if (path === "/api/stats/errors") {
+		const limit = url.searchParams.get("limit");
+		const stats = await getRecentErrors(limit ? parseInt(limit, 10) : undefined);
+		return Response.json(stats);
+	}
+
+	if (path === "/api/stats/models") {
+		const stats = await getDashboardStats(range);
+		return Response.json(stats.byModel);
+	}
+
+	if (path === "/api/stats/folders") {
+		const stats = await getDashboardStats(range);
+		return Response.json(stats.byFolder);
+	}
+
+	if (path === "/api/stats/timeseries") {
+		const stats = await getDashboardStats(range);
+		return Response.json(stats.timeSeries);
+	}
+
+	if (path.startsWith("/api/request/")) {
+		const id = path.split("/").pop();
+		if (!id) return new Response("Bad Request", { status: 400 });
+		const details = await getRequestDetails(parseInt(id, 10));
+		if (!details) return new Response("Not Found", { status: 404 });
+		return Response.json(details);
+	}
+
+	if (path === "/api/sync") {
+		const result = await syncAllSessions();
+		const count = await getTotalMessageCount();
+		return Response.json({ ...result, totalMessages: count });
+	}
+
+	if (path === "/api/stats/gain") {
+		const project = url.searchParams.get("project");
+		const stats = await getGainDashboardStats(range, project);
+		return Response.json(stats);
+	}
+
+	return new Response("Not Found", { status: 404 });
+}
+
+/**
+ * Handle static file requests.
+ */
+async function handleStatic(requestPath: string): Promise<Response> {
+	const staticDir = await getEmbeddedClientDir();
+	const filePath = requestPath === "/" ? "/index.html" : requestPath;
+	const fullPath = path.join(staticDir, filePath);
+
+	const file = Bun.file(fullPath);
+	if (await file.exists()) {
+		return new Response(file);
+	}
+
+	// SPA fallback
+	const index = Bun.file(path.join(staticDir, "index.html"));
+	if (await index.exists()) {
+		return new Response(index);
+	}
+
+	return new Response("Not Found", { status: 404 });
+}
+
+/**
+ * Start the HTTP server.
+ */
+export async function startServer(port = 3847): Promise<{ port: number; stop: () => void }> {
+	await ensureClientBuild();
+
+	const server = Bun.serve({
+		port,
+		async fetch(req) {
+			const url = new URL(req.url);
+			const path = url.pathname;
+
+			// CORS headers for local development
+			const corsHeaders = {
+				"Access-Control-Allow-Origin": "*",
+				"Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+				"Access-Control-Allow-Headers": "Content-Type",
+			};
+
+			if (req.method === "OPTIONS") {
+				return new Response(null, { headers: corsHeaders });
+			}
+
+			try {
+				let response: Response;
+
+				if (path.startsWith("/api/")) {
+					response = await handleApi(req);
+				} else {
+					response = await handleStatic(path);
+				}
+
+				// Add CORS headers to all responses
+				const headers = new Headers(response.headers);
+				for (const [key, value] of Object.entries(corsHeaders)) {
+					headers.set(key, value);
+				}
+
+				return new Response(response.body, {
+					status: response.status,
+					headers,
+				});
+			} catch (error) {
+				console.error("Server error:", error);
+				return Response.json(
+					{ error: error instanceof Error ? error.message : "Unknown error" },
+					{ status: 500, headers: corsHeaders },
+				);
+			}
+		},
+	});
+
+	return {
+		port: server.port ?? port,
+		stop: () => server.stop(),
+	};
+}

package/src/shared-types.ts

@@ -0,0 +1,323 @@
+/**
+ * Shared type definitions consumed by both the server-side stats code and the
+ * standalone client bundle. Keep this file free of any imports from server-only
+ * packages (e.g. `@oh-my-pi-zen/pi-ai`, `bun:sqlite`) so the client can import it
+ * without dragging server dependencies into its bundle.
+ */
+
+/**
+ * Aggregated stats for a model or folder.
+ */
+export interface AggregatedStats {
+	/** Total number of requests */
+	totalRequests: number;
+	/** Number of successful requests */
+	successfulRequests: number;
+	/** Number of failed requests */
+	failedRequests: number;
+	/** Error rate (0-1) */
+	errorRate: number;
+	/** Total input tokens */
+	totalInputTokens: number;
+	/** Total output tokens */
+	totalOutputTokens: number;
+	/** Total cache read tokens */
+	totalCacheReadTokens: number;
+	/** Total cache write tokens */
+	totalCacheWriteTokens: number;
+	/** Cache hit rate (0-1) */
+	cacheRate: number;
+	/** Total cost */
+	totalCost: number;
+	/** Total premium requests */
+	totalPremiumRequests: number;
+	/** Average duration in ms */
+	avgDuration: number | null;
+	/** Average TTFT in ms */
+	avgTtft: number | null;
+	/** Average tokens per second (output tokens / duration) */
+	avgTokensPerSecond: number | null;
+	/** Time range */
+	firstTimestamp: number;
+	lastTimestamp: number;
+}
+
+/**
+ * Stats grouped by model.
+ */
+export interface ModelStats extends AggregatedStats {
+	model: string;
+	provider: string;
+}
+
+/**
+ * Stats grouped by folder.
+ */
+export interface FolderStats extends AggregatedStats {
+	folder: string;
+}
+
+/**
+ * Time series data point.
+ */
+export interface TimeSeriesPoint {
+	/** Bucket timestamp (start of hour/day) */
+	timestamp: number;
+	/** Request count */
+	requests: number;
+	/** Error count */
+	errors: number;
+	/** Total tokens */
+	tokens: number;
+	/** Total cost */
+	cost: number;
+}
+
+/**
+ * Model usage time series data point (daily buckets).
+ */
+export interface ModelTimeSeriesPoint {
+	/** Bucket timestamp (start of day) */
+	timestamp: number;
+	/** Model name */
+	model: string;
+	/** Provider name */
+	provider: string;
+	/** Request count */
+	requests: number;
+}
+
+/**
+ * Model performance time series data point (daily buckets).
+ */
+export interface ModelPerformancePoint {
+	/** Bucket timestamp (start of day) */
+	timestamp: number;
+	/** Model name */
+	model: string;
+	/** Provider name */
+	provider: string;
+	/** Request count */
+	requests: number;
+	/** Average TTFT in ms */
+	avgTtft: number | null;
+	/** Average tokens per second */
+	avgTokensPerSecond: number | null;
+}
+
+/**
+ * Cost time series data point (daily buckets).
+ */
+export interface CostTimeSeriesPoint {
+	/** Bucket timestamp (start of day) */
+	timestamp: number;
+	/** Model name */
+	model: string;
+	/** Provider name */
+	provider: string;
+	/** Total cost for this bucket */
+	cost: number;
+	/** Cost breakdown */
+	costInput: number;
+	costOutput: number;
+	costCacheRead: number;
+	costCacheWrite: number;
+	/** Request count */
+	requests: number;
+}
+
+/**
+ * Overall dashboard stats.
+ */
+export interface DashboardStats {
+	overall: AggregatedStats;
+	byModel: ModelStats[];
+	byFolder: FolderStats[];
+	byAgentType: AgentTypeStats[];
+	timeSeries: TimeSeriesPoint[];
+	modelSeries: ModelTimeSeriesPoint[];
+	modelPerformanceSeries: ModelPerformancePoint[];
+	costSeries: CostTimeSeriesPoint[];
+}
+
+/**
+ * Which agent produced a message, derived from its transcript file location
+ * inside the session directory: the top-level `<project>/<file>.jsonl` is the
+ * `main` agent, an `__advisor.jsonl` is the passive `advisor`, and any other
+ * nested transcript is a task `subagent`.
+ */
+export type AgentType = "main" | "subagent" | "advisor";
+
+/**
+ * Token usage aggregated by {@link AgentType} over the active range. Token
+ * columns are explicit so the dashboard's share denominator matches the
+ * counts it renders (input + output + cache read + cache write).
+ */
+export interface AgentTypeStats {
+	agentType: AgentType;
+	/** Total number of requests */
+	totalRequests: number;
+	/** Total input tokens */
+	totalInputTokens: number;
+	/** Total output tokens */
+	totalOutputTokens: number;
+	/** Total cache read tokens */
+	totalCacheReadTokens: number;
+	/** Total cache write tokens */
+	totalCacheWriteTokens: number;
+	/** Total cost */
+	totalCost: number;
+}
+
+/**
+ * Behavior time-series point (daily bucket, per responding model).
+ */
+export interface BehaviorTimeSeriesPoint {
+	/** Bucket timestamp (start of day) */
+	timestamp: number;
+	/** Responding model ("unknown" if user msg never got a reply) */
+	model: string;
+	/** Responding provider */
+	provider: string;
+	/** Number of user messages in bucket */
+	messages: number;
+	/** Total yelling sentences in bucket */
+	yelling: number;
+	/** Total profanity hits in bucket */
+	profanity: number;
+	/** Total anguish signal in bucket */
+	anguish: number;
+	/** Total corrective-negation hits in bucket */
+	negation: number;
+	/** Total user-repeating-themselves hits in bucket */
+	repetition: number;
+	/** Total second-person blame hits in bucket */
+	blame: number;
+	/** Total characters in bucket */
+	chars: number;
+}
+
+export interface BehaviorOverallStats {
+	totalMessages: number;
+	totalYelling: number;
+	totalProfanity: number;
+	totalAnguish: number;
+	totalNegation: number;
+	totalRepetition: number;
+	totalBlame: number;
+	totalChars: number;
+	firstTimestamp: number;
+	lastTimestamp: number;
+}
+
+/**
+ * Per-model behavioral aggregate over the active range.
+ */
+export interface BehaviorModelStats {
+	model: string;
+	provider: string;
+	totalMessages: number;
+	totalYelling: number;
+	totalProfanity: number;
+	totalAnguish: number;
+	totalNegation: number;
+	totalRepetition: number;
+	totalBlame: number;
+	totalChars: number;
+	lastTimestamp: number;
+}
+
+export interface BehaviorDashboardStats {
+	overall: BehaviorOverallStats;
+	byModel: BehaviorModelStats[];
+	behaviorSeries: BehaviorTimeSeriesPoint[];
+}
+
+/** Token savings from a single source type. */
+export interface GainSourceTotals {
+	savedTokens: number;
+	savedBytes: number;
+	hits: number;
+	/** originalBytes - savedBytes, when original is known */
+	outputBytes: number;
+	/** Total original bytes before compression, when known */
+	originalBytes: number;
+	/** savedBytes / originalBytes when both are known, else null */
+	reductionPercent: number | null;
+}
+
+/** Per-source breakdown. */
+export type GainSource = "snapcompact";
+
+/** Time-series point for gain (daily bucket). */
+export interface GainTimeSeriesPoint {
+	date: string;
+	snapcompact: number;
+	total: number;
+}
+
+/** Complete gain dashboard payload. */
+export interface GainDashboardStats {
+	/** Aggregate across all sources for the active range. */
+	overall: GainSourceTotals;
+	/** Per-source breakdown. */
+	bySource: Record<GainSource, GainSourceTotals>;
+	/** Daily time series. */
+	timeSeries: GainTimeSeriesPoint[];
+	/** Active project filter (cwd prefix), or null for all projects. */
+	project: string | null;
+	/** All distinct projects seen in the data, for the selector. */
+	projects: string[];
+}
+
+/**
+ * Aggregated usage for a single tool over the active range.
+ *
+ * Token/cost fields are the *real* provider usage of the assistant turns that
+ * invoked the tool, split evenly across that turn's tool calls so the numbers
+ * stay additive (a turn with 3 calls contributes a third of its usage to each
+ * tool). Payload fields (`argsChars`/`resultChars`) are raw character counts
+ * of the serialized arguments and the text fed back into context — a size
+ * proxy, not provider-counted tokens.
+ */
+export interface ToolUsageStats {
+	/** Tool name as recorded on the tool call. */
+	tool: string;
+	/** Number of tool calls. */
+	calls: number;
+	/** Calls whose result came back with `isError`. */
+	errors: number;
+	/** Serialized tool-call argument characters. */
+	argsChars: number;
+	/** Text characters of tool results fed back into context. */
+	resultChars: number;
+	/** Total provider tokens of invoking turns, attributed per call share. */
+	totalTokensShare: number;
+	/** Output tokens of invoking turns, attributed per call share. */
+	outputTokensShare: number;
+	/** Cost (USD) of invoking turns, attributed per call share. */
+	costShare: number;
+	/** Unix ms of the most recent call in range. */
+	lastUsed: number;
+}
+
+/** Per-(tool, model) breakdown with the same attribution as {@link ToolUsageStats}. */
+export interface ToolModelStats extends ToolUsageStats {
+	model: string;
+	provider: string;
+}
+
+/** Tool-call time-series point (one bucket per tool). */
+export interface ToolTimeSeriesPoint {
+	timestamp: number;
+	tool: string;
+	calls: number;
+	errors: number;
+}
+
+/** Complete tools dashboard payload. */
+export interface ToolDashboardStats {
+	byTool: ToolUsageStats[];
+	byToolModel: ToolModelStats[];
+	series: ToolTimeSeriesPoint[];
+}

package/src/sync-worker.ts

@@ -0,0 +1,40 @@
+/**
+ * Stateless parse worker for `syncAllSessions`. The main thread owns the
+ * SQLite handle; workers receive `{ sessionFile, fromOffset }`, run
+ * `parseSessionFile` (which is pure I/O + CPU, no DB), and post the
+ * structured-clone-safe result back. One in-flight request per worker so
+ * the main thread can fan jobs out 1:1 with the pool size.
+ *
+ * A `{ kind: "ping" }` request is also accepted and replies with
+ * `{ ok: true, kind: "pong" }` — used by `smokeTestSyncWorker` to prove the
+ * worker actually spawns and runs in compiled binaries (regression coverage
+ * for issue #1011 / PR #1027, where the worker silently failed to load).
+ */
+
+import { type ParseSessionResult, parseSessionFile } from "./parser";
+
+export type SyncWorkerRequest = { kind?: "parse"; sessionFile: string; fromOffset: number } | { kind: "ping" };
+
+export type SyncWorkerResponse =
+	| { ok: true; kind?: "parse"; result: ParseSessionResult }
+	| { ok: true; kind: "pong" }
+	| { ok: false; error: string };
+
+declare const self: Worker & {
+	onmessage: ((event: MessageEvent<SyncWorkerRequest>) => void) | null;
+};
+
+self.onmessage = async event => {
+	const request = event.data;
+	try {
+		if (request.kind === "ping") {
+			self.postMessage({ ok: true, kind: "pong" } satisfies SyncWorkerResponse);
+			return;
+		}
+		const result = await parseSessionFile(request.sessionFile, request.fromOffset);
+		self.postMessage({ ok: true, result } satisfies SyncWorkerResponse);
+	} catch (err) {
+		const error = err instanceof Error ? (err.stack ?? err.message) : String(err);
+		self.postMessage({ ok: false, error } satisfies SyncWorkerResponse);
+	}
+};