agentboss 0.1.2 → 0.1.4

package/server/db/queries.js

@@ -1,1051 +1,1108 @@
-/**
- * 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,
-};
+/**
+ * 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]
+  );
+}
+
+/**
+ * Count user messages per session for all sessions in a date range.
+ * One aggregate query (cheaper than N getMessagesBySession calls); used by
+ * the report builder's session list.
+ *
+ * @param {Object} db
+ * @param {string} fromDate  YYYY-MM-DD inclusive
+ * @param {string} toDate    YYYY-MM-DD inclusive
+ * @returns {Map<string, number>}  sessionId -> user message count
+ */
+function getUserMessageCountsByDateRange(db, fromDate, toDate) {
+  const rows = queryAll(
+    db,
+    `SELECT m.session_id AS session_id, COUNT(*) AS cnt
+       FROM unified_message m
+       JOIN unified_session s ON s.id = m.session_id
+      WHERE s.date >= ? AND s.date <= ? AND m.role = 'user'
+      GROUP BY m.session_id`,
+    [fromDate, toDate]
+  );
+  const map = new Map();
+  for (const r of rows) map.set(r.session_id, r.cnt || 0);
+  return map;
+}
+
+/**
+ * Count user / assistant messages for an explicit set of session IDs.
+ * Used by the overview "recent sessions" table so its message counts match
+ * the per-session detail (real rows), not the ETL-stored message_count.
+ *
+ * @param {Object} db
+ * @param {string[]} sessionIds
+ * @returns {Map<string, {user:number, assistant:number}>}
+ */
+function getMessageRoleCounts(db, sessionIds) {
+  const map = new Map();
+  if (!Array.isArray(sessionIds) || sessionIds.length === 0) return map;
+  const placeholders = sessionIds.map(() => '?').join(',');
+  const rows = queryAll(
+    db,
+    `SELECT session_id, role, COUNT(*) AS cnt
+       FROM unified_message
+      WHERE session_id IN (${placeholders})
+      GROUP BY session_id, role`,
+    sessionIds
+  );
+  for (const r of rows) {
+    const e = map.get(r.session_id) || { user: 0, assistant: 0 };
+    if (r.role === 'user') e.user = r.cnt || 0;
+    else if (r.role === 'assistant') e.assistant = r.cnt || 0;
+    map.set(r.session_id, e);
+  }
+  return map;
+}
+
+/**
+ * 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,
+  getUserMessageCountsByDateRange,
+  getMessageRoleCounts,
+  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,
+};