@katyella/legio 0.1.0

package/src/metrics/store.ts

@@ -0,0 +1,511 @@
+/**
+ * SQLite-backed metrics storage for agent session data.
+ *
+ * Uses better-sqlite3 for zero-dependency, synchronous database access.
+ * All operations are sync — no async/await needed.
+ */
+
+import Database from "better-sqlite3";
+import type { SessionMetrics, TokenSnapshot } from "../types.ts";
+
+export interface ModelGroup {
+	model: string;
+	sessions: number;
+	inputTokens: number;
+	outputTokens: number;
+	cacheReadTokens: number;
+	cacheCreationTokens: number;
+	estimatedCostUsd: number;
+}
+
+export interface DateGroup {
+	date: string;
+	sessions: number;
+	inputTokens: number;
+	outputTokens: number;
+	cacheReadTokens: number;
+	cacheCreationTokens: number;
+	estimatedCostUsd: number;
+}
+
+export interface MetricsStore {
+	recordSession(metrics: SessionMetrics): void;
+	getRecentSessions(limit?: number): SessionMetrics[];
+	/** Get sessions filtered by optional time range. */
+	getSessionsFiltered(opts: { since?: string; until?: string; limit?: number }): SessionMetrics[];
+	getSessionsByAgent(agentName: string): SessionMetrics[];
+	/** Get sessions belonging to a specific coordinator run. */
+	getSessionsByRun(runId: string): SessionMetrics[];
+	/** Get sessions grouped by model_used with aggregated token totals and cost. */
+	getSessionsByModel(opts?: { since?: string; until?: string }): ModelGroup[];
+	/** Get sessions grouped by date (YYYY-MM-DD) with aggregated token totals and cost. */
+	getSessionsByDate(opts?: { since?: string; until?: string }): DateGroup[];
+	getAverageDuration(capability?: string): number;
+	/** Delete metrics matching the given criteria. Returns the number of rows deleted. */
+	purge(options: { all?: boolean; agent?: string }): number;
+	/** Record a token usage snapshot for a running agent. */
+	recordSnapshot(snapshot: TokenSnapshot): void;
+	/** Get the most recent snapshot per active agent (one row per agent). */
+	getLatestSnapshots(): TokenSnapshot[];
+	/** Get the timestamp of the most recent snapshot for an agent, or null. */
+	getLatestSnapshotTime(agentName: string): string | null;
+	/** Delete snapshots matching criteria. Returns number of rows deleted. */
+	purgeSnapshots(options: { all?: boolean; agent?: string; olderThanMs?: number }): number;
+	close(): void;
+}
+
+/** Row shape as stored in SQLite (snake_case columns). */
+interface SessionRow {
+	agent_name: string;
+	bead_id: string;
+	capability: string;
+	started_at: string;
+	completed_at: string | null;
+	duration_ms: number;
+	exit_code: number | null;
+	merge_result: string | null;
+	parent_agent: string | null;
+	run_id: string | null;
+	input_tokens: number;
+	output_tokens: number;
+	cache_read_tokens: number;
+	cache_creation_tokens: number;
+	estimated_cost_usd: number | null;
+	model_used: string | null;
+}
+
+/** Snapshot row shape as stored in SQLite (snake_case columns). */
+interface SnapshotRow {
+	id: number;
+	agent_name: string;
+	input_tokens: number;
+	output_tokens: number;
+	cache_read_tokens: number;
+	cache_creation_tokens: number;
+	estimated_cost_usd: number | null;
+	model_used: string | null;
+	created_at: string;
+}
+
+/** Aggregated row shape from by-model GROUP BY query. */
+interface ModelGroupRow {
+	model: string;
+	sessions: number;
+	input_tokens: number;
+	output_tokens: number;
+	cache_read_tokens: number;
+	cache_creation_tokens: number;
+	estimated_cost_usd: number;
+}
+
+/** Aggregated row shape from by-date GROUP BY query. */
+interface DateGroupRow {
+	date: string;
+	sessions: number;
+	input_tokens: number;
+	output_tokens: number;
+	cache_read_tokens: number;
+	cache_creation_tokens: number;
+	estimated_cost_usd: number;
+}
+
+const CREATE_TABLE = `
+CREATE TABLE IF NOT EXISTS sessions (
+  agent_name TEXT NOT NULL,
+  bead_id TEXT NOT NULL,
+  capability TEXT NOT NULL,
+  started_at TEXT NOT NULL,
+  completed_at TEXT,
+  duration_ms INTEGER NOT NULL DEFAULT 0,
+  exit_code INTEGER,
+  merge_result TEXT,
+  parent_agent TEXT,
+  run_id TEXT,
+  input_tokens INTEGER NOT NULL DEFAULT 0,
+  output_tokens INTEGER NOT NULL DEFAULT 0,
+  cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+  cache_creation_tokens INTEGER NOT NULL DEFAULT 0,
+  estimated_cost_usd REAL,
+  model_used TEXT,
+  PRIMARY KEY (agent_name, bead_id)
+)`;
+
+const CREATE_SNAPSHOTS_TABLE = `
+CREATE TABLE IF NOT EXISTS token_snapshots (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  agent_name TEXT NOT NULL,
+  input_tokens INTEGER NOT NULL DEFAULT 0,
+  output_tokens INTEGER NOT NULL DEFAULT 0,
+  cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+  cache_creation_tokens INTEGER NOT NULL DEFAULT 0,
+  estimated_cost_usd REAL,
+  model_used TEXT,
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f','now'))
+)`;
+
+const CREATE_SNAPSHOTS_INDEX = `
+CREATE INDEX IF NOT EXISTS idx_snapshots_agent_time
+  ON token_snapshots(agent_name, created_at)
+`;
+
+/** Columns added via migration (safe to call multiple times — only adds missing columns). */
+const TOKEN_COLUMNS = [
+	{ name: "input_tokens", ddl: "INTEGER NOT NULL DEFAULT 0" },
+	{ name: "output_tokens", ddl: "INTEGER NOT NULL DEFAULT 0" },
+	{ name: "cache_read_tokens", ddl: "INTEGER NOT NULL DEFAULT 0" },
+	{ name: "cache_creation_tokens", ddl: "INTEGER NOT NULL DEFAULT 0" },
+	{ name: "estimated_cost_usd", ddl: "REAL" },
+	{ name: "model_used", ddl: "TEXT" },
+	{ name: "run_id", ddl: "TEXT" },
+] as const;
+
+/**
+ * Migrate an existing sessions table to include token columns.
+ * Safe to call multiple times — only adds columns that are missing.
+ */
+function migrateTokenColumns(db: Database.Database): void {
+	const rows = db.prepare("PRAGMA table_info(sessions)").all() as Array<{ name: string }>;
+	const existingColumns = new Set(rows.map((r) => r.name));
+
+	for (const col of TOKEN_COLUMNS) {
+		if (!existingColumns.has(col.name)) {
+			db.exec(`ALTER TABLE sessions ADD COLUMN ${col.name} ${col.ddl}`);
+		}
+	}
+}
+
+/** Convert a database row (snake_case) to a SessionMetrics object (camelCase). */
+function rowToMetrics(row: SessionRow): SessionMetrics {
+	return {
+		agentName: row.agent_name,
+		beadId: row.bead_id,
+		capability: row.capability,
+		startedAt: row.started_at,
+		completedAt: row.completed_at,
+		durationMs: row.duration_ms,
+		exitCode: row.exit_code,
+		mergeResult: row.merge_result as SessionMetrics["mergeResult"],
+		parentAgent: row.parent_agent,
+		runId: row.run_id,
+		inputTokens: row.input_tokens,
+		outputTokens: row.output_tokens,
+		cacheReadTokens: row.cache_read_tokens,
+		cacheCreationTokens: row.cache_creation_tokens,
+		estimatedCostUsd: row.estimated_cost_usd,
+		modelUsed: row.model_used,
+	};
+}
+
+/** Convert a database snapshot row (snake_case) to a TokenSnapshot object (camelCase). */
+function rowToSnapshot(row: SnapshotRow): TokenSnapshot {
+	return {
+		agentName: row.agent_name,
+		inputTokens: row.input_tokens,
+		outputTokens: row.output_tokens,
+		cacheReadTokens: row.cache_read_tokens,
+		cacheCreationTokens: row.cache_creation_tokens,
+		estimatedCostUsd: row.estimated_cost_usd,
+		modelUsed: row.model_used,
+		createdAt: row.created_at,
+	};
+}
+
+/**
+ * Create a new MetricsStore backed by a SQLite database at the given path.
+ *
+ * Initializes the database with WAL mode and a 5-second busy timeout.
+ * Creates the sessions table if it does not already exist.
+ * Migrates existing tables to add token columns if missing.
+ */
+export function createMetricsStore(dbPath: string): MetricsStore {
+	const db = new Database(dbPath);
+
+	// Configure for concurrent access
+	db.exec("PRAGMA journal_mode = WAL");
+	db.exec("PRAGMA synchronous = NORMAL");
+	db.exec("PRAGMA busy_timeout = 5000");
+
+	// Create schema
+	db.exec(CREATE_TABLE);
+	db.exec(CREATE_SNAPSHOTS_TABLE);
+	db.exec(CREATE_SNAPSHOTS_INDEX);
+
+	// Migrate: add token columns to existing tables that lack them
+	migrateTokenColumns(db);
+
+	// Prepare statements for all queries
+	const insertStmt = db.prepare(`
+		INSERT OR REPLACE INTO sessions
+			(agent_name, bead_id, capability, started_at, completed_at, duration_ms, exit_code, merge_result, parent_agent, run_id, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, estimated_cost_usd, model_used)
+		VALUES
+			($agent_name, $bead_id, $capability, $started_at, $completed_at, $duration_ms, $exit_code, $merge_result, $parent_agent, $run_id, $input_tokens, $output_tokens, $cache_read_tokens, $cache_creation_tokens, $estimated_cost_usd, $model_used)
+	`);
+
+	const recentStmt = db.prepare(`
+		SELECT * FROM sessions ORDER BY started_at DESC LIMIT $limit
+	`);
+
+	const byAgentStmt = db.prepare(`
+		SELECT * FROM sessions WHERE agent_name = $agent_name ORDER BY started_at DESC
+	`);
+
+	const byRunStmt = db.prepare(`
+		SELECT * FROM sessions WHERE run_id = $run_id ORDER BY started_at DESC
+	`);
+
+	const filteredStmt = db.prepare(`
+		SELECT * FROM sessions
+		WHERE ($since IS NULL OR started_at >= $since OR completed_at >= $since)
+		  AND ($until IS NULL OR started_at <= $until)
+		ORDER BY started_at DESC
+		LIMIT $limit
+	`);
+
+	const byModelStmt = db.prepare(`
+		SELECT
+		  COALESCE(model_used, 'unknown') as model,
+		  COUNT(*) as sessions,
+		  SUM(input_tokens) as input_tokens,
+		  SUM(output_tokens) as output_tokens,
+		  SUM(cache_read_tokens) as cache_read_tokens,
+		  SUM(cache_creation_tokens) as cache_creation_tokens,
+		  SUM(COALESCE(estimated_cost_usd, 0)) as estimated_cost_usd
+		FROM sessions
+		WHERE ($since IS NULL OR started_at >= $since OR completed_at >= $since)
+		  AND ($until IS NULL OR started_at <= $until)
+		GROUP BY COALESCE(model_used, 'unknown')
+		ORDER BY estimated_cost_usd DESC
+	`);
+
+	const byDateStmt = db.prepare(`
+		SELECT
+		  DATE(started_at) as date,
+		  COUNT(*) as sessions,
+		  SUM(input_tokens) as input_tokens,
+		  SUM(output_tokens) as output_tokens,
+		  SUM(cache_read_tokens) as cache_read_tokens,
+		  SUM(cache_creation_tokens) as cache_creation_tokens,
+		  SUM(COALESCE(estimated_cost_usd, 0)) as estimated_cost_usd
+		FROM sessions
+		WHERE ($since IS NULL OR started_at >= $since OR completed_at >= $since)
+		  AND ($until IS NULL OR started_at <= $until)
+		GROUP BY DATE(started_at)
+		ORDER BY date ASC
+	`);
+
+	const avgDurationAllStmt = db.prepare(`
+		SELECT AVG(duration_ms) AS avg_duration FROM sessions WHERE completed_at IS NOT NULL
+	`);
+
+	const avgDurationByCapStmt = db.prepare(`
+		SELECT AVG(duration_ms) AS avg_duration FROM sessions
+		WHERE completed_at IS NOT NULL AND capability = $capability
+	`);
+
+	// Snapshot prepared statements
+	const insertSnapshotStmt = db.prepare(`
+		INSERT INTO token_snapshots
+			(agent_name, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, estimated_cost_usd, model_used, created_at)
+		VALUES
+			($agent_name, $input_tokens, $output_tokens, $cache_read_tokens, $cache_creation_tokens, $estimated_cost_usd, $model_used, $created_at)
+	`);
+
+	const latestSnapshotsStmt = db.prepare(`
+		SELECT s.*
+		FROM token_snapshots s
+		INNER JOIN (
+			SELECT agent_name, MAX(created_at) as max_created_at
+			FROM token_snapshots
+			GROUP BY agent_name
+		) latest ON s.agent_name = latest.agent_name AND s.created_at = latest.max_created_at
+	`);
+
+	const latestSnapshotTimeStmt = db.prepare(`
+		SELECT MAX(created_at) as created_at
+		FROM token_snapshots
+		WHERE agent_name = $agent_name
+	`);
+
+	return {
+		recordSession(metrics: SessionMetrics): void {
+			insertStmt.run({
+				agent_name: metrics.agentName,
+				bead_id: metrics.beadId,
+				capability: metrics.capability,
+				started_at: metrics.startedAt,
+				completed_at: metrics.completedAt,
+				duration_ms: metrics.durationMs,
+				exit_code: metrics.exitCode,
+				merge_result: metrics.mergeResult,
+				parent_agent: metrics.parentAgent,
+				run_id: metrics.runId ?? null,
+				input_tokens: metrics.inputTokens,
+				output_tokens: metrics.outputTokens,
+				cache_read_tokens: metrics.cacheReadTokens,
+				cache_creation_tokens: metrics.cacheCreationTokens,
+				estimated_cost_usd: metrics.estimatedCostUsd,
+				model_used: metrics.modelUsed,
+			});
+		},
+
+		getRecentSessions(limit = 20): SessionMetrics[] {
+			const rows = recentStmt.all({ limit }) as SessionRow[];
+			return rows.map(rowToMetrics);
+		},
+
+		getSessionsFiltered(opts: {
+			since?: string;
+			until?: string;
+			limit?: number;
+		}): SessionMetrics[] {
+			const rows = filteredStmt.all({
+				since: opts.since ?? null,
+				until: opts.until ?? null,
+				limit: opts.limit ?? 100,
+			}) as SessionRow[];
+			return rows.map(rowToMetrics);
+		},
+
+		getSessionsByAgent(agentName: string): SessionMetrics[] {
+			const rows = byAgentStmt.all({ agent_name: agentName }) as SessionRow[];
+			return rows.map(rowToMetrics);
+		},
+
+		getSessionsByRun(runId: string): SessionMetrics[] {
+			const rows = byRunStmt.all({ run_id: runId }) as SessionRow[];
+			return rows.map(rowToMetrics);
+		},
+
+		getSessionsByModel(opts?: { since?: string; until?: string }): ModelGroup[] {
+			const rows = byModelStmt.all({
+				since: opts?.since ?? null,
+				until: opts?.until ?? null,
+			}) as ModelGroupRow[];
+			return rows.map((row) => ({
+				model: row.model,
+				sessions: row.sessions,
+				inputTokens: row.input_tokens,
+				outputTokens: row.output_tokens,
+				cacheReadTokens: row.cache_read_tokens,
+				cacheCreationTokens: row.cache_creation_tokens,
+				estimatedCostUsd: row.estimated_cost_usd,
+			}));
+		},
+
+		getSessionsByDate(opts?: { since?: string; until?: string }): DateGroup[] {
+			const rows = byDateStmt.all({
+				since: opts?.since ?? null,
+				until: opts?.until ?? null,
+			}) as DateGroupRow[];
+			return rows.map((row) => ({
+				date: row.date,
+				sessions: row.sessions,
+				inputTokens: row.input_tokens,
+				outputTokens: row.output_tokens,
+				cacheReadTokens: row.cache_read_tokens,
+				cacheCreationTokens: row.cache_creation_tokens,
+				estimatedCostUsd: row.estimated_cost_usd,
+			}));
+		},
+
+		getAverageDuration(capability?: string): number {
+			if (capability !== undefined) {
+				const row = avgDurationByCapStmt.get({ capability }) as
+					| { avg_duration: number | null }
+					| undefined;
+				return row?.avg_duration ?? 0;
+			}
+			const row = avgDurationAllStmt.get() as { avg_duration: number | null } | undefined;
+			return row?.avg_duration ?? 0;
+		},
+
+		purge(options: { all?: boolean; agent?: string }): number {
+			if (options.all) {
+				const countRow = db.prepare("SELECT COUNT(*) as cnt FROM sessions").get() as
+					| { cnt: number }
+					| undefined;
+				const count = countRow?.cnt ?? 0;
+				db.prepare("DELETE FROM sessions").run();
+				return count;
+			}
+
+			if (options.agent !== undefined) {
+				const countRow = db
+					.prepare("SELECT COUNT(*) as cnt FROM sessions WHERE agent_name = $agent")
+					.get({ agent: options.agent }) as { cnt: number } | undefined;
+				const count = countRow?.cnt ?? 0;
+				db.prepare("DELETE FROM sessions WHERE agent_name = $agent").run({
+					agent: options.agent,
+				});
+				return count;
+			}
+
+			return 0;
+		},
+
+		recordSnapshot(snapshot: TokenSnapshot): void {
+			insertSnapshotStmt.run({
+				agent_name: snapshot.agentName,
+				input_tokens: snapshot.inputTokens,
+				output_tokens: snapshot.outputTokens,
+				cache_read_tokens: snapshot.cacheReadTokens,
+				cache_creation_tokens: snapshot.cacheCreationTokens,
+				estimated_cost_usd: snapshot.estimatedCostUsd,
+				model_used: snapshot.modelUsed,
+				created_at: snapshot.createdAt,
+			});
+		},
+
+		getLatestSnapshots(): TokenSnapshot[] {
+			const rows = latestSnapshotsStmt.all() as SnapshotRow[];
+			return rows.map(rowToSnapshot);
+		},
+
+		getLatestSnapshotTime(agentName: string): string | null {
+			const row = latestSnapshotTimeStmt.get({ agent_name: agentName }) as
+				| { created_at: string }
+				| undefined;
+			return row?.created_at ?? null;
+		},
+
+		purgeSnapshots(options: { all?: boolean; agent?: string; olderThanMs?: number }): number {
+			if (options.all) {
+				const countRow = db.prepare("SELECT COUNT(*) as cnt FROM token_snapshots").get() as
+					| { cnt: number }
+					| undefined;
+				const count = countRow?.cnt ?? 0;
+				db.prepare("DELETE FROM token_snapshots").run();
+				return count;
+			}
+
+			if (options.agent !== undefined) {
+				const countRow = db
+					.prepare("SELECT COUNT(*) as cnt FROM token_snapshots WHERE agent_name = $agent")
+					.get({ agent: options.agent }) as { cnt: number } | undefined;
+				const count = countRow?.cnt ?? 0;
+				db.prepare("DELETE FROM token_snapshots WHERE agent_name = $agent").run({
+					agent: options.agent,
+				});
+				return count;
+			}
+
+			if (options.olderThanMs !== undefined) {
+				const cutoffTime = new Date(Date.now() - options.olderThanMs).toISOString();
+				const countRow = db
+					.prepare("SELECT COUNT(*) as cnt FROM token_snapshots WHERE created_at < $cutoff")
+					.get({ cutoff: cutoffTime }) as { cnt: number } | undefined;
+				const count = countRow?.cnt ?? 0;
+				db.prepare("DELETE FROM token_snapshots WHERE created_at < $cutoff").run({
+					cutoff: cutoffTime,
+				});
+				return count;
+			}
+
+			return 0;
+		},
+
+		close(): void {
+			db.close();
+		},
+	};
+}