@tokentop/ttop 0.2.2

package/src/storage/repos/usageEvents.ts

@@ -0,0 +1,334 @@
+import { getDatabase } from '../db.ts';
+import type { UsageEventInsert, TimeSeriesPoint, TimeSeriesFilters } from '../types.ts';
+
+const INSERT_SQL = `
+  INSERT INTO usage_events (
+    timestamp, source, provider, model, agent_id, session_id, project_path,
+    input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,
+    cost_usd, request_count, pricing_source
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+`;
+
+export function insertUsageEvent(event: UsageEventInsert): number {
+  const db = getDatabase();
+  const stmt = db.prepare(INSERT_SQL);
+
+  const result = stmt.run(
+    event.timestamp,
+    event.source,
+    event.provider ?? null,
+    event.model ?? null,
+    event.agentId ?? null,
+    event.sessionId ?? null,
+    event.projectPath ?? null,
+    event.inputTokens,
+    event.outputTokens,
+    event.cacheReadTokens,
+    event.cacheWriteTokens,
+    event.costUsd,
+    event.requestCount,
+    event.pricingSource ?? null
+  );
+
+  return Number(result.lastInsertRowid);
+}
+
+export function insertUsageEventBatch(events: UsageEventInsert[]): void {
+  if (events.length === 0) return;
+
+  const db = getDatabase();
+  const stmt = db.prepare(INSERT_SQL);
+
+  const insertMany = db.transaction((items: UsageEventInsert[]) => {
+    for (const e of items) {
+      stmt.run(
+        e.timestamp,
+        e.source,
+        e.provider ?? null,
+        e.model ?? null,
+        e.agentId ?? null,
+        e.sessionId ?? null,
+        e.projectPath ?? null,
+        e.inputTokens,
+        e.outputTokens,
+        e.cacheReadTokens,
+        e.cacheWriteTokens,
+        e.costUsd,
+        e.requestCount,
+        e.pricingSource ?? null
+      );
+    }
+  });
+
+  insertMany(events);
+}
+
+export function queryUsageTimeSeries(
+  startMs: number,
+  endMs: number,
+  bucketMs: number,
+  filters: TimeSeriesFilters = {}
+): TimeSeriesPoint[] {
+  const db = getDatabase();
+
+  const conditions: string[] = ['timestamp >= ?', 'timestamp <= ?'];
+  const params: (string | number)[] = [startMs, endMs];
+
+  if (filters.provider) {
+    conditions.push('provider = ?');
+    params.push(filters.provider);
+  }
+  if (filters.model) {
+    conditions.push('model = ?');
+    params.push(filters.model);
+  }
+  if (filters.agentId) {
+    conditions.push('agent_id = ?');
+    params.push(filters.agentId);
+  }
+  if (filters.sessionId) {
+    conditions.push('session_id = ?');
+    params.push(filters.sessionId);
+  }
+  if (filters.projectPath) {
+    conditions.push('project_path = ?');
+    params.push(filters.projectPath);
+  }
+
+  const sql = `
+    SELECT
+      (timestamp / ${bucketMs} * ${bucketMs}) AS bucket_start,
+      COALESCE(SUM(input_tokens + output_tokens), 0) AS tokens,
+      COALESCE(SUM(cost_usd), 0) AS cost_usd,
+      COALESCE(SUM(request_count), 0) AS request_count
+    FROM usage_events
+    WHERE ${conditions.join(' AND ')}
+    GROUP BY bucket_start
+    ORDER BY bucket_start ASC
+  `;
+
+  const rows = db.prepare(sql).all(...params) as Array<{
+    bucket_start: number;
+    tokens: number;
+    cost_usd: number;
+    request_count: number;
+  }>;
+
+  return rows.map(r => ({
+    bucketStart: r.bucket_start,
+    tokens: r.tokens,
+    costUsd: r.cost_usd,
+    requestCount: r.request_count,
+  }));
+}
+
+export function calculateBurnRate(windowMs: number, nowMs = Date.now()): { costPerHour: number; tokensPerMinute: number } {
+  const db = getDatabase();
+  const startMs = nowMs - windowMs;
+
+  const row = db.prepare(`
+    SELECT
+      COALESCE(SUM(cost_usd), 0) AS cost,
+      COALESCE(SUM(input_tokens + output_tokens), 0) AS tokens
+    FROM usage_events
+    WHERE timestamp >= ? AND timestamp <= ?
+  `).get(startMs, nowMs) as { cost: number; tokens: number };
+
+  const hours = windowMs / (1000 * 60 * 60);
+  const minutes = windowMs / (1000 * 60);
+
+  return {
+    costPerHour: hours > 0 ? row.cost / hours : 0,
+    tokensPerMinute: minutes > 0 ? row.tokens / minutes : 0,
+  };
+}
+
+export function getTotalUsageInWindow(startMs: number, endMs: number): {
+  inputTokens: number;
+  outputTokens: number;
+  costUsd: number;
+  requestCount: number;
+} {
+  const db = getDatabase();
+
+  const row = db.prepare(`
+    SELECT
+      COALESCE(SUM(input_tokens), 0) AS input_tokens,
+      COALESCE(SUM(output_tokens), 0) AS output_tokens,
+      COALESCE(SUM(cost_usd), 0) AS cost_usd,
+      COALESCE(SUM(request_count), 0) AS request_count
+    FROM usage_events
+    WHERE timestamp >= ? AND timestamp <= ?
+  `).get(startMs, endMs) as {
+    input_tokens: number;
+    output_tokens: number;
+    cost_usd: number;
+    request_count: number;
+  };
+
+  return {
+    inputTokens: row.input_tokens,
+    outputTokens: row.output_tokens,
+    costUsd: row.cost_usd,
+    requestCount: row.request_count,
+  };
+}
+
+export interface SessionActivityPoint {
+  timestamp: number;
+  tokens: number;
+}
+
+export interface ProviderDailyCost {
+  provider: string;
+  bucketStart: number;
+  costUsd: number;
+  tokens: number;
+  requestCount: number;
+}
+
+export function queryProviderDailyCosts(
+  startMs: number,
+  endMs: number,
+  bucketMs: number
+): ProviderDailyCost[] {
+  const db = getDatabase();
+
+  const sql = `
+    SELECT
+      provider,
+      (timestamp / ${bucketMs} * ${bucketMs}) AS bucket_start,
+      COALESCE(SUM(cost_usd), 0) AS cost_usd,
+      COALESCE(SUM(input_tokens + output_tokens), 0) AS tokens,
+      COALESCE(SUM(request_count), 0) AS request_count
+    FROM usage_events
+    WHERE timestamp >= ? AND timestamp <= ?
+      AND provider IS NOT NULL
+    GROUP BY provider, bucket_start
+    ORDER BY provider, bucket_start ASC
+  `;
+
+  const rows = db.prepare(sql).all(startMs, endMs) as Array<{
+    provider: string;
+    bucket_start: number;
+    cost_usd: number;
+    tokens: number;
+    request_count: number;
+  }>;
+
+  return rows.map(r => ({
+    provider: r.provider,
+    bucketStart: r.bucket_start,
+    costUsd: r.cost_usd,
+    tokens: r.tokens,
+    requestCount: r.request_count,
+  }));
+}
+
+export interface ModelDailyCost {
+  model: string;
+  bucketStart: number;
+  costUsd: number;
+  tokens: number;
+  requestCount: number;
+}
+
+export function queryModelDailyCosts(
+  startMs: number,
+  endMs: number,
+  bucketMs: number
+): ModelDailyCost[] {
+  const db = getDatabase();
+
+  const sql = `
+    SELECT
+      model,
+      (timestamp / ${bucketMs} * ${bucketMs}) AS bucket_start,
+      COALESCE(SUM(cost_usd), 0) AS cost_usd,
+      COALESCE(SUM(input_tokens + output_tokens), 0) AS tokens,
+      COALESCE(SUM(request_count), 0) AS request_count
+    FROM usage_events
+    WHERE timestamp >= ? AND timestamp <= ?
+      AND model IS NOT NULL
+    GROUP BY model, bucket_start
+    ORDER BY model, bucket_start ASC
+  `;
+
+  const rows = db.prepare(sql).all(startMs, endMs) as Array<{
+    model: string;
+    bucket_start: number;
+    cost_usd: number;
+    tokens: number;
+    request_count: number;
+  }>;
+
+  return rows.map(r => ({
+    model: r.model,
+    bucketStart: r.bucket_start,
+    costUsd: r.cost_usd,
+    tokens: r.tokens,
+    requestCount: r.request_count,
+  }));
+}
+
+export interface ProjectDailyCost {
+  projectPath: string;
+  bucketStart: number;
+  costUsd: number;
+  tokens: number;
+  requestCount: number;
+}
+
+export function queryProjectDailyCosts(
+  startMs: number,
+  endMs: number,
+  bucketMs: number
+): ProjectDailyCost[] {
+  const db = getDatabase();
+
+  const sql = `
+    SELECT
+      project_path,
+      (timestamp / ${bucketMs} * ${bucketMs}) AS bucket_start,
+      COALESCE(SUM(cost_usd), 0) AS cost_usd,
+      COALESCE(SUM(input_tokens + output_tokens), 0) AS tokens,
+      COALESCE(SUM(request_count), 0) AS request_count
+    FROM usage_events
+    WHERE timestamp >= ? AND timestamp <= ?
+      AND project_path IS NOT NULL
+    GROUP BY project_path, bucket_start
+    ORDER BY project_path, bucket_start ASC
+  `;
+
+  const rows = db.prepare(sql).all(startMs, endMs) as Array<{
+    project_path: string;
+    bucket_start: number;
+    cost_usd: number;
+    tokens: number;
+    request_count: number;
+  }>;
+
+  return rows.map(r => ({
+    projectPath: r.project_path,
+    bucketStart: r.bucket_start,
+    costUsd: r.cost_usd,
+    tokens: r.tokens,
+    requestCount: r.request_count,
+  }));
+}
+
+export function getSessionActivityTimeline(sessionId: string): SessionActivityPoint[] {
+  const db = getDatabase();
+
+  const rows = db.prepare(`
+    SELECT timestamp, (input_tokens + output_tokens) AS tokens
+    FROM usage_events
+    WHERE session_id = ?
+    ORDER BY timestamp ASC
+  `).all(sessionId) as Array<{ timestamp: number; tokens: number }>;
+
+  return rows.map(r => ({
+    timestamp: r.timestamp,
+    tokens: r.tokens,
+  }));
+}

package/src/storage/types.ts

@@ -0,0 +1,288 @@
+/**
+ * TypeScript interfaces for SQLite storage layer.
+ * Based on SQLITE_ARCHITECTURE.md specification.
+ */
+
+// ============================================================================
+// Enums & Literal Types
+// ============================================================================
+
+export type UsageEventSource = 'agent' | 'provider';
+export type SessionStatus = 'active' | 'idle';
+export type CostSource = 'api' | 'estimated';
+export type PricingSource = 'models.dev' | 'fallback' | 'unknown';
+
+// ============================================================================
+// App Runs Table
+// ============================================================================
+
+export interface AppRunRow {
+  id?: number;
+  startedAt: number; // ms since epoch
+  endedAt?: number | null;
+  appVersion?: string | null;
+  refreshIntervalMs?: number | null;
+  pid?: number | null;
+  hostname?: string | null;
+}
+
+// ============================================================================
+// Provider Snapshots Table
+// ============================================================================
+
+export interface ProviderSnapshotRow {
+  id?: number;
+  timestamp: number; // ms since epoch
+  provider: string;
+  usedPercent?: number | null;
+  limitReached: boolean;
+  resetsAt?: number | null; // ms since epoch
+  tokensInput?: number | null;
+  tokensOutput?: number | null;
+  costUsd?: number | null;
+  costSource?: CostSource | null;
+  rawJson?: string | null;
+}
+
+export interface ProviderSnapshotInsert {
+  timestamp: number;
+  provider: string;
+  usedPercent?: number | null;
+  limitReached?: boolean;
+  resetsAt?: number | null;
+  tokensInput?: number | null;
+  tokensOutput?: number | null;
+  costUsd?: number | null;
+  costSource?: CostSource | null;
+  rawJson?: string | null;
+}
+
+// ============================================================================
+// Agent Sessions Table (Logical Dimension)
+// ============================================================================
+
+export interface AgentSessionDim {
+  id?: number;
+  agentId: string;
+  sessionId: string;
+  projectPath?: string | null;
+  startedAt?: number | null;
+  firstSeenAt: number;
+  lastSeenAt: number;
+}
+
+export interface AgentSessionUpsert {
+  agentId: string;
+  sessionId: string;
+  projectPath?: string | null;
+  startedAt?: number | null;
+  firstSeenAt?: number;
+  lastSeenAt: number;
+}
+
+// ============================================================================
+// Agent Session Snapshots Table
+// ============================================================================
+
+export interface AgentSessionSnapshotRow {
+  id?: number;
+  timestamp: number;
+  agentSessionId: number;
+  lastActivityAt?: number | null;
+  status?: SessionStatus | null;
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  totalCacheReadTokens: number;
+  totalCacheWriteTokens: number;
+  totalCostUsd: number;
+  requestCount: number;
+}
+
+export interface AgentSessionSnapshotInsert {
+  timestamp: number;
+  agentSessionId: number;
+  lastActivityAt?: number | null;
+  status?: SessionStatus | null;
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  totalCacheReadTokens: number;
+  totalCacheWriteTokens: number;
+  totalCostUsd: number;
+  requestCount: number;
+}
+
+// ============================================================================
+// Agent Session Stream Snapshots Table
+// ============================================================================
+
+export interface AgentSessionStreamSnapshotRow {
+  agentSessionSnapshotId: number;
+  provider: string;
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  costUsd: number;
+  requestCount: number;
+  pricingSource?: PricingSource | null;
+}
+
+// ============================================================================
+// Usage Events Table (Append-Only Deltas)
+// ============================================================================
+
+export interface UsageEventRow {
+  id?: number;
+  timestamp: number;
+  source: UsageEventSource;
+  provider?: string | null;
+  model?: string | null;
+  agentId?: string | null;
+  sessionId?: string | null;
+  projectPath?: string | null;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  costUsd: number;
+  requestCount: number;
+  pricingSource?: PricingSource | null;
+}
+
+export interface UsageEventInsert {
+  timestamp: number;
+  source: UsageEventSource;
+  provider?: string | null;
+  model?: string | null;
+  agentId?: string | null;
+  sessionId?: string | null;
+  projectPath?: string | null;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  costUsd: number;
+  requestCount: number;
+  pricingSource?: PricingSource | null;
+}
+
+// ============================================================================
+// Hourly Aggregates Table
+// ============================================================================
+
+export interface HourlyAggregateRow {
+  bucketStart: number; // ms since epoch, truncated to hour
+  provider?: string | null;
+  model?: string | null;
+  agentId?: string | null;
+  projectPath?: string | null;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  costUsd: number;
+  requestCount: number;
+}
+
+// ============================================================================
+// Daily Aggregates Table
+// ============================================================================
+
+export interface DailyAggregateRow {
+  date: string; // 'YYYY-MM-DD'
+  provider?: string | null;
+  model?: string | null;
+  agentId?: string | null;
+  projectPath?: string | null;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  costUsd: number;
+  requestCount: number;
+}
+
+// ============================================================================
+// Query Types
+// ============================================================================
+
+export interface TimeSeriesPoint {
+  bucketStart: number;
+  tokens: number;
+  costUsd: number;
+  requestCount: number;
+}
+
+export interface TimeSeriesFilters {
+  provider?: string;
+  model?: string;
+  agentId?: string;
+  sessionId?: string;
+  projectPath?: string;
+}
+
+export interface UsageQueryOptions {
+  startTime?: number;
+  endTime?: number;
+  provider?: string;
+  model?: string;
+  agentId?: string;
+  sessionId?: string;
+  projectPath?: string;
+  limit?: number;
+  offset?: number;
+}
+
+// ============================================================================
+// Delta Computation
+// ============================================================================
+
+export interface StreamTotals {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  costUsd: number;
+  requestCount: number;
+}
+
+/**
+ * Computes the delta between two stream totals.
+ * Returns null if delta is all zeros (no change worth recording).
+ */
+export function computeStreamDelta(
+  current: StreamTotals,
+  previous: StreamTotals | undefined
+): StreamTotals | null {
+  if (!previous) {
+    // First observation - treat as a delta from zero
+    const hasNonZero =
+      current.inputTokens ||
+      current.outputTokens ||
+      current.cacheReadTokens ||
+      current.cacheWriteTokens ||
+      current.costUsd ||
+      current.requestCount;
+    return hasNonZero ? current : null;
+  }
+
+  const delta: StreamTotals = {
+    inputTokens: Math.max(0, current.inputTokens - previous.inputTokens),
+    outputTokens: Math.max(0, current.outputTokens - previous.outputTokens),
+    cacheReadTokens: Math.max(0, current.cacheReadTokens - previous.cacheReadTokens),
+    cacheWriteTokens: Math.max(0, current.cacheWriteTokens - previous.cacheWriteTokens),
+    costUsd: Math.max(0, current.costUsd - previous.costUsd),
+    requestCount: Math.max(0, current.requestCount - previous.requestCount),
+  };
+
+  const hasNonZero =
+    delta.inputTokens ||
+    delta.outputTokens ||
+    delta.cacheReadTokens ||
+    delta.cacheWriteTokens ||
+    delta.costUsd ||
+    delta.requestCount;
+
+  return hasNonZero ? delta : null;
+}