@os-eco/overstory-cli 0.6.1

package/src/metrics/store.ts

@@ -0,0 +1,445 @@
+/**
+ * SQLite-backed metrics storage for agent session data.
+ *
+ * Uses bun:sqlite for zero-dependency, synchronous database access.
+ * All operations are sync — no async/await needed.
+ */
+
+import { Database } from "bun:sqlite";
+import type { SessionMetrics, TokenSnapshot } from "../types.ts";
+
+export interface MetricsStore {
+	recordSession(metrics: SessionMetrics): void;
+	getRecentSessions(limit?: number): SessionMetrics[];
+	getSessionsByAgent(agentName: string): SessionMetrics[];
+	getSessionsByRun(runId: string): SessionMetrics[];
+	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;
+	task_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;
+	input_tokens: number;
+	output_tokens: number;
+	cache_read_tokens: number;
+	cache_creation_tokens: number;
+	estimated_cost_usd: number | null;
+	model_used: string | null;
+	run_id: 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;
+}
+
+const CREATE_TABLE = `
+CREATE TABLE IF NOT EXISTS sessions (
+  agent_name TEXT NOT NULL,
+  task_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,
+  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,
+  run_id TEXT,
+  PRIMARY KEY (agent_name, task_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)
+`;
+
+/** Token columns added in the token instrumentation migration. */
+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" },
+] as const;
+
+/**
+ * Migrate an existing sessions table from bead_id to task_id column.
+ * Safe to call multiple times — only renames if bead_id exists and task_id does not.
+ */
+function migrateBeadIdToTaskId(db: Database): void {
+	const rows = db.prepare("PRAGMA table_info(sessions)").all() as Array<{ name: string }>;
+	const existingColumns = new Set(rows.map((r) => r.name));
+	if (existingColumns.has("bead_id") && !existingColumns.has("task_id")) {
+		db.exec("ALTER TABLE sessions RENAME COLUMN bead_id TO task_id");
+	}
+}
+
+/**
+ * Migrate an existing sessions table to include the run_id column.
+ * Safe to call multiple times — only adds the column if missing.
+ */
+function migrateRunIdColumn(db: Database): void {
+	const rows = db.prepare("PRAGMA table_info(sessions)").all() as Array<{ name: string }>;
+	const existingColumns = new Set(rows.map((r) => r.name));
+	if (!existingColumns.has("run_id")) {
+		db.exec("ALTER TABLE sessions ADD COLUMN run_id TEXT");
+	}
+}
+
+/**
+ * Migrate an existing sessions table to include token columns.
+ * Safe to call multiple times — only adds columns that are missing.
+ */
+function migrateTokenColumns(db: 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.task_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,
+		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,
+		runId: row.run_id,
+	};
+}
+
+/** 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 busy_timeout = 5000");
+
+	// Create schema
+	db.exec(CREATE_TABLE);
+	db.exec(CREATE_SNAPSHOTS_TABLE);
+	db.exec(CREATE_SNAPSHOTS_INDEX);
+
+	// Migrate: rename bead_id → task_id, add token columns and run_id column to existing tables
+	migrateBeadIdToTaskId(db);
+	migrateTokenColumns(db);
+	migrateRunIdColumn(db);
+
+	// Prepare statements for all queries
+	const insertStmt = db.prepare<
+		void,
+		{
+			$agent_name: string;
+			$task_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;
+			$input_tokens: number;
+			$output_tokens: number;
+			$cache_read_tokens: number;
+			$cache_creation_tokens: number;
+			$estimated_cost_usd: number | null;
+			$model_used: string | null;
+			$run_id: string | null;
+		}
+	>(`
+		INSERT OR REPLACE INTO sessions
+			(agent_name, task_id, capability, started_at, completed_at, duration_ms, exit_code, merge_result, parent_agent, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, estimated_cost_usd, model_used, run_id)
+		VALUES
+			($agent_name, $task_id, $capability, $started_at, $completed_at, $duration_ms, $exit_code, $merge_result, $parent_agent, $input_tokens, $output_tokens, $cache_read_tokens, $cache_creation_tokens, $estimated_cost_usd, $model_used, $run_id)
+	`);
+
+	const recentStmt = db.prepare<SessionRow, { $limit: number }>(`
+		SELECT * FROM sessions ORDER BY started_at DESC LIMIT $limit
+	`);
+
+	const byAgentStmt = db.prepare<SessionRow, { $agent_name: string }>(`
+		SELECT * FROM sessions WHERE agent_name = $agent_name ORDER BY started_at DESC
+	`);
+
+	const byRunStmt = db.prepare<SessionRow, { $run_id: string }>(`
+		SELECT * FROM sessions WHERE run_id = $run_id ORDER BY started_at DESC
+	`);
+
+	const avgDurationAllStmt = db.prepare<{ avg_duration: number | null }, Record<string, never>>(`
+		SELECT AVG(duration_ms) AS avg_duration FROM sessions WHERE completed_at IS NOT NULL
+	`);
+
+	const avgDurationByCapStmt = db.prepare<
+		{ avg_duration: number | null },
+		{ $capability: string }
+	>(`
+		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<
+		void,
+		{
+			$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;
+		}
+	>(`
+		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<SnapshotRow, Record<string, never>>(`
+		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<
+		{ created_at: string } | null,
+		{ $agent_name: string }
+	>(`
+		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,
+				$task_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,
+				$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,
+				$run_id: metrics.runId,
+			});
+		},
+
+		getRecentSessions(limit = 20): SessionMetrics[] {
+			const rows = recentStmt.all({ $limit: limit });
+			return rows.map(rowToMetrics);
+		},
+
+		getSessionsByAgent(agentName: string): SessionMetrics[] {
+			const rows = byAgentStmt.all({ $agent_name: agentName });
+			return rows.map(rowToMetrics);
+		},
+
+		getSessionsByRun(runId: string): SessionMetrics[] {
+			const rows = byRunStmt.all({ $run_id: runId });
+			return rows.map(rowToMetrics);
+		},
+
+		getAverageDuration(capability?: string): number {
+			if (capability !== undefined) {
+				const row = avgDurationByCapStmt.get({ $capability: capability });
+				return row?.avg_duration ?? 0;
+			}
+			const row = avgDurationAllStmt.get({});
+			return row?.avg_duration ?? 0;
+		},
+
+		purge(options: { all?: boolean; agent?: string }): number {
+			if (options.all) {
+				const countRow = db
+					.prepare<{ cnt: number }, []>("SELECT COUNT(*) as cnt FROM sessions")
+					.get();
+				const count = countRow?.cnt ?? 0;
+				db.prepare("DELETE FROM sessions").run();
+				return count;
+			}
+
+			if (options.agent !== undefined) {
+				const countRow = db
+					.prepare<{ cnt: number }, { $agent: string }>(
+						"SELECT COUNT(*) as cnt FROM sessions WHERE agent_name = $agent",
+					)
+					.get({ $agent: options.agent });
+				const count = countRow?.cnt ?? 0;
+				db.prepare<void, { $agent: string }>("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({});
+			return rows.map(rowToSnapshot);
+		},
+
+		getLatestSnapshotTime(agentName: string): string | null {
+			const row = latestSnapshotTimeStmt.get({ $agent_name: agentName });
+			return row?.created_at ?? null;
+		},
+
+		purgeSnapshots(options: { all?: boolean; agent?: string; olderThanMs?: number }): number {
+			if (options.all) {
+				const countRow = db
+					.prepare<{ cnt: number }, []>("SELECT COUNT(*) as cnt FROM token_snapshots")
+					.get();
+				const count = countRow?.cnt ?? 0;
+				db.prepare("DELETE FROM token_snapshots").run();
+				return count;
+			}
+
+			if (options.agent !== undefined) {
+				const countRow = db
+					.prepare<{ cnt: number }, { $agent: string }>(
+						"SELECT COUNT(*) as cnt FROM token_snapshots WHERE agent_name = $agent",
+					)
+					.get({ $agent: options.agent });
+				const count = countRow?.cnt ?? 0;
+				db.prepare<void, { $agent: string }>(
+					"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<{ cnt: number }, { $cutoff: string }>(
+						"SELECT COUNT(*) as cnt FROM token_snapshots WHERE created_at < $cutoff",
+					)
+					.get({ $cutoff: cutoffTime });
+				const count = countRow?.cnt ?? 0;
+				db.prepare<void, { $cutoff: string }>(
+					"DELETE FROM token_snapshots WHERE created_at < $cutoff",
+				).run({
+					$cutoff: cutoffTime,
+				});
+				return count;
+			}
+
+			return 0;
+		},
+
+		close(): void {
+			db.close();
+		},
+	};
+}