agentboss 0.1.0

package/server/db/queries.js

@@ -0,0 +1,1051 @@
+/**
+ * Database query helpers for Agent Boss (boss.db)
+ * Wraps common operations for the sql.js-backed SQLite database.
+ *
+ * sql.js API notes:
+ * - db.run(sql, params)       – execute with optional params array
+ * - db.exec(sql)              – execute, returns [{columns, values}]
+ * - db.prepare(sql)           – returns statement; use .bind().step() / .getAsObject()
+ * - Positional ? placeholders; params passed as arrays
+ *
+ * @author Felix
+ */
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a SELECT and return all matching rows as plain objects.
+ * @param {Object} db  sql.js Database instance
+ * @param {string} sql SQL query
+ * @param {Array}  params Positional parameters
+ * @returns {Object[]}
+ */
+function queryAll(db, sql, params = []) {
+  const stmt = db.prepare(sql);
+  if (params.length) stmt.bind(params);
+  const results = [];
+  while (stmt.step()) {
+    results.push(stmt.getAsObject());
+  }
+  stmt.free();
+  return results;
+}
+
+/**
+ * Execute a SELECT and return the first matching row, or null.
+ * @param {Object} db  sql.js Database instance
+ * @param {string} sql SQL query
+ * @param {Array}  params Positional parameters
+ * @returns {Object|null}
+ */
+function queryOne(db, sql, params = []) {
+  const results = queryAll(db, sql, params);
+  return results[0] || null;
+}
+
+// ---------------------------------------------------------------------------
+// Session queries
+// ---------------------------------------------------------------------------
+
+/**
+ * Insert or replace a unified session row.
+ * @param {Object} db
+ * @param {Object} session
+ */
+function upsertSession(db, session) {
+  const sql = `INSERT OR REPLACE INTO unified_session (
+    id, source, date, started_at, ended_at, duration_minutes, active_minutes,
+    message_count, tokens_input, tokens_output, tokens_reasoning,
+    tokens_cache_read, tokens_cache_write, cost_usd, project, title, model,
+    error_count, tool_call_count, summary_additions, summary_deletions,
+    summary_files, reverted, time_compacting,
+    parent_session_id, agent_type
+  ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`;
+
+  db.run(sql, [
+    session.id,
+    session.source,
+    session.date,
+    session.started_at,
+    session.ended_at || null,
+    session.duration_minutes || 0,
+    session.active_minutes ?? null,
+    session.message_count || 0,
+    session.tokens_input || 0,
+    session.tokens_output || 0,
+    session.tokens_reasoning || 0,
+    session.tokens_cache_read || 0,
+    session.tokens_cache_write || 0,
+    session.cost_usd || 0,
+    session.project || null,
+    session.title || null,
+    session.model || null,
+    session.error_count || 0,
+    session.tool_call_count || 0,
+    session.summary_additions || 0,
+    session.summary_deletions || 0,
+    session.summary_files || 0,
+    session.reverted || 0,
+    session.time_compacting || 0,
+    session.parent_session_id || null,
+    session.agent_type || null,
+  ]);
+}
+
+/**
+ * Get sessions for a specific date, optionally filtered by source.
+ * @param {Object} db
+ * @param {string} date  YYYY-MM-DD
+ * @param {string} [source]
+ * @returns {Object[]}
+ */
+function getSessionsByDate(db, date, source) {
+  if (source) {
+    return queryAll(
+      db,
+      'SELECT * FROM unified_session WHERE date = ? AND source = ? ORDER BY started_at',
+      [date, source]
+    );
+  }
+  return queryAll(
+    db,
+    'SELECT * FROM unified_session WHERE date = ? ORDER BY started_at',
+    [date]
+  );
+}
+
+/**
+ * Get a single session by ID.
+ * @param {Object} db
+ * @param {string} id
+ * @returns {Object|null}
+ */
+function getSessionById(db, id) {
+  return queryOne(db, 'SELECT * FROM unified_session WHERE id = ?', [id]);
+}
+
+/**
+ * Get sessions in a date range with optional source filter and pagination.
+ * @param {Object} db
+ * @param {string} fromDate  YYYY-MM-DD inclusive
+ * @param {string} toDate    YYYY-MM-DD inclusive
+ * @param {string} [source]
+ * @param {number} [limit=100]
+ * @param {number} [offset=0]
+ * @returns {Object[]}
+ */
+function getSessionsByDateRange(db, fromDate, toDate, source, limit = 100, offset = 0) {
+  if (source) {
+    return queryAll(
+      db,
+      `SELECT * FROM unified_session
+       WHERE date >= ? AND date <= ? AND source = ?
+       ORDER BY started_at DESC
+       LIMIT ? OFFSET ?`,
+      [fromDate, toDate, source, limit, offset]
+    );
+  }
+  return queryAll(
+    db,
+    `SELECT * FROM unified_session
+     WHERE date >= ? AND date <= ?
+     ORDER BY started_at DESC
+     LIMIT ? OFFSET ?`,
+    [fromDate, toDate, limit, offset]
+  );
+}
+
+/**
+ * Count sessions in a date range (for pagination).
+ * @param {Object} db
+ * @param {string} fromDate
+ * @param {string} toDate
+ * @param {string} [source]
+ * @returns {number}
+ */
+function countSessionsByDateRange(db, fromDate, toDate, source) {
+  const row = source
+    ? queryOne(
+        db,
+        'SELECT COUNT(*) AS cnt FROM unified_session WHERE date >= ? AND date <= ? AND source = ?',
+        [fromDate, toDate, source]
+      )
+    : queryOne(
+        db,
+        'SELECT COUNT(*) AS cnt FROM unified_session WHERE date >= ? AND date <= ?',
+        [fromDate, toDate]
+      );
+  return row ? row.cnt : 0;
+}
+
+// ---------------------------------------------------------------------------
+// Message queries
+// ---------------------------------------------------------------------------
+
+/**
+ * Get all messages for a session ordered by timestamp.
+ * @param {Object} db
+ * @param {string} sessionId
+ * @returns {Object[]}
+ */
+function getMessagesBySession(db, sessionId) {
+  return queryAll(
+    db,
+    'SELECT * FROM unified_message WHERE session_id = ? ORDER BY timestamp',
+    [sessionId]
+  );
+}
+
+/**
+ * Insert multiple messages efficiently inside a transaction.
+ * @param {Object} db
+ * @param {Object[]} messages
+ */
+function bulkInsertMessages(db, messages) {
+  if (!messages.length) return;
+
+  const sql = `INSERT INTO unified_message (
+    id, session_id, source, role, timestamp,
+    tokens_input, tokens_output, tokens_reasoning,
+    cost_usd, content_length, is_error, model_id, text
+  ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)`;
+
+  db.run('BEGIN TRANSACTION');
+  try {
+    for (const m of messages) {
+      // content_length: prefer explicit value, otherwise derive from text
+      const len = m.content_length || (m.text ? m.text.length : 0);
+      db.run(sql, [
+        m.id,
+        m.session_id,
+        m.source,
+        m.role,
+        m.timestamp,
+        m.tokens_input || 0,
+        m.tokens_output || 0,
+        m.tokens_reasoning || 0,
+        m.cost_usd || 0,
+        len,
+        m.is_error || 0,
+        m.model_id || null,
+        m.text || null,
+      ]);
+    }
+    db.run('COMMIT');
+  } catch (err) {
+    db.run('ROLLBACK');
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Part queries
+// ---------------------------------------------------------------------------
+
+/**
+ * Get all parts for a session.
+ * @param {Object} db
+ * @param {string} sessionId
+ * @returns {Object[]}
+ */
+function getPartsBySession(db, sessionId) {
+  return queryAll(
+    db,
+    'SELECT * FROM unified_part WHERE session_id = ? ORDER BY timestamp',
+    [sessionId]
+  );
+}
+
+/**
+ * Insert multiple parts efficiently inside a transaction.
+ * @param {Object} db
+ * @param {Object[]} parts
+ */
+function bulkInsertParts(db, parts) {
+  if (!parts.length) return;
+
+  const sql = `INSERT INTO unified_part (
+    id, message_id, session_id, source, type, timestamp
+  ) VALUES (?,?,?,?,?,?)`;
+
+  db.run('BEGIN TRANSACTION');
+  try {
+    for (const p of parts) {
+      db.run(sql, [
+        p.id,
+        p.message_id,
+        p.session_id,
+        p.source,
+        p.type,
+        p.timestamp,
+      ]);
+    }
+    db.run('COMMIT');
+  } catch (err) {
+    db.run('ROLLBACK');
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tool call queries
+// ---------------------------------------------------------------------------
+
+/**
+ * Get all tool calls for a session ordered by timestamp.
+ * @param {Object} db
+ * @param {string} sessionId
+ * @returns {Object[]}
+ */
+function getToolCallsBySession(db, sessionId) {
+  return queryAll(
+    db,
+    'SELECT * FROM unified_tool_call WHERE session_id = ? ORDER BY timestamp',
+    [sessionId]
+  );
+}
+
+/**
+ * Insert multiple tool calls efficiently inside a transaction.
+ * @param {Object} db
+ * @param {Object[]} toolCalls
+ */
+function bulkInsertToolCalls(db, toolCalls) {
+  if (!toolCalls.length) return;
+
+  const sql = `INSERT INTO unified_tool_call (
+    id, part_id, session_id, source, tool_name, timestamp,
+    status, error_message, target_file
+  ) VALUES (?,?,?,?,?,?,?,?,?)`;
+
+  db.run('BEGIN TRANSACTION');
+  try {
+    for (const tc of toolCalls) {
+      db.run(sql, [
+        tc.id,
+        tc.part_id,
+        tc.session_id,
+        tc.source,
+        tc.tool_name,
+        tc.timestamp,
+        tc.status || null,
+        tc.error_message || null,
+        tc.target_file || null,
+      ]);
+    }
+    db.run('COMMIT');
+  } catch (err) {
+    db.run('ROLLBACK');
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Analysis queries
+// ---------------------------------------------------------------------------
+
+/**
+ * Insert or replace a session analysis row.
+ * @param {Object} db
+ * @param {Object} analysis
+ */
+function upsertSessionAnalysis(db, analysis) {
+  // v2 columns (H1..O1, difficulty, judge).  The legacy v1 columns
+  // (score_a..score_e, sub_scores, highlight_dims) still exist on the
+  // table for back-compat with older boss.db files but are no longer
+  // written; they'll just remain at their historical values (NULL on
+  // freshly-analysed rows).
+  const sql = `INSERT OR REPLACE INTO session_analysis (
+    session_id, source, analyzed_at, status,
+    difficulty,
+    score_h1, level_h1,
+    score_h2, level_h2,
+    score_h3, level_h3,
+    score_e1, level_e1,
+    score_e2, level_e2,
+    score_o1, level_o1,
+    sub_scores_v2, llm_judge_v2, judge_source
+  ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`;
+
+  db.run(sql, [
+    analysis.session_id,
+    analysis.source || null,
+    analysis.analyzed_at || null,
+    analysis.status || 'pending',
+    analysis.difficulty ?? null,
+    analysis.score_h1 ?? null, analysis.level_h1 ?? null,
+    analysis.score_h2 ?? null, analysis.level_h2 ?? null,
+    analysis.score_h3 ?? null, analysis.level_h3 ?? null,
+    analysis.score_e1 ?? null, analysis.level_e1 ?? null,
+    analysis.score_e2 ?? null, analysis.level_e2 ?? null,
+    analysis.score_o1 ?? null, analysis.level_o1 ?? null,
+    analysis.sub_scores_v2 || null,
+    analysis.llm_judge_v2 || null,
+    analysis.judge_source || null,
+  ]);
+}
+
+/**
+ * Get the analysis row for a session.
+ * @param {Object} db
+ * @param {string} sessionId
+ * @returns {Object|null}
+ */
+function getAnalysisBySession(db, sessionId) {
+  return queryOne(
+    db,
+    'SELECT * FROM session_analysis WHERE session_id = ?',
+    [sessionId]
+  );
+}
+
+/**
+ * Get sessions that need (re-)analysis for a given date.
+ * Picks sessions that have no analysis row, are 'pending', or whose
+ * data grew since the last pass (ended_at newer than analyzed_at —
+ * both ISO-8601 UTC, so string comparison is safe).  The last clause
+ * also retries 'error' rows once the session has new data.
+ * @param {Object} db
+ * @param {string} date  YYYY-MM-DD
+ * @returns {Object[]}
+ */
+function getUnanalyzedSessions(db, date) {
+  return queryAll(
+    db,
+    `SELECT s.* FROM unified_session s
+     LEFT JOIN session_analysis sa ON s.id = sa.session_id
+     WHERE s.date = ? AND (
+       sa.status IS NULL OR sa.status = 'pending'
+       OR (sa.analyzed_at IS NOT NULL AND s.ended_at > sa.analyzed_at)
+     )
+     ORDER BY s.started_at`,
+    [date]
+  );
+}
+
+/**
+ * Insert or replace a daily summary row.
+ * @param {Object} db
+ * @param {Object} summary
+ */
+function upsertDailySummary(db, summary) {
+  const sql = `INSERT OR REPLACE INTO daily_summary (
+    id, date, source, session_count, message_count, tool_call_count,
+    tokens_input, tokens_output, tokens_reasoning,
+    tokens_cache_read, tokens_cache_write, cost_usd,
+    first_activity_at, last_activity_at, active_minutes,
+    peak_hour, error_count, revert_count, additions, deletions
+  ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`;
+
+  db.run(sql, [
+    summary.id,
+    summary.date,
+    summary.source,
+    summary.session_count || 0,
+    summary.message_count || 0,
+    summary.tool_call_count || 0,
+    summary.tokens_input || 0,
+    summary.tokens_output || 0,
+    summary.tokens_reasoning || 0,
+    summary.tokens_cache_read || 0,
+    summary.tokens_cache_write || 0,
+    summary.cost_usd || 0,
+    summary.first_activity_at || null,
+    summary.last_activity_at || null,
+    summary.active_minutes || 0,
+    summary.peak_hour ?? null,
+    summary.error_count || 0,
+    summary.revert_count || 0,
+    summary.additions || 0,
+    summary.deletions || 0,
+  ]);
+}
+
+/**
+ * Get daily summary for a specific date and source.
+ * @param {Object} db
+ * @param {string} date
+ * @param {string} [source]
+ * @returns {Object|null}
+ */
+function getDailySummary(db, date, source) {
+  // Default to the 'all' rollup row to keep parity with getDailySummaries
+  // and prevent double-counting across sources.
+  const effectiveSource = source || 'all';
+  if (effectiveSource) {
+    return queryOne(
+      db,
+      'SELECT * FROM daily_summary WHERE date = ? AND source = ?',
+      [date, effectiveSource]
+    );
+  }
+  return queryOne(
+    db,
+    'SELECT * FROM daily_summary WHERE date = ?',
+    [date]
+  );
+}
+
+/**
+ * Get daily summaries in a date range.
+ * @param {Object} db
+ * @param {string} fromDate
+ * @param {string} toDate
+ * @param {string} [source]
+ * @returns {Object[]}
+ */
+function getDailySummaries(db, fromDate, toDate, source) {
+  // When no source is specified, return the cross-source rollup ('all') to
+  // avoid double-counting (one row per source PLUS one 'all' row are written
+  // per date by the daily aggregator).
+  const effectiveSource = source || 'all';
+  return queryAll(
+    db,
+    'SELECT * FROM daily_summary WHERE date >= ? AND date <= ? AND source = ? ORDER BY date',
+    [fromDate, toDate, effectiveSource]
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Hourly activity queries
+// ---------------------------------------------------------------------------
+
+/**
+ * Insert or replace an hourly activity row.
+ * @param {Object} db
+ * @param {Object} activity
+ */
+function upsertHourlyActivity(db, activity) {
+  const sql = `INSERT OR REPLACE INTO hourly_activity (
+    date, hour, source,
+    message_count, session_count, error_count, tool_call_count
+  ) VALUES (?,?,?,?,?,?,?)`;
+
+  db.run(sql, [
+    activity.date,
+    activity.hour,
+    activity.source,
+    activity.message_count || 0,
+    activity.session_count || 0,
+    activity.error_count || 0,
+    activity.tool_call_count || 0,
+  ]);
+}
+
+/**
+ * Get hourly activity rows for a date, optionally filtered by source.
+ * @param {Object} db
+ * @param {string} date
+ * @param {string} [source]
+ * @returns {Object[]}
+ */
+function getHourlyActivity(db, date, source) {
+  if (source) {
+    return queryAll(
+      db,
+      'SELECT * FROM hourly_activity WHERE date = ? AND source = ? ORDER BY hour',
+      [date, source]
+    );
+  }
+  return queryAll(
+    db,
+    'SELECT * FROM hourly_activity WHERE date = ? ORDER BY hour',
+    [date]
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Settings queries
+// ---------------------------------------------------------------------------
+
+/**
+ * Get a single setting value by key.
+ * @param {Object} db
+ * @param {string} key
+ * @returns {string|null}
+ */
+function getSetting(db, key) {
+  const row = queryOne(db, 'SELECT value FROM user_settings WHERE key = ?', [key]);
+  return row ? row.value : null;
+}
+
+/**
+ * Set a setting value (insert or update).
+ * @param {Object} db
+ * @param {string} key
+ * @param {string} value
+ */
+function setSetting(db, key, value) {
+  db.run(
+    'INSERT OR REPLACE INTO user_settings (key, value) VALUES (?, ?)',
+    [key, value]
+  );
+}
+
+/**
+ * Get all settings as a plain object { key: value }.
+ * @param {Object} db
+ * @returns {Object}
+ */
+function getAllSettings(db) {
+  const rows = queryAll(db, 'SELECT key, value FROM user_settings');
+  const settings = {};
+  for (const row of rows) {
+    settings[row.key] = row.value;
+  }
+  return settings;
+}
+
+// ---------------------------------------------------------------------------
+// ETL state queries
+// ---------------------------------------------------------------------------
+
+/**
+ * Get ETL state for a source.
+ * @param {Object} db
+ * @param {string} source
+ * @returns {Object|null}
+ */
+function getEtlState(db, source) {
+  return queryOne(db, 'SELECT * FROM etl_state WHERE source = ?', [source]);
+}
+
+/**
+ * Update ETL state for a source (upsert).
+ * @param {Object} db
+ * @param {string} source
+ * @param {Object} data
+ */
+function updateEtlState(db, source, data) {
+  const sql = `INSERT OR REPLACE INTO etl_state (
+    source, last_sync_at, last_session_id, last_session_time, status
+  ) VALUES (?,?,?,?,?)`;
+
+  db.run(sql, [
+    source,
+    data.last_sync_at || null,
+    data.last_session_id || null,
+    data.last_session_time || null,
+    data.status || 'idle',
+  ]);
+}
+
+// ---------------------------------------------------------------------------
+// Analysis state queries
+// ---------------------------------------------------------------------------
+
+/**
+ * Get analysis state (singleton row, id=1).
+ * @param {Object} db
+ * @returns {Object|null}
+ */
+function getAnalysisState(db) {
+  return queryOne(db, 'SELECT * FROM analysis_state WHERE id = 1');
+}
+
+/**
+ * Update the analysis state (singleton row, id=1).
+ * @param {Object} db
+ * @param {Object} data
+ */
+function updateAnalysisState(db, data) {
+  const sql = `INSERT OR REPLACE INTO analysis_state (
+    id, status, current_date, analyzed_count, total_count, last_analyzed_at
+  ) VALUES (1,?,?,?,?,?)`;
+
+  db.run(sql, [
+    data.status || 'idle',
+    data.current_date || null,
+    data.analyzed_count || 0,
+    data.total_count || 0,
+    data.last_analyzed_at || null,
+  ]);
+}
+
+// ---------------------------------------------------------------------------
+// Tool config queries
+// ---------------------------------------------------------------------------
+
+/**
+ * Get configuration for a specific tool.
+ * @param {Object} db
+ * @param {string} tool
+ * @returns {Object|null}
+ */
+function getToolConfig(db, tool) {
+  return queryOne(db, 'SELECT * FROM tool_config WHERE tool = ?', [tool]);
+}
+
+/**
+ * Get all tool configurations.
+ * @param {Object} db
+ * @returns {Object[]}
+ */
+function getAllToolConfigs(db) {
+  return queryAll(db, 'SELECT * FROM tool_config ORDER BY tool');
+}
+
+/**
+ * Insert or replace a tool configuration.
+ * @param {Object} db
+ * @param {Object} config
+ */
+function upsertToolConfig(db, config) {
+  const sql = `INSERT OR REPLACE INTO tool_config (
+    tool, enabled, data_path, status, label
+  ) VALUES (?,?,?,?,?)`;
+
+  db.run(sql, [
+    config.tool,
+    config.enabled ?? 1,
+    config.data_path || null,
+    config.status || 'unknown',
+    config.label,
+  ]);
+}
+
+// ---------------------------------------------------------------------------
+// Overview (home page) — ETL-direct aggregations
+// ---------------------------------------------------------------------------
+//
+// All four helpers below read only from unified_session and never touch the
+// analysis-layer tables.  This guarantees the home page renders immediately
+// after ETL, without waiting for the LLM-driven scoring job to catch up.
+//
+
+/**
+ * Earliest session date present in unified_session, or null if empty.
+ * Used by the overview API to resolve the "all-time" date range without
+ * forking every helper to accept an open-ended bound.
+ *
+ * @param {Object} db
+ * @returns {string|null}  YYYY-MM-DD or null
+ */
+function getEarliestSessionDate(db) {
+  const r = queryOne(db, 'SELECT MIN(date) AS d FROM unified_session');
+  return r && r.d ? r.d : null;
+}
+
+/**
+ * Single-day snapshot aggregated across all sources.
+ * Returns a zero-filled object (never null) so the UI can render safely.
+ *
+ * @param {Object} db
+ * @param {string} date  YYYY-MM-DD
+ * @returns {Object}
+ */
+function getOverviewSnapshot(db, date) {
+  const row = queryOne(
+    db,
+    `SELECT
+        COUNT(*)                          AS sessions,
+        COALESCE(SUM(active_minutes), 0)  AS active_minutes,
+        COALESCE(SUM(cost_usd), 0)        AS cost,
+        COALESCE(SUM(tokens_input), 0)    AS tokens_input,
+        COALESCE(SUM(tokens_output), 0)   AS tokens_output,
+        COALESCE(SUM(message_count), 0)   AS messages,
+        COALESCE(SUM(error_count), 0)     AS errors,
+        COALESCE(SUM(reverted), 0)        AS reverted
+       FROM unified_session
+      WHERE date = ?`,
+    [date]
+  ) || {};
+
+  const tokensInput = row.tokens_input || 0;
+  const tokensOutput = row.tokens_output || 0;
+
+  return {
+    date,
+    sessions:       row.sessions       || 0,
+    activeMinutes:  row.active_minutes  || 0,
+    cost:           Math.round((row.cost || 0) * 10000) / 10000,
+    tokensInput,
+    tokensOutput,
+    tokensTotal:    tokensInput + tokensOutput,
+    messages:       row.messages       || 0,
+    errors:         row.errors         || 0,
+    reverted:       row.reverted       || 0,
+  };
+}
+
+/**
+ * Daily trend rows for the home page, broken out by source so the UI can
+ * render two overlaid lines (opencode vs claude-code).
+ *
+ * @param {Object} db
+ * @param {string} fromDate  YYYY-MM-DD (inclusive)
+ * @param {string} toDate    YYYY-MM-DD (inclusive)
+ * @returns {Object[]}
+ */
+function getOverviewTrend(db, fromDate, toDate) {
+  return queryAll(
+    db,
+    `SELECT
+        date,
+        source,
+        COUNT(*)                          AS sessions,
+        COALESCE(SUM(cost_usd), 0)        AS cost,
+        COALESCE(SUM(active_minutes), 0)  AS active_minutes
+       FROM unified_session
+      WHERE date BETWEEN ? AND ?
+      GROUP BY date, source
+      ORDER BY date ASC, source ASC`,
+    [fromDate, toDate]
+  );
+}
+
+/**
+ * Top projects within a date range, ranked by total cost (USD).
+ * Excludes rows where project is NULL / empty.
+ *
+ * @param {Object} db
+ * @param {string} fromDate
+ * @param {string} toDate
+ * @param {number} [limit=8]
+ * @returns {Object[]}
+ */
+function getOverviewTopProjects(db, fromDate, toDate, limit = 8) {
+  return queryAll(
+    db,
+    `SELECT
+        project,
+        COUNT(*)                              AS sessions,
+        COALESCE(SUM(cost_usd), 0)            AS cost,
+        COALESCE(SUM(active_minutes), 0)      AS active_minutes,
+        COALESCE(SUM(summary_additions), 0)   AS additions,
+        COALESCE(SUM(summary_deletions), 0)   AS deletions,
+        COALESCE(SUM(summary_files), 0)       AS files
+       FROM unified_session
+      WHERE date BETWEEN ? AND ?
+        AND project IS NOT NULL
+        AND project <> ''
+      GROUP BY project
+      ORDER BY cost DESC, sessions DESC
+      LIMIT ?`,
+    [fromDate, toDate, limit]
+  );
+}
+
+/**
+ * Per-day cache effectiveness (hit-rate) for a date window.
+ * Hit rate = cache_read / (cache_read + cache_write + tokens_input).
+ * See the implementation below for why cache_write is in the denominator.
+ * Raw numerator/denominator are returned so the UI can change the formula
+ * later without another query.
+ *
+ * @param {Object} db
+ * @param {string} fromDate
+ * @param {string} toDate
+ * @returns {Object[]}
+ */
+function getOverviewCacheRate(db, fromDate, toDate) {
+  const rows = queryAll(
+    db,
+    `SELECT
+        date,
+        COALESCE(SUM(tokens_input), 0)        AS tokens_input,
+        COALESCE(SUM(tokens_cache_read), 0)   AS cache_read,
+        COALESCE(SUM(tokens_cache_write), 0)  AS cache_write
+       FROM unified_session
+      WHERE date BETWEEN ? AND ?
+      GROUP BY date
+      ORDER BY date ASC`,
+    [fromDate, toDate]
+  );
+  return rows.map((r) => {
+    const input = r.tokens_input || 0;
+    const cr    = r.cache_read   || 0;
+    const cw    = r.cache_write  || 0;
+    // Hit rate = reused cached input / total input tokens the model saw.
+    // Including cache_write in the denominator matters: those are tokens
+    // that *paid full price* this turn (writing them to the cache); only
+    // future turns benefit.  Excluding cache_write would always inflate
+    // the rate toward ~100% in long sessions and obscure the moment a
+    // huge new context block was loaded.
+    const denom = cr + cw + input;
+    return {
+      date:       r.date,
+      input,
+      cacheRead:  cr,
+      cacheWrite: cw,
+      hitRate:    denom > 0 ? Math.round((cr / denom) * 1000) / 10 : 0, // %
+    };
+  });
+}
+
+/**
+ * Per-day error rate for a date window.
+ * rate = SUM(error_count) / NULLIF(SUM(message_count), 0)
+ *
+ * @param {Object} db
+ * @param {string} fromDate
+ * @param {string} toDate
+ * @returns {Object[]}
+ */
+function getOverviewErrorRate(db, fromDate, toDate) {
+  const rows = queryAll(
+    db,
+    `SELECT
+        date,
+        COALESCE(SUM(error_count), 0)    AS errors,
+        COALESCE(SUM(message_count), 0)  AS messages,
+        COALESCE(SUM(tool_call_count),0) AS tool_calls
+       FROM unified_session
+      WHERE date BETWEEN ? AND ?
+      GROUP BY date
+      ORDER BY date ASC`,
+    [fromDate, toDate]
+  );
+  return rows.map((r) => ({
+    date:     r.date,
+    errors:   r.errors   || 0,
+    messages: r.messages || 0,
+    toolCalls: r.tool_calls || 0,
+    rate:     r.messages > 0
+      ? Math.round((r.errors / r.messages) * 10000) / 100  // % with 2 decimals
+      : 0,
+  }));
+}
+
+/**
+ * Tool usage Top-N within a date window, with error-rate per tool.
+ * Joins unified_tool_call -> unified_session to apply the date filter.
+ *
+ * @param {Object} db
+ * @param {string} fromDate
+ * @param {string} toDate
+ * @param {number} [limit=10]
+ * @returns {Object[]}
+ */
+function getOverviewTopTools(db, fromDate, toDate, limit = 10) {
+  const rows = queryAll(
+    db,
+    `SELECT
+        tc.tool_name                                              AS tool,
+        COUNT(*)                                                  AS calls,
+        SUM(CASE WHEN tc.status = 'error' THEN 1 ELSE 0 END)      AS errors,
+        COUNT(DISTINCT tc.session_id)                             AS sessions
+       FROM unified_tool_call tc
+       JOIN unified_session   s ON s.id = tc.session_id
+      WHERE s.date BETWEEN ? AND ?
+        AND tc.tool_name IS NOT NULL
+        AND tc.tool_name <> ''
+      GROUP BY tc.tool_name
+      ORDER BY calls DESC
+      LIMIT ?`,
+    [fromDate, toDate, limit]
+  );
+  return rows.map((r) => ({
+    tool:      r.tool,
+    calls:     r.calls    || 0,
+    errors:    r.errors   || 0,
+    sessions:  r.sessions || 0,
+    errorRate: r.calls > 0
+      ? Math.round((r.errors / r.calls) * 1000) / 10 // % with 1 decimal
+      : 0,
+  }));
+}
+
+/**
+ * Most recent sessions across all sources / dates.
+ *
+ * Excludes subagents (parent_session_id IS NOT NULL) by default so the
+ * "最近 10 个会话" panel only shows top-level work; aggregate stats on
+ * the same page still include them via their own queries.
+ *
+ * @param {Object} db
+ * @param {number} [limit=10]
+ * @returns {Object[]}
+ */
+function getOverviewRecentSessions(db, limit = 10) {
+  return queryAll(
+    db,
+    `SELECT
+        id,
+        source,
+        started_at,
+        project,
+        title,
+        model,
+        message_count,
+        cost_usd,
+        error_count,
+        reverted
+       FROM unified_session
+      WHERE parent_session_id IS NULL
+      ORDER BY started_at DESC
+      LIMIT ?`,
+    [limit]
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  // Internal helpers (exported for testing / advanced use)
+  queryAll,
+  queryOne,
+
+  // Session
+  upsertSession,
+  getSessionsByDate,
+  getSessionById,
+  getSessionsByDateRange,
+  countSessionsByDateRange,
+
+  // Message
+  getMessagesBySession,
+  bulkInsertMessages,
+
+  // Part
+  getPartsBySession,
+  bulkInsertParts,
+
+  // Tool call
+  getToolCallsBySession,
+  bulkInsertToolCalls,
+
+  // Analysis
+  upsertSessionAnalysis,
+  getAnalysisBySession,
+  getUnanalyzedSessions,
+  upsertDailySummary,
+  getDailySummary,
+  getDailySummaries,
+
+  // Hourly activity
+  upsertHourlyActivity,
+  getHourlyActivity,
+
+  // Settings
+  getSetting,
+  setSetting,
+  getAllSettings,
+
+  // ETL state
+  getEtlState,
+  updateEtlState,
+
+  // Analysis state
+  getAnalysisState,
+  updateAnalysisState,
+
+  // Tool config
+  getToolConfig,
+  getAllToolConfigs,
+  upsertToolConfig,
+
+  // Overview (home page) — ETL-direct
+  getOverviewSnapshot,
+  getOverviewTrend,
+  getOverviewTopProjects,
+  getOverviewRecentSessions,
+  getOverviewCacheRate,
+  getOverviewErrorRate,
+  getOverviewTopTools,
+  getEarliestSessionDate,
+};