@tokentop/ttop 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokentop/ttop",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Real-time AI token usage monitor - htop for your API costs",
   "author": "Nigel Bazzeghin <nbazzeghin@gmail.com>",
   "license": "MIT",
@@ -33,8 +33,8 @@
     "snapshot": "bun src/tui/debug/snapshot.tsx"
   },
   "dependencies": {
-    "@opentui/core": "0.1.80",
-    "@opentui/react": "0.1.80",
+    "@opentui/core": "0.1.81",
+    "@opentui/react": "0.1.81",
     "@tokentop/agent-claude-code": "^1.1.0",
     "@tokentop/agent-opencode": "^1.0.0",
     "@tokentop/plugin-sdk": "^1.1.0",

package/src/plugins/lifecycle.ts

@@ -91,25 +91,29 @@ class PluginLifecycleManager {
   async initializeAll(): Promise<void> {
     const plugins = pluginRegistry.getAllPlugins();
 
-    for (const plugin of plugins) {
-      const entry = this.getOrCreate(plugin);
-      if (entry.state !== "loaded") continue;
-
-      const ok = await this.invokeHook(plugin, "initialize");
-      entry.state = ok ? "initialized" : "failed";
-    }
+    await Promise.all(
+      plugins.map(async (plugin) => {
+        const entry = this.getOrCreate(plugin);
+        if (entry.state !== "loaded") return;
+
+        const ok = await this.invokeHook(plugin, "initialize");
+        entry.state = ok ? "initialized" : "failed";
+      }),
+    );
   }
 
   async startAll(): Promise<void> {
     const plugins = pluginRegistry.getAllPlugins();
 
-    for (const plugin of plugins) {
-      const entry = this.getOrCreate(plugin);
-      if (entry.state !== "initialized") continue;
+    await Promise.all(
+      plugins.map(async (plugin) => {
+        const entry = this.getOrCreate(plugin);
+        if (entry.state !== "initialized") return;
 
-      const ok = await this.invokeHook(plugin, "start");
-      entry.state = ok ? "started" : "failed";
-    }
+        const ok = await this.invokeHook(plugin, "start");
+        entry.state = ok ? "started" : "failed";
+      }),
+    );
   }
 
   async stopAll(): Promise<void> {

package/src/plugins/notifications/terminal-bell.ts

@@ -18,8 +18,15 @@ export const terminalBellPlugin: NotificationPlugin = {
   permissions: {},
 
   configSchema: {
-    enabled: { type: "boolean", default: true, description: "Enable terminal bell notifications" },
+    enabled: {
+      type: "boolean",
+      label: "Enabled",
+      default: true,
+      description: "Enable terminal bell notifications",
+    },
     minSeverity: {
+      label: "Minimum severity",
+      description: "Only trigger bell for alerts at this severity or higher.",
       type: "select",
       default: "warning",
       options: [

package/src/plugins/notifications/visual-flash.ts

@@ -18,8 +18,18 @@ export const visualFlashPlugin: NotificationPlugin = {
   permissions: {},
 
   configSchema: {
-    enabled: { type: "boolean", default: true, description: "Enable visual flash notifications" },
-    duration: { type: "number", default: 100, description: "Flash duration in milliseconds" },
+    enabled: {
+      type: "boolean",
+      label: "Enabled",
+      default: true,
+      description: "Enable visual flash notifications",
+    },
+    duration: {
+      type: "number",
+      label: "Flash duration (ms)",
+      default: 100,
+      description: "Flash duration in milliseconds",
+    },
   },
 
   supports(event: NotificationEvent): boolean {

package/src/plugins/providers/zai.ts

@@ -64,7 +64,9 @@ export const zaiCodingPlanPlugin: ProviderPlugin = {
   auth: {
     async discover(ctx: PluginContext): Promise<CredentialResult> {
       // 1. Try OpenCode auth (api, wellknown, or oauth)
-      const entry = await ctx.authSources.opencode.getProviderEntry("zai-coding-plan");
+      const entry =
+        (await ctx.authSources.opencode.getProviderEntry("zhipuai-coding-plan")) ||
+        (await ctx.authSources.opencode.getProviderEntry("zai-coding-plan"));
       if (entry) {
         if (entry.type === "api" && entry.key) {
           return { ok: true, credentials: { apiKey: entry.key, source: "opencode" } };

package/src/plugins/registry.ts

@@ -35,6 +35,7 @@ class PluginRegistryImpl {
 
   private sources = new Map<string, PluginSource>();
   private initialized = false;
+  private officialIds = new Set<string>();
 
   private sourceKey(type: string, id: string): string {
     return `${type}-${id}`;
@@ -44,37 +45,20 @@ class PluginRegistryImpl {
     const key = this.sourceKey(plugin.type, plugin.id);
     const existingSource = this.sources.get(key);
 
-    if (existingSource === "builtin" && source !== "builtin") {
+    // Priority: local > npm > builtin
+    // If a higher-priority source already registered this plugin, skip.
+    const priority: Record<PluginSource, number> = { local: 2, npm: 1, builtin: 0 };
+    if (existingSource && priority[existingSource] > priority[source]) {
       return;
     }
 
-    this.sources.set(key, source);
-    switch (plugin.type) {
-      case "provider":
-        if (this.plugins.provider.has(plugin.id)) {
-          console.warn(`Plugin "${plugin.id}" already registered, overwriting`);
-        }
-        this.plugins.provider.set(plugin.id, plugin);
-        break;
-      case "agent":
-        if (this.plugins.agent.has(plugin.id)) {
-          console.warn(`Plugin "${plugin.id}" already registered, overwriting`);
-        }
-        this.plugins.agent.set(plugin.id, plugin);
-        break;
-      case "theme":
-        if (this.plugins.theme.has(plugin.id)) {
-          console.warn(`Plugin "${plugin.id}" already registered, overwriting`);
-        }
-        this.plugins.theme.set(plugin.id, plugin);
-        break;
-      case "notification":
-        if (this.plugins.notification.has(plugin.id)) {
-          console.warn(`Plugin "${plugin.id}" already registered, overwriting`);
-        }
-        this.plugins.notification.set(plugin.id, plugin);
-        break;
+    if (existingSource && existingSource !== source) {
+      console.info(`Plugin "${plugin.id}" overridden by ${source} (was ${existingSource})`);
     }
+
+    this.sources.set(key, source);
+    const map = this.plugins[plugin.type] as Map<string, AnyPlugin>;
+    map.set(plugin.id, plugin);
   }
 
   unregister(type: PluginType, id: string): boolean {
@@ -118,6 +102,10 @@ class PluginRegistryImpl {
     return this.sources.get(this.sourceKey(type, id));
   }
 
+  isOfficial(type: PluginType, id: string): boolean {
+    return this.officialIds.has(this.sourceKey(type, id));
+  }
+
   async loadBuiltinPlugins(): Promise<void> {
     const [providers, agents, themes, notifications] = await Promise.all([
       import("./providers/index.ts"),
@@ -127,19 +115,31 @@ class PluginRegistryImpl {
     ]);
 
     for (const plugin of Object.values(providers)) {
-      if (isProviderPlugin(plugin)) this.register(plugin, "builtin");
+      if (isProviderPlugin(plugin)) {
+        this.register(plugin, "builtin");
+        this.officialIds.add(this.sourceKey(plugin.type, plugin.id));
+      }
     }
 
     for (const plugin of Object.values(agents)) {
-      if (isAgentPlugin(plugin)) this.register(plugin, "builtin");
+      if (isAgentPlugin(plugin)) {
+        this.register(plugin, "builtin");
+        this.officialIds.add(this.sourceKey(plugin.type, plugin.id));
+      }
     }
 
     for (const plugin of Object.values(themes)) {
-      if (isThemePlugin(plugin)) this.register(plugin, "builtin");
+      if (isThemePlugin(plugin)) {
+        this.register(plugin, "builtin");
+        this.officialIds.add(this.sourceKey(plugin.type, plugin.id));
+      }
     }
 
     for (const plugin of Object.values(notifications)) {
-      if (isNotificationPlugin(plugin)) this.register(plugin, "builtin");
+      if (isNotificationPlugin(plugin)) {
+        this.register(plugin, "builtin");
+        this.officialIds.add(this.sourceKey(plugin.type, plugin.id));
+      }
     }
   }
 
@@ -148,13 +148,13 @@ class PluginRegistryImpl {
     const resolvedExtraPaths = extraPaths.map((p) => resolvePluginPath(p));
     const allPaths = [...discoveredPaths, ...resolvedExtraPaths];
 
-    for (const pluginPath of allPaths) {
-      const result = await loadLocalPlugin(pluginPath);
+    const results = await Promise.all(allPaths.map((p) => loadLocalPlugin(p)));
+    for (const [i, result] of results.entries()) {
       if (result.success && result.plugin) {
         this.register(result.plugin, "local");
         console.info(`Loaded local plugin: ${result.plugin.name} (${result.plugin.id})`);
       } else {
-        console.warn(`Failed to load plugin from ${pluginPath}: ${result.error}`);
+        console.warn(`Failed to load plugin from ${allPaths[i]}: ${result.error}`);
       }
     }
   }
@@ -171,9 +171,14 @@ class PluginRegistryImpl {
       }
     }
 
-    for (const packageName of packages) {
-      const resolvedPath = resolveNpmPluginPath(packageName);
-      const result = await loadNpmPlugin(packageName, resolvedPath);
+    const loadResults = await Promise.all(
+      packages.map(async (packageName) => {
+        const resolvedPath = resolveNpmPluginPath(packageName);
+        const result = await loadNpmPlugin(packageName, resolvedPath);
+        return { packageName, result };
+      }),
+    );
+    for (const { packageName, result } of loadResults) {
       if (result.success && result.plugin) {
         this.register(result.plugin, "npm");
         console.info(`Loaded npm plugin: ${result.plugin.name} (${packageName})`);

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/retention.ts

@@ -0,0 +1,146 @@
+/**
+ * Data retention policy — prevents unbounded database growth.
+ *
+ * Detailed snapshot data (agent_session_snapshots, agent_session_stream_snapshots,
+ * provider_snapshots) is pruned after a retention window. Aggregated data in
+ * usage_events, hourly_aggregates, and daily_aggregates is kept longer since
+ * those tables grow much more slowly.
+ */
+
+import { getDatabase, isDatabaseInitialized } from "./db.ts";
+
+/** Keep detailed snapshots for 7 days */
+const SNAPSHOT_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Keep provider snapshots for 7 days */
+const PROVIDER_SNAPSHOT_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Keep usage events for 90 days */
+const USAGE_EVENT_RETENTION_MS = 90 * 24 * 60 * 60 * 1000;
+
+/** Maximum rows to delete in a single batch (prevents long-running transactions) */
+const PRUNE_BATCH_SIZE = 10_000;
+
+export interface PruneResult {
+  agentSessionSnapshots: number;
+  providerSnapshots: number;
+  usageEvents: number;
+  durationMs: number;
+}
+
+/**
+ * Prune old data from the database. Deletes in batches to avoid
+ * holding a write lock for too long.
+ */
+export function pruneOldData(nowMs: number = Date.now()): PruneResult {
+  if (!isDatabaseInitialized()) {
+    return { agentSessionSnapshots: 0, providerSnapshots: 0, usageEvents: 0, durationMs: 0 };
+  }
+
+  const db = getDatabase();
+  const start = performance.now();
+
+  let agentSessionSnapshots = 0;
+  let providerSnapshots = 0;
+  let usageEvents = 0;
+
+  const snapshotCutoff = nowMs - SNAPSHOT_RETENTION_MS;
+  const providerCutoff = nowMs - PROVIDER_SNAPSHOT_RETENTION_MS;
+  const usageEventCutoff = nowMs - USAGE_EVENT_RETENTION_MS;
+
+  // Prune agent_session_snapshots in batches.
+  // CASCADE delete handles agent_session_stream_snapshots automatically.
+  {
+    const stmt = db.prepare(`
+      DELETE FROM agent_session_snapshots
+      WHERE id IN (
+        SELECT id FROM agent_session_snapshots
+        WHERE timestamp < ?
+        LIMIT ?
+      )
+    `);
+
+    let deleted: number;
+    do {
+      const result = stmt.run(snapshotCutoff, PRUNE_BATCH_SIZE);
+      deleted = result.changes;
+      agentSessionSnapshots += deleted;
+    } while (deleted === PRUNE_BATCH_SIZE);
+  }
+
+  // Prune old provider_snapshots in batches
+  {
+    const stmt = db.prepare(`
+      DELETE FROM provider_snapshots
+      WHERE id IN (
+        SELECT id FROM provider_snapshots
+        WHERE timestamp < ?
+        LIMIT ?
+      )
+    `);
+
+    let deleted: number;
+    do {
+      const result = stmt.run(providerCutoff, PRUNE_BATCH_SIZE);
+      deleted = result.changes;
+      providerSnapshots += deleted;
+    } while (deleted === PRUNE_BATCH_SIZE);
+  }
+
+  // Prune old usage_events in batches
+  {
+    const stmt = db.prepare(`
+      DELETE FROM usage_events
+      WHERE id IN (
+        SELECT id FROM usage_events
+        WHERE timestamp < ?
+        LIMIT ?
+      )
+    `);
+
+    let deleted: number;
+    do {
+      const result = stmt.run(usageEventCutoff, PRUNE_BATCH_SIZE);
+      deleted = result.changes;
+      usageEvents += deleted;
+    } while (deleted === PRUNE_BATCH_SIZE);
+  }
+
+  const durationMs = Math.round(performance.now() - start);
+
+  return { agentSessionSnapshots, providerSnapshots, usageEvents, durationMs };
+}
+
+/**
+ * Run incremental auto_vacuum if supported (WAL mode).
+ * This reclaims free pages without blocking readers.
+ */
+export function incrementalVacuum(pages = 1000): void {
+  if (!isDatabaseInitialized()) return;
+
+  const db = getDatabase();
+  try {
+    db.exec(`PRAGMA incremental_vacuum(${pages})`);
+  } catch {
+    // Not all builds support incremental vacuum — silently skip
+  }
+}
+
+/**
+ * Get the database file size in bytes. Returns 0 if unable to determine.
+ */
+export function getDatabaseSizeBytes(): number {
+  if (!isDatabaseInitialized()) return 0;
+
+  const db = getDatabase();
+  try {
+    const row = db.prepare("PRAGMA page_count").get() as { page_count: number } | null;
+    const sizeRow = db.prepare("PRAGMA page_size").get() as { page_size: number } | null;
+    if (row && sizeRow) {
+      return row.page_count * sizeRow.page_size;
+    }
+  } catch {
+    // ignore
+  }
+  return 0;
+}