@tokentop/ttop 0.2.2 → 0.4.0

package/src/storage/db.ts

@@ -1,7 +1,7 @@
-import { Database } from 'bun:sqlite';
-import * as fs from 'fs/promises';
-import { PATHS } from './paths.ts';
-import { applyMigrations } from './migrations/index.ts';
+import { Database } from "bun:sqlite";
+import * as fs from "fs/promises";
+import { applyMigrations } from "./migrations/index.ts";
+import { PATHS } from "./paths.ts";
 
 let db: Database | null = null;
 let currentAppRunId: number | null = null;
@@ -13,10 +13,10 @@ export async function initDatabase(): Promise<Database> {
 
   db = new Database(PATHS.data.database, { create: true });
 
-  db.exec('PRAGMA journal_mode = WAL');
-  db.exec('PRAGMA synchronous = NORMAL');
-  db.exec('PRAGMA foreign_keys = ON');
-  db.exec('PRAGMA busy_timeout = 2000');
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec("PRAGMA synchronous = NORMAL");
+  db.exec("PRAGMA foreign_keys = ON");
+  db.exec("PRAGMA busy_timeout = 2000");
 
   applyMigrations(db);
 
@@ -27,9 +27,9 @@ export async function initDatabase(): Promise<Database> {
 
   const result = stmt.run(
     Date.now(),
-    process.env.npm_package_version ?? '0.0.0',
+    process.env.npm_package_version ?? "0.0.0",
     process.pid,
-    require('os').hostname()
+    require("os").hostname(),
   );
 
   currentAppRunId = Number(result.lastInsertRowid);
@@ -39,7 +39,7 @@ export async function initDatabase(): Promise<Database> {
 
 export function getDatabase(): Database {
   if (!db) {
-    throw new Error('Database not initialized. Call initDatabase() first.');
+    throw new Error("Database not initialized. Call initDatabase() first.");
   }
   return db;
 }
@@ -50,7 +50,7 @@ export function getAppRunId(): number | null {
 
 export function closeDatabase(): void {
   if (db && currentAppRunId) {
-    db.prepare('UPDATE app_runs SET ended_at = ? WHERE id = ?').run(Date.now(), currentAppRunId);
+    db.prepare("UPDATE app_runs SET ended_at = ? WHERE id = ?").run(Date.now(), currentAppRunId);
   }
   if (db) {
     db.close();

package/src/storage/index.ts

@@ -1,66 +1,65 @@
-export { PATHS } from './paths.ts';
-
 export {
-  initDatabase,
-  getDatabase,
   closeDatabase,
-  isDatabaseInitialized,
   getAppRunId,
-} from './db.ts';
-
+  getDatabase,
+  initDatabase,
+  isDatabaseInitialized,
+} from "./db.ts";
+export { PATHS } from "./paths.ts";
+export type { LatestStreamTotals } from "./repos/agentSessions.ts";
 export {
+  getAgentSession,
+  getLatestStreamTotalsForAllSessions,
+  getRecentSessions,
+  getSessionsByProject,
+  insertAgentSessionSnapshot,
+  upsertAgentSession,
+} from "./repos/agentSessions.ts";
+export {
+  getLatestProviderSnapshot,
   insertProviderSnapshot,
   insertProviderSnapshotBatch,
   queryProviderSnapshots,
-  getLatestProviderSnapshot,
-} from './repos/providerSnapshots.ts';
-
+} from "./repos/providerSnapshots.ts";
+export type {
+  ModelDailyCost,
+  ProjectDailyCost,
+  ProviderDailyCost,
+  SessionActivityPoint,
+} from "./repos/usageEvents.ts";
 export {
+  calculateBurnRate,
+  getSessionActivityTimeline,
+  getTotalUsageInWindow,
   insertUsageEvent,
   insertUsageEventBatch,
-  queryUsageTimeSeries,
-  queryProviderDailyCosts,
   queryModelDailyCosts,
   queryProjectDailyCosts,
-  calculateBurnRate,
-  getTotalUsageInWindow,
-  getSessionActivityTimeline,
-} from './repos/usageEvents.ts';
-
-export type { SessionActivityPoint, ProviderDailyCost, ModelDailyCost, ProjectDailyCost } from './repos/usageEvents.ts';
-
-export {
-  upsertAgentSession,
-  insertAgentSessionSnapshot,
-  getAgentSession,
-  getRecentSessions,
-  getSessionsByProject,
-  getLatestStreamTotalsForAllSessions,
-} from './repos/agentSessions.ts';
-
-export type { LatestStreamTotals } from './repos/agentSessions.ts';
+  queryProviderDailyCosts,
+  queryUsageTimeSeries,
+} from "./repos/usageEvents.ts";
 
 export type {
-  UsageEventSource,
-  SessionStatus,
-  CostSource,
-  PricingSource,
-  AppRunRow,
-  ProviderSnapshotRow,
-  ProviderSnapshotInsert,
   AgentSessionDim,
-  AgentSessionUpsert,
-  AgentSessionSnapshotRow,
   AgentSessionSnapshotInsert,
+  AgentSessionSnapshotRow,
   AgentSessionStreamSnapshotRow,
-  UsageEventRow,
-  UsageEventInsert,
-  HourlyAggregateRow,
+  AgentSessionUpsert,
+  AppRunRow,
+  CostSource,
   DailyAggregateRow,
-  TimeSeriesPoint,
+  HourlyAggregateRow,
+  PricingSource,
+  ProviderSnapshotInsert,
+  ProviderSnapshotRow,
+  SessionStatus,
+  StreamTotals,
   TimeSeriesFilters,
+  TimeSeriesPoint,
+  UsageEventInsert,
+  UsageEventRow,
+  UsageEventSource,
   UsageQueryOptions,
-  StreamTotals,
-} from './types.ts';
+} from "./types.ts";
 
-export { computeStreamDelta } from './types.ts';
+export { computeStreamDelta } from "./types.ts";

package/src/storage/migrations/index.ts

@@ -1,4 +1,4 @@
-import type { Database } from 'bun:sqlite';
+import type { Database } from "bun:sqlite";
 
 export interface Migration {
   version: number;
@@ -167,7 +167,7 @@ export const migrations: Migration[] = [
 ];
 
 export function getCurrentVersion(db: Database): number {
-  const result = db.prepare('PRAGMA user_version').get() as { user_version: number } | null;
+  const result = db.prepare("PRAGMA user_version").get() as { user_version: number } | null;
   return result?.user_version ?? 0;
 }
 

package/src/storage/paths.ts

@@ -1,24 +1,24 @@
-import * as path from 'path';
-import * as os from 'os';
+import * as os from "os";
+import * as path from "path";
 
 const HOME = os.homedir();
 
 export const PATHS = {
   config: {
-    dir: path.join(HOME, '.config/tokentop'),
-    file: path.join(HOME, '.config/tokentop/config.json'),
-    fileJsonc: path.join(HOME, '.config/tokentop/config.jsonc'),
-    plugins: path.join(HOME, '.config/tokentop/plugins'),
+    dir: path.join(HOME, ".config/tokentop"),
+    file: path.join(HOME, ".config/tokentop/config.json"),
+    fileJsonc: path.join(HOME, ".config/tokentop/config.jsonc"),
+    plugins: path.join(HOME, ".config/tokentop/plugins"),
   },
   data: {
-    dir: path.join(HOME, '.local/share/tokentop'),
-    database: path.join(HOME, '.local/share/tokentop/usage.db'),
-    sessions: path.join(HOME, '.local/share/tokentop/sessions'),
-    cache: path.join(HOME, '.local/share/tokentop/cache'),
-    logs: path.join(HOME, '.local/share/tokentop/logs'),
+    dir: path.join(HOME, ".local/share/tokentop"),
+    database: path.join(HOME, ".local/share/tokentop/usage.db"),
+    sessions: path.join(HOME, ".local/share/tokentop/sessions"),
+    cache: path.join(HOME, ".local/share/tokentop/cache"),
+    logs: path.join(HOME, ".local/share/tokentop/logs"),
   },
   cache: {
-    dir: path.join(HOME, '.cache/tokentop'),
-    nodeModules: path.join(HOME, '.cache/tokentop/node_modules'),
+    dir: path.join(HOME, ".cache/tokentop"),
+    nodeModules: path.join(HOME, ".cache/tokentop/node_modules"),
   },
 } as const;

package/src/storage/persistence-service.ts

@@ -0,0 +1,206 @@
+/**
+ * Module-level session persistence service.
+ *
+ * All mutable state is stored on globalThis to survive bun --hot HMR
+ * reloads and React component remounts. This decouples persistence
+ * from React's lifecycle entirely.
+ *
+ * Call persistSessions() on every poll tick (1s). The service internally:
+ *   Gate 1: Skips sessions whose usage data hasn't changed (fingerprint)
+ *   Gate 2: Throttles writes to at most once per SNAPSHOT_INTERVAL_MS
+ *
+ * Both gates update their state only on successful writes, ensuring
+ * deferred writes when the throttle expires.
+ */
+
+import { isDatabaseInitialized } from "./db.ts";
+import {
+  getLatestStreamTotalsForAllSessions,
+  insertAgentSessionSnapshot,
+  upsertAgentSession,
+} from "./repos/agentSessions.ts";
+import { insertUsageEventBatch } from "./repos/usageEvents.ts";
+import type {
+  AgentSessionSnapshotInsert,
+  AgentSessionStreamSnapshotRow,
+  AgentSessionUpsert,
+  StreamTotals,
+  UsageEventInsert,
+} from "./types.ts";
+import { computeStreamDelta } from "./types.ts";
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/** Minimum interval between DB writes for the same session */
+const SNAPSHOT_INTERVAL_MS = 300_000; // 5 minutes
+
+// ---------------------------------------------------------------------------
+// Global state (survives bun --hot HMR and React remounts)
+// ---------------------------------------------------------------------------
+
+interface PersistenceState {
+  /** Timestamp of last successful DB write per session key */
+  lastWriteTimestamps: Map<string, number>;
+  /** Usage-based fingerprint per session key (updated only on successful write) */
+  sessionFingerprints: Map<string, string>;
+  /** Previous stream totals for delta computation */
+  previousStreamTotals: Map<string, StreamTotals>;
+  /** Whether startup seeding has completed */
+  seeded: boolean;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __tokentopPersistence: PersistenceState | undefined;
+}
+
+function getState(): PersistenceState {
+  if (!globalThis.__tokentopPersistence) {
+    globalThis.__tokentopPersistence = {
+      lastWriteTimestamps: new Map(),
+      sessionFingerprints: new Map(),
+      previousStreamTotals: new Map(),
+      seeded: false,
+    };
+  }
+  return globalThis.__tokentopPersistence;
+}
+
+// ---------------------------------------------------------------------------
+// Fingerprinting
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute a fingerprint based on usage data only (not lastActivityAt).
+ * This ensures inactive sessions with stable usage don't trigger writes,
+ * while active sessions that consume tokens do.
+ */
+function computeFingerprint(snapshot: Omit<AgentSessionSnapshotInsert, "agentSessionId">): string {
+  return `${snapshot.totalCostUsd}:${snapshot.requestCount}:${snapshot.totalInputTokens}:${snapshot.totalOutputTokens}`;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface SessionPersistData {
+  session: AgentSessionUpsert;
+  snapshot: Omit<AgentSessionSnapshotInsert, "agentSessionId">;
+  streams: Omit<AgentSessionStreamSnapshotRow, "agentSessionSnapshotId">[];
+}
+
+/**
+ * Persist session data to the database with per-session throttling.
+ *
+ * Safe to call on every poll tick (every 1s). The service internally:
+ *   1. Skips sessions whose usage data hasn't changed (fingerprint gate)
+ *   2. Throttles writes to at most once per SNAPSHOT_INTERVAL_MS per session
+ *
+ * @returns Number of sessions actually written to DB
+ */
+export function persistSessions(sessions: SessionPersistData[]): number {
+  if (!isDatabaseInitialized()) return 0;
+
+  const state = getState();
+  const now = Date.now();
+  let persistedCount = 0;
+
+  for (const { session, snapshot, streams } of sessions) {
+    const sessionKey = `${session.agentId}:${session.sessionId}`;
+
+    // Gate 1: Skip sessions whose usage data hasn't changed since last write
+    const fp = computeFingerprint(snapshot);
+    if (state.sessionFingerprints.get(sessionKey) === fp) continue;
+
+    // Gate 2: Throttle writes to once per interval per session
+    const lastTs = state.lastWriteTimestamps.get(sessionKey) ?? 0;
+    if (now - lastTs < SNAPSHOT_INTERVAL_MS) continue;
+
+    // Both gates passed — write to DB
+    try {
+      const agentSessionId = upsertAgentSession(session);
+      insertAgentSessionSnapshot({ ...snapshot, agentSessionId }, streams);
+
+      // Compute and emit usage event deltas
+      const usageEvents: UsageEventInsert[] = [];
+      for (const stream of streams) {
+        const streamKey = `${sessionKey}:${stream.provider}:${stream.model}`;
+        const current: StreamTotals = {
+          inputTokens: stream.inputTokens,
+          outputTokens: stream.outputTokens,
+          cacheReadTokens: stream.cacheReadTokens,
+          cacheWriteTokens: stream.cacheWriteTokens,
+          costUsd: stream.costUsd,
+          requestCount: stream.requestCount,
+        };
+
+        const previous = state.previousStreamTotals.get(streamKey);
+        const delta = computeStreamDelta(current, previous);
+
+        if (delta) {
+          usageEvents.push({
+            timestamp: now,
+            source: "agent",
+            provider: stream.provider,
+            model: stream.model,
+            agentId: session.agentId,
+            sessionId: session.sessionId,
+            projectPath: session.projectPath ?? null,
+            inputTokens: delta.inputTokens,
+            outputTokens: delta.outputTokens,
+            cacheReadTokens: delta.cacheReadTokens,
+            cacheWriteTokens: delta.cacheWriteTokens,
+            costUsd: delta.costUsd,
+            requestCount: delta.requestCount,
+            pricingSource: stream.pricingSource ?? null,
+          });
+        }
+
+        state.previousStreamTotals.set(streamKey, current);
+      }
+
+      if (usageEvents.length > 0) {
+        insertUsageEventBatch(usageEvents);
+      }
+
+      // Update tracking state ONLY on successful write
+      state.lastWriteTimestamps.set(sessionKey, now);
+      state.sessionFingerprints.set(sessionKey, fp);
+      persistedCount++;
+    } catch (err) {
+      console.error("Failed to persist session:", err);
+    }
+  }
+
+  return persistedCount;
+}
+
+/**
+ * Seed previous stream totals from the database.
+ * Called once at startup after DB initialization to ensure
+ * accurate delta computation from the first persistence call.
+ */
+export function seedPreviousTotals(): void {
+  const state = getState();
+  if (state.seeded) return;
+
+  try {
+    const latestTotals = getLatestStreamTotalsForAllSessions();
+    for (const row of latestTotals) {
+      const streamKey = `${row.agentId}:${row.sessionId}:${row.provider}:${row.model}`;
+      state.previousStreamTotals.set(streamKey, {
+        inputTokens: row.inputTokens,
+        outputTokens: row.outputTokens,
+        cacheReadTokens: row.cacheReadTokens,
+        cacheWriteTokens: row.cacheWriteTokens,
+        costUsd: row.costUsd,
+        requestCount: row.requestCount,
+      });
+    }
+    state.seeded = true;
+  } catch (err) {
+    console.error("Failed to seed previous totals from DB:", err);
+  }
+}

package/src/storage/repos/agentSessions.ts

@@ -1,10 +1,10 @@
-import { getDatabase } from '../db.ts';
+import { getDatabase } from "../db.ts";
 import type {
   AgentSessionDim,
-  AgentSessionUpsert,
   AgentSessionSnapshotInsert,
   AgentSessionStreamSnapshotRow,
-} from '../types.ts';
+  AgentSessionUpsert,
+} from "../types.ts";
 
 const UPSERT_SESSION_SQL = `
   INSERT INTO agent_sessions (agent_id, session_id, project_path, started_at, first_seen_at, last_seen_at)
@@ -36,21 +36,23 @@ export function upsertAgentSession(session: AgentSessionUpsert): number {
   const db = getDatabase();
   const now = Date.now();
 
-  const row = db.prepare(UPSERT_SESSION_SQL).get(
-    session.agentId,
-    session.sessionId,
-    session.projectPath ?? null,
-    session.startedAt ?? null,
-    session.firstSeenAt ?? now,
-    session.lastSeenAt
-  ) as { id: number };
+  const row = db
+    .prepare(UPSERT_SESSION_SQL)
+    .get(
+      session.agentId,
+      session.sessionId,
+      session.projectPath ?? null,
+      session.startedAt ?? null,
+      session.firstSeenAt ?? now,
+      session.lastSeenAt,
+    ) as { id: number };
 
   return row.id;
 }
 
 export function insertAgentSessionSnapshot(
   snapshot: AgentSessionSnapshotInsert,
-  streams: Omit<AgentSessionStreamSnapshotRow, 'agentSessionSnapshotId'>[]
+  streams: Omit<AgentSessionStreamSnapshotRow, "agentSessionSnapshotId">[],
 ): number {
   const db = getDatabase();
 
@@ -70,7 +72,7 @@ export function insertAgentSessionSnapshot(
       snapshot.totalCacheReadTokens,
       snapshot.totalCacheWriteTokens,
       snapshot.totalCostUsd,
-      snapshot.requestCount
+      snapshot.requestCount,
     );
 
     snapshotId = Number(result.lastInsertRowid);
@@ -86,7 +88,7 @@ export function insertAgentSessionSnapshot(
         stream.cacheWriteTokens,
         stream.costUsd,
         stream.requestCount,
-        stream.pricingSource ?? null
+        stream.pricingSource ?? null,
       );
     }
   })();
@@ -97,9 +99,11 @@ export function insertAgentSessionSnapshot(
 export function getAgentSession(agentId: string, sessionId: string): AgentSessionDim | null {
   const db = getDatabase();
 
-  const row = db.prepare(`
+  const row = db
+    .prepare(`
     SELECT * FROM agent_sessions WHERE agent_id = ? AND session_id = ?
-  `).get(agentId, sessionId) as DbSessionRow | null;
+  `)
+    .get(agentId, sessionId) as DbSessionRow | null;
 
   return row ? mapSessionRow(row) : null;
 }
@@ -107,11 +111,13 @@ export function getAgentSession(agentId: string, sessionId: string): AgentSessio
 export function getRecentSessions(limit = 50): AgentSessionDim[] {
   const db = getDatabase();
 
-  const rows = db.prepare(`
+  const rows = db
+    .prepare(`
     SELECT * FROM agent_sessions
     ORDER BY last_seen_at DESC
     LIMIT ?
-  `).all(limit) as DbSessionRow[];
+  `)
+    .all(limit) as DbSessionRow[];
 
   return rows.map(mapSessionRow);
 }
@@ -119,12 +125,14 @@ export function getRecentSessions(limit = 50): AgentSessionDim[] {
 export function getSessionsByProject(projectPath: string, limit = 50): AgentSessionDim[] {
   const db = getDatabase();
 
-  const rows = db.prepare(`
+  const rows = db
+    .prepare(`
     SELECT * FROM agent_sessions
     WHERE project_path = ?
     ORDER BY last_seen_at DESC
     LIMIT ?
-  `).all(projectPath, limit) as DbSessionRow[];
+  `)
+    .all(projectPath, limit) as DbSessionRow[];
 
   return rows.map(mapSessionRow);
 }
@@ -167,7 +175,8 @@ export interface LatestStreamTotals {
 export function getLatestStreamTotalsForAllSessions(): LatestStreamTotals[] {
   const db = getDatabase();
 
-  const rows = db.prepare(`
+  const rows = db
+    .prepare(`
     SELECT
       s.agent_id, s.session_id,
       ss.provider, ss.model,
@@ -182,7 +191,8 @@ export function getLatestStreamTotalsForAllSessions(): LatestStreamTotals[] {
       FROM agent_session_snapshots snap2
       GROUP BY snap2.agent_session_id
     )
-  `).all() as Array<{
+  `)
+    .all() as Array<{
     agent_id: string;
     session_id: string;
     provider: string;
@@ -195,7 +205,7 @@ export function getLatestStreamTotalsForAllSessions(): LatestStreamTotals[] {
     request_count: number;
   }>;
 
-  return rows.map(r => ({
+  return rows.map((r) => ({
     agentId: r.agent_id,
     sessionId: r.session_id,
     provider: r.provider,

package/src/storage/repos/providerSnapshots.ts

@@ -1,5 +1,5 @@
-import { getDatabase } from '../db.ts';
-import type { ProviderSnapshotInsert, ProviderSnapshotRow, CostSource } from '../types.ts';
+import { getDatabase } from "../db.ts";
+import type { CostSource, ProviderSnapshotInsert, ProviderSnapshotRow } from "../types.ts";
 
 const INSERT_SQL = `
   INSERT INTO provider_snapshots (
@@ -36,7 +36,7 @@ export function insertProviderSnapshot(snapshot: ProviderSnapshotInsert): number
     snapshot.tokensOutput ?? null,
     snapshot.costUsd ?? null,
     snapshot.costSource ?? null,
-    snapshot.rawJson ?? null
+    snapshot.rawJson ?? null,
   );
 
   return Number(result.lastInsertRowid);
@@ -60,7 +60,7 @@ export function insertProviderSnapshotBatch(snapshots: ProviderSnapshotInsert[])
         s.tokensOutput ?? null,
         s.costUsd ?? null,
         s.costSource ?? null,
-        s.rawJson ?? null
+        s.rawJson ?? null,
       );
     }
   });
@@ -72,7 +72,7 @@ export function queryProviderSnapshots(
   provider: string,
   startMs: number,
   endMs: number,
-  limit = 100
+  limit = 100,
 ): ProviderSnapshotRow[] {
   const db = getDatabase();
   const rows = db.prepare(QUERY_BY_PROVIDER_SQL).all(provider, startMs, endMs, limit) as DbRow[];