2ndbrain 2026.1.30 → 2026.1.32

package/src/claude/conversation.js

@@ -0,0 +1,219 @@
+/**
+ * Conversation manager (spec section 6).
+ *
+ * Persists all conversation turns to the conversation_messages table,
+ * manages Claude CLI sessions, and controls history size through
+ * auto-compaction.
+ */
+class ConversationManager {
+  /**
+   * @param {object} options
+   * @param {object} options.db - Database pool or query interface (must expose .query())
+   * @param {object} options.logger - Structured logger instance
+   * @param {object} options.config - Application configuration object
+   */
+  constructor({ db, logger, config }) {
+    this.db = db;
+    this.logger = logger;
+    this.config = config;
+
+    /** @type {string|null} Active Claude CLI session ID */
+    this.currentSessionId = null;
+  }
+
+  /**
+   * Save a conversation message to the database.
+   *
+   * @param {string} role - Message role: 'user', 'assistant', 'system', or 'summary'
+   * @param {string} content - Message text content
+   * @param {object} [metadata=null] - Optional JSONB metadata (tool calls, attachments, cost, etc.)
+   * @returns {Promise<object>} The inserted row
+   */
+  async saveMessage(role, content, metadata = null) {
+    const result = await this.db.query(
+      `INSERT INTO conversation_messages (session_id, role, content, metadata)
+       VALUES ($1, $2, $3, $4)
+       RETURNING *`,
+      [this.currentSessionId, role, content, metadata ? JSON.stringify(metadata) : null],
+    );
+
+    this.logger.debug(
+      'conversation',
+      `Saved ${role} message (session=${this.currentSessionId || 'none'}, length=${content.length})`,
+    );
+
+    return result.rows[0];
+  }
+
+  /**
+   * Fetch recent conversation messages.
+   *
+   * @param {number} [limit] - Maximum number of messages to return.
+   *   Defaults to HISTORY_COMPACT_THRESHOLD from config.
+   * @returns {Promise<Array<object>>} Messages ordered oldest-first
+   */
+  async getHistory(limit) {
+    const effectiveLimit = limit ?? this.config.HISTORY_COMPACT_THRESHOLD;
+
+    const result = await this.db.query(
+      `SELECT id, created_at, session_id, role, content, metadata
+       FROM conversation_messages
+       ORDER BY created_at DESC
+       LIMIT $1`,
+      [effectiveLimit],
+    );
+
+    // Return in chronological order (oldest first)
+    return result.rows.reverse();
+  }
+
+  /**
+   * Get the total number of conversation messages.
+   *
+   * @returns {Promise<number>}
+   */
+  async getMessageCount() {
+    const result = await this.db.query('SELECT COUNT(*)::int AS count FROM conversation_messages');
+    return result.rows[0].count;
+  }
+
+  /**
+   * Get the timestamp of the most recent conversation message.
+   *
+   * @returns {Promise<string|null>} ISO timestamp string, or null if no messages exist
+   */
+  async getLastActivity() {
+    const result = await this.db.query(
+      'SELECT created_at FROM conversation_messages ORDER BY created_at DESC LIMIT 1',
+    );
+    return result.rows[0]?.created_at?.toISOString() ?? null;
+  }
+
+  /**
+   * Start a new conversation session.
+   *
+   * Sets currentSessionId to null so the next Claude invocation will
+   * create a fresh session. The previous session remains in the database.
+   */
+  newSession() {
+    this.logger.info('conversation', `Starting new session (previous=${this.currentSessionId || 'none'})`);
+    this.currentSessionId = null;
+  }
+
+  /**
+   * Update the current session ID (typically called after receiving
+   * the session_id from a Claude CLI result).
+   *
+   * @param {string} id - The Claude CLI session ID
+   */
+  setSessionId(id) {
+    this.currentSessionId = id;
+    this.logger.debug('conversation', `Session ID set to ${id}`);
+  }
+
+  /**
+   * Auto-compact conversation history when it exceeds the configured threshold.
+   *
+   * Compaction only runs when no Claude subprocess is active (prevents race
+   * conditions). Old messages are summarized via Claude and replaced with a
+   * single summary message, keeping the 20 most recent messages intact.
+   *
+   * @param {object} claudeBridge - ClaudeBridge instance (used to check activity and summarize)
+   * @returns {Promise<boolean>} True if compaction was performed
+   */
+  async compact(claudeBridge) {
+    // Guard: do not compact while Claude is processing a request
+    if (claudeBridge.isActive()) {
+      this.logger.debug('conversation', 'Skipping compaction: Claude subprocess is active');
+      return false;
+    }
+
+    const count = await this.getMessageCount();
+    const threshold = this.config.HISTORY_COMPACT_THRESHOLD;
+
+    if (count <= threshold) {
+      this.logger.debug('conversation', `No compaction needed (${count}/${threshold} messages)`);
+      return false;
+    }
+
+    this.logger.info('conversation', `Starting compaction (${count} messages, threshold=${threshold})`);
+
+    const keepRecent = 20;
+    const removeCount = count - keepRecent;
+
+    try {
+      // Fetch the oldest messages that will be summarized
+      const oldMessages = await this.db.query(
+        `SELECT id, created_at, role, content
+         FROM conversation_messages
+         ORDER BY created_at ASC
+         LIMIT $1`,
+        [removeCount],
+      );
+
+      if (oldMessages.rows.length === 0) {
+        return false;
+      }
+
+      // Format old messages for the summarization prompt
+      const formatted = oldMessages.rows
+        .map((msg) => `[${msg.role}] (${msg.created_at.toISOString()}): ${msg.content}`)
+        .join('\n\n');
+
+      const summarizationPrompt =
+        'Summarize the following conversation history into a concise context summary. ' +
+        'Preserve key facts, decisions, ongoing topics, and any important context. ' +
+        'Use bullet points for clarity. This summary will replace the original messages ' +
+        'to keep conversation history manageable.';
+
+      // Use the Claude bridge to generate a summary
+      const result = await claudeBridge.invoke(
+        `${summarizationPrompt}\n\n---\n\n${formatted}`,
+        null, // New session for the summary task
+        'You are a conversation summarizer. Produce a concise, factual summary.',
+      );
+
+      if (!result.text) {
+        this.logger.warn('conversation', 'Compaction aborted: empty summary from Claude');
+        return false;
+      }
+
+      // Collect IDs of messages to delete
+      const idsToDelete = oldMessages.rows.map((msg) => msg.id);
+
+      // Insert the summary message
+      await this.db.query(
+        `INSERT INTO conversation_messages (session_id, role, content, metadata)
+         VALUES ($1, 'summary', $2, $3)`,
+        [
+          this.currentSessionId,
+          result.text,
+          JSON.stringify({
+            compacted_count: idsToDelete.length,
+            compacted_at: new Date().toISOString(),
+            summary_cost_usd: result.cost,
+          }),
+        ],
+      );
+
+      // Delete the original old messages
+      await this.db.query(
+        'DELETE FROM conversation_messages WHERE id = ANY($1::int[])',
+        [idsToDelete],
+      );
+
+      this.logger.info(
+        'conversation',
+        `Compaction complete: ${idsToDelete.length} messages replaced with summary`,
+      );
+
+      return true;
+    } catch (err) {
+      this.logger.error('conversation', `Compaction failed: ${err.message}`);
+      return false;
+    }
+  }
+}
+
+export { ConversationManager };
+export default ConversationManager;

package/src/config.js

@@ -0,0 +1,90 @@
+import { config as dotenvConfig } from 'dotenv';
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PROJECT_ROOT = path.resolve(__dirname, '..');
+const ENV_PATH = path.join(PROJECT_ROOT, '.env');
+
+// Load .env from project root
+dotenvConfig({ path: ENV_PATH });
+
+const env = process.env;
+
+const config = {
+  // Required
+  TELEGRAM_BOT_TOKEN: env.TELEGRAM_BOT_TOKEN || '',
+  TELEGRAM_ALLOWED_USERS: env.TELEGRAM_ALLOWED_USERS || '',
+  DATABASE_URL: env.DATABASE_URL || '',
+
+  // Claude Bridge
+  CLAUDE_MODEL: env.CLAUDE_MODEL || 'claude-sonnet-4-20250514',
+  CLAUDE_THINKING: env.CLAUDE_THINKING || 'true',
+  CLAUDE_TIMEOUT: parseInt(env.CLAUDE_TIMEOUT, 10) || 120000,
+  CLAUDE_MAX_BUDGET: env.CLAUDE_MAX_BUDGET || '',
+
+  // Storage
+  DATA_DIR: env.DATA_DIR || path.join(os.homedir(), 'data'),
+
+  // MCP
+  MCP_CONFIG_PATH: env.MCP_CONFIG_PATH || path.join(os.homedir(), '.claude', 'mcp.json'),
+  MCP_TOOLS_WHITELIST: env.MCP_TOOLS_WHITELIST || '*',
+  COMMANDS_WHITELIST: env.COMMANDS_WHITELIST || '',
+
+  // Security
+  FILE_EDIT_PATHS: env.FILE_EDIT_PATHS || '',
+
+  // Rate Limiting
+  RATE_LIMIT_CLAUDE: parseInt(env.RATE_LIMIT_CLAUDE, 10) || 10,
+  RATE_LIMIT_TELEGRAM: parseInt(env.RATE_LIMIT_TELEGRAM, 10) || 30,
+
+  // Conversation
+  HISTORY_COMPACT_THRESHOLD: parseInt(env.HISTORY_COMPACT_THRESHOLD, 10) || 100,
+
+  // Logging
+  LOG_LEVEL: env.LOG_LEVEL || 'info',
+
+  // Web Admin
+  WEB_PORT: parseInt(env.WEB_PORT, 10) || 3000,
+  WEB_BIND: env.WEB_BIND || '127.0.0.1',
+  AUTO_OPEN_BROWSER: env.AUTO_OPEN_BROWSER || 'true',
+
+  // Embeddings
+  EMBEDDING_PROVIDER: env.EMBEDDING_PROVIDER || '',
+  EMBEDDING_API_KEY: env.EMBEDDING_API_KEY || '',
+  EMBEDDING_MODEL: env.EMBEDDING_MODEL || 'text-embedding-3-small',
+  EMBEDDING_DIMENSIONS: env.EMBEDDING_DIMENSIONS || '',
+  EMBEDDING_BASE_URL: env.EMBEDDING_BASE_URL || '',
+};
+
+const REQUIRED_VARS = ['TELEGRAM_BOT_TOKEN', 'TELEGRAM_ALLOWED_USERS', 'DATABASE_URL'];
+
+/**
+ * Validates that all required configuration variables are present and non-empty.
+ * Returns an object with `valid` boolean and `missing` array of variable names.
+ */
+function validateConfig() {
+  const missing = REQUIRED_VARS.filter((key) => !config[key]);
+  return {
+    valid: missing.length === 0,
+    missing,
+  };
+}
+
+/**
+ * Returns true if this appears to be a first run -- either the .env file
+ * does not exist or required configuration variables are missing.
+ */
+function isFirstRun() {
+  if (!fs.existsSync(ENV_PATH)) {
+    return true;
+  }
+  const { valid } = validateConfig();
+  return !valid;
+}
+
+export { config, validateConfig, isFirstRun, PROJECT_ROOT, ENV_PATH };
+export default config;

package/src/db/migrate.js

@@ -0,0 +1,94 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pool } from './pool.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const MIGRATIONS_DIR = path.resolve(__dirname, '../../db/migrations');
+
+/**
+ * Ensure the schema_migrations tracking table exists.
+ */
+async function ensureMigrationsTable() {
+  await pool.query(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      name        TEXT PRIMARY KEY,
+      applied_at  TIMESTAMPTZ DEFAULT NOW()
+    )
+  `);
+}
+
+/**
+ * Retrieve the set of already-applied migration names.
+ * @returns {Promise<Set<string>>}
+ */
+async function getAppliedMigrations() {
+  const result = await pool.query('SELECT name FROM schema_migrations ORDER BY name');
+  return new Set(result.rows.map((row) => row.name));
+}
+
+/**
+ * Read all .sql migration files from the migrations directory, sorted by filename.
+ * @returns {string[]} Sorted array of filenames
+ */
+function getMigrationFiles() {
+  if (!fs.existsSync(MIGRATIONS_DIR)) {
+    return [];
+  }
+  return fs
+    .readdirSync(MIGRATIONS_DIR)
+    .filter((f) => f.endsWith('.sql'))
+    .sort();
+}
+
+/**
+ * Run all pending database migrations inside individual transactions.
+ * Each migration that has not yet been recorded in schema_migrations
+ * is executed and tracked.
+ *
+ * @returns {Promise<string[]>} List of migration names that were applied
+ */
+async function migrate() {
+  await ensureMigrationsTable();
+
+  const applied = await getAppliedMigrations();
+  const files = getMigrationFiles();
+  const newlyApplied = [];
+
+  for (const file of files) {
+    if (applied.has(file)) {
+      continue;
+    }
+
+    const filePath = path.join(MIGRATIONS_DIR, file);
+    const sql = fs.readFileSync(filePath, 'utf-8');
+
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      await client.query(sql);
+      await client.query('INSERT INTO schema_migrations (name) VALUES ($1)', [file]);
+      await client.query('COMMIT');
+      newlyApplied.push(file);
+      console.log(`[${new Date().toISOString()}] [info] [migrate] Applied migration: ${file}`);
+    } catch (err) {
+      await client.query('ROLLBACK');
+      console.error(`[${new Date().toISOString()}] [error] [migrate] Failed to apply migration ${file}:`, err.message);
+      throw err;
+    } finally {
+      client.release();
+    }
+  }
+
+  if (newlyApplied.length === 0) {
+    console.log(`[${new Date().toISOString()}] [info] [migrate] No pending migrations.`);
+  } else {
+    console.log(`[${new Date().toISOString()}] [info] [migrate] Applied ${newlyApplied.length} migration(s).`);
+  }
+
+  return newlyApplied;
+}
+
+export { migrate, getAppliedMigrations, getMigrationFiles, ensureMigrationsTable };
+export default migrate;

package/src/db/pool.js

@@ -0,0 +1,33 @@
+import pg from 'pg';
+import config from '../config.js';
+
+const { Pool } = pg;
+
+const pool = new Pool({
+  connectionString: config.DATABASE_URL,
+});
+
+// Emit errors on idle clients so they don't crash the process
+pool.on('error', (err) => {
+  console.error(`[${new Date().toISOString()}] [error] [db/pool] Unexpected idle client error:`, err.message);
+});
+
+/**
+ * Execute a parameterized SQL query against the pool.
+ * @param {string} text - SQL query string
+ * @param {Array} [params] - Query parameters
+ * @returns {Promise<pg.QueryResult>}
+ */
+async function query(text, params) {
+  return pool.query(text, params);
+}
+
+/**
+ * Gracefully close all connections in the pool.
+ */
+async function close() {
+  await pool.end();
+}
+
+export { pool, query, close };
+export default pool;