@cpretzinger/boss-claude 1.0.0 → 1.0.2

package/lib/agents/memory-engineers/postgres-memory-engineer.js

@@ -0,0 +1,633 @@
+/**
+ * PostgreSQL Memory Engineer
+ *
+ * Component: Structured queries on PostgreSQL
+ * Schema: boss_claude.sessions table
+ *
+ * Features:
+ * - Query boss_claude.sessions table
+ * - Full-text search on summaries and context
+ * - Date range filtering
+ * - Tag-based filtering
+ * - Session retrieval with metadata
+ */
+
+import pg from 'pg';
+const { Pool } = pg;
+
+// Use shared connection pool
+let pool;
+
+/**
+ * Initialize PostgreSQL connection pool
+ */
+function getPool() {
+  if (!pool) {
+    pool = new Pool({
+      connectionString: process.env.BOSS_CLAUDE_PG_URL,
+      max: 10,
+      idleTimeoutMillis: 30000,
+      connectionTimeoutMillis: 2000,
+      ssl: {
+        rejectUnauthorized: true
+      }
+    });
+
+    pool.on('error', (err) => {
+      console.error('[PostgresMemoryEngineer] Pool error:', err);
+    });
+  }
+  return pool;
+}
+
+/**
+ * Execute a query with timeout protection
+ * @param {Object} pool - PostgreSQL pool
+ * @param {string} query - SQL query
+ * @param {Array} params - Query parameters
+ * @param {number} timeout - Timeout in milliseconds (default: 30000)
+ * @returns {Promise<Object>} Query result
+ */
+async function queryWithTimeout(pool, query, params, timeout = 30000) {
+  return Promise.race([
+    pool.query(query, params),
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('[PostgresMemoryEngineer] Query timeout')), timeout)
+    )
+  ]);
+}
+
+/**
+ * Validate ORDER BY clause to prevent SQL injection
+ * @param {string} orderBy - Column name to order by
+ * @param {string} orderDir - Direction (ASC or DESC)
+ * @returns {Object} Validated orderBy and orderDir
+ * @throws {Error} If invalid column or direction
+ */
+function validateOrderClause(orderBy, orderDir) {
+  // Whitelist of allowed ORDER BY columns
+  const ALLOWED_ORDER_COLUMNS = [
+    'id',
+    'user_id',
+    'project',
+    'start_time',
+    'end_time',
+    'duration_seconds',
+    'xp_earned',
+    'tokens_saved',
+    'tasks_completed',
+    'perfect_executions',
+    'efficiency_multiplier',
+    'level_at_start',
+    'level_at_end',
+    'relevance'
+  ];
+
+  // Whitelist of allowed directions
+  const ALLOWED_DIRECTIONS = ['ASC', 'DESC'];
+
+  const normalizedOrderBy = orderBy?.toLowerCase() || 'start_time';
+  const normalizedOrderDir = orderDir?.toUpperCase() || 'DESC';
+
+  if (!ALLOWED_ORDER_COLUMNS.includes(normalizedOrderBy)) {
+    throw new Error(`Invalid ORDER BY column: ${orderBy}. Allowed columns: ${ALLOWED_ORDER_COLUMNS.join(', ')}`);
+  }
+
+  if (!ALLOWED_DIRECTIONS.includes(normalizedOrderDir)) {
+    throw new Error(`Invalid ORDER BY direction: ${orderDir}. Allowed: ASC, DESC`);
+  }
+
+  return {
+    orderBy: normalizedOrderBy,
+    orderDir: normalizedOrderDir
+  };
+}
+
+/**
+ * PostgreSQL Memory Engineer
+ */
+export class PostgresMemoryEngineer {
+  constructor() {
+    this.pool = getPool();
+  }
+
+  /**
+   * Search sessions with full-text search on summary and context_data
+   * @param {string} userId - User identifier
+   * @param {string} searchTerm - Search term for full-text search
+   * @param {Object} options - Search options
+   * @returns {Promise<Array>} Matching sessions
+   */
+  async fullTextSearch(userId, searchTerm, options = {}) {
+    try {
+      const {
+        limit = 50,
+        offset = 0,
+        orderBy = 'start_time',
+        orderDir = 'DESC'
+      } = options;
+
+      // Validate ORDER BY clause to prevent SQL injection
+      const validated = validateOrderClause(orderBy, orderDir);
+
+      const query = `
+        SELECT
+          id,
+          user_id,
+          project,
+          start_time,
+          end_time,
+          duration_seconds,
+          xp_earned,
+          tokens_saved,
+          tasks_completed,
+          perfect_executions,
+          efficiency_multiplier,
+          level_at_start,
+          level_at_end,
+          summary,
+          context_data,
+          ts_rank(
+            to_tsvector('english', COALESCE(summary, '') || ' ' || COALESCE(context_data::text, '')),
+            plainto_tsquery('english', $2)
+          ) as relevance
+        FROM boss_claude.sessions
+        WHERE user_id = $1
+          AND (
+            to_tsvector('english', COALESCE(summary, '') || ' ' || COALESCE(context_data::text, ''))
+            @@ plainto_tsquery('english', $2)
+          )
+        ORDER BY ${validated.orderBy} ${validated.orderDir}
+        LIMIT $3 OFFSET $4
+      `;
+
+      const result = await queryWithTimeout(this.pool, query, [userId, searchTerm, limit, offset]);
+      return result.rows;
+    } catch (error) {
+      console.error('[PostgresMemoryEngineer] fullTextSearch error:', error);
+      throw new Error(`Failed to execute full-text search: ${error.message}`);
+    }
+  }
+
+  /**
+   * Filter sessions by date range
+   * @param {string} userId - User identifier
+   * @param {Date|string} startDate - Start date
+   * @param {Date|string} endDate - End date
+   * @param {Object} options - Query options
+   * @returns {Promise<Array>} Sessions in date range
+   */
+  async filterByDateRange(userId, startDate, endDate, options = {}) {
+    try {
+      const {
+        limit = 100,
+        offset = 0,
+        includeActive = true,
+        orderBy = 'start_time',
+        orderDir = 'DESC'
+      } = options;
+
+      // Validate ORDER BY clause to prevent SQL injection
+      const validated = validateOrderClause(orderBy, orderDir);
+
+      let query = `
+        SELECT
+          id,
+          user_id,
+          project,
+          start_time,
+          end_time,
+          duration_seconds,
+          xp_earned,
+          tokens_saved,
+          tasks_completed,
+          perfect_executions,
+          efficiency_multiplier,
+          level_at_start,
+          level_at_end,
+          summary,
+          context_data
+        FROM boss_claude.sessions
+        WHERE user_id = $1
+          AND start_time >= $2
+          AND start_time <= $3
+      `;
+
+      const params = [userId, startDate, endDate];
+
+      if (!includeActive) {
+        query += ` AND end_time IS NOT NULL`;
+      }
+
+      query += `
+        ORDER BY ${validated.orderBy} ${validated.orderDir}
+        LIMIT $4 OFFSET $5
+      `;
+
+      params.push(limit, offset);
+
+      const result = await queryWithTimeout(this.pool, query, params);
+      return result.rows;
+    } catch (error) {
+      console.error('[PostgresMemoryEngineer] filterByDateRange error:', error);
+      throw new Error(`Failed to filter by date range: ${error.message}`);
+    }
+  }
+
+  /**
+   * Filter sessions by tags in context_data
+   * @param {string} userId - User identifier
+   * @param {Array<string>} tags - Tags to filter by
+   * @param {Object} options - Query options
+   * @returns {Promise<Array>} Sessions matching tags
+   */
+  async filterByTags(userId, tags, options = {}) {
+    try {
+      const {
+        limit = 50,
+        offset = 0,
+        matchAll = false, // true = AND, false = OR
+        orderBy = 'start_time',
+        orderDir = 'DESC'
+      } = options;
+
+      // Validate ORDER BY clause to prevent SQL injection
+      const validated = validateOrderClause(orderBy, orderDir);
+
+      // Build JSONB query for tags
+      const tagConditions = tags.map((tag, idx) => {
+        return `context_data->'tags' @> $${idx + 2}`;
+      }).join(matchAll ? ' AND ' : ' OR ');
+
+      const query = `
+        SELECT
+          id,
+          user_id,
+          project,
+          start_time,
+          end_time,
+          duration_seconds,
+          xp_earned,
+          tokens_saved,
+          tasks_completed,
+          perfect_executions,
+          efficiency_multiplier,
+          level_at_start,
+          level_at_end,
+          summary,
+          context_data,
+          context_data->'tags' as tags
+        FROM boss_claude.sessions
+        WHERE user_id = $1
+          AND (${tagConditions})
+        ORDER BY ${validated.orderBy} ${validated.orderDir}
+        LIMIT $${tags.length + 2} OFFSET $${tags.length + 3}
+      `;
+
+      const params = [
+        userId,
+        ...tags.map(tag => JSON.stringify([tag])),
+        limit,
+        offset
+      ];
+
+      const result = await queryWithTimeout(this.pool, query, params);
+      return result.rows;
+    } catch (error) {
+      console.error('[PostgresMemoryEngineer] filterByTags error:', error);
+      throw new Error(`Failed to filter by tags: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get sessions by project name
+   * @param {string} userId - User identifier
+   * @param {string} projectName - Project name
+   * @param {Object} options - Query options
+   * @returns {Promise<Array>} Sessions for project
+   */
+  async filterByProject(userId, projectName, options = {}) {
+    try {
+      const {
+        limit = 50,
+        offset = 0,
+        orderBy = 'start_time',
+        orderDir = 'DESC'
+      } = options;
+
+      // Validate ORDER BY clause to prevent SQL injection
+      const validated = validateOrderClause(orderBy, orderDir);
+
+      const query = `
+        SELECT
+          id,
+          user_id,
+          project,
+          start_time,
+          end_time,
+          duration_seconds,
+          xp_earned,
+          tokens_saved,
+          tasks_completed,
+          perfect_executions,
+          efficiency_multiplier,
+          level_at_start,
+          level_at_end,
+          summary,
+          context_data
+        FROM boss_claude.sessions
+        WHERE user_id = $1
+          AND project = $2
+        ORDER BY ${validated.orderBy} ${validated.orderDir}
+        LIMIT $3 OFFSET $4
+      `;
+
+      const result = await queryWithTimeout(this.pool, query, [userId, projectName, limit, offset]);
+      return result.rows;
+    } catch (error) {
+      console.error('[PostgresMemoryEngineer] filterByProject error:', error);
+      throw new Error(`Failed to filter by project: ${error.message}`);
+    }
+  }
+
+  /**
+   * Advanced query builder with multiple filters
+   * @param {string} userId - User identifier
+   * @param {Object} filters - Combined filters
+   * @returns {Promise<Array>} Filtered sessions
+   */
+  async advancedQuery(userId, filters = {}) {
+    const {
+      searchTerm,
+      startDate,
+      endDate,
+      tags,
+      project,
+      minXp,
+      minTokens,
+      minEfficiency,
+      includeActive = true,
+      limit = 50,
+      offset = 0,
+      orderBy = 'start_time',
+      orderDir = 'DESC'
+    } = filters;
+
+    // Validate ORDER BY clause to prevent SQL injection
+    const validated = validateOrderClause(orderBy, orderDir);
+
+    let conditions = ['user_id = $1'];
+    let params = [userId];
+    let paramCount = 1;
+
+    // Full-text search
+    if (searchTerm) {
+      paramCount++;
+      conditions.push(`
+        to_tsvector('english', COALESCE(summary, '') || ' ' || COALESCE(context_data::text, ''))
+        @@ plainto_tsquery('english', $${paramCount})
+      `);
+      params.push(searchTerm);
+    }
+
+    // Date range
+    if (startDate) {
+      paramCount++;
+      conditions.push(`start_time >= $${paramCount}`);
+      params.push(startDate);
+    }
+    if (endDate) {
+      paramCount++;
+      conditions.push(`start_time <= $${paramCount}`);
+      params.push(endDate);
+    }
+
+    // Tags
+    if (tags && tags.length > 0) {
+      const tagConditions = tags.map(tag => {
+        paramCount++;
+        params.push(JSON.stringify([tag]));
+        return `context_data->'tags' @> $${paramCount}`;
+      }).join(' OR ');
+      conditions.push(`(${tagConditions})`);
+    }
+
+    // Project
+    if (project) {
+      paramCount++;
+      conditions.push(`project = $${paramCount}`);
+      params.push(project);
+    }
+
+    // XP threshold
+    if (minXp !== undefined) {
+      paramCount++;
+      conditions.push(`xp_earned >= $${paramCount}`);
+      params.push(minXp);
+    }
+
+    // Token threshold
+    if (minTokens !== undefined) {
+      paramCount++;
+      conditions.push(`tokens_saved >= $${paramCount}`);
+      params.push(minTokens);
+    }
+
+    // Efficiency threshold
+    if (minEfficiency !== undefined) {
+      paramCount++;
+      conditions.push(`efficiency_multiplier >= $${paramCount}`);
+      params.push(minEfficiency);
+    }
+
+    // Active sessions filter
+    if (!includeActive) {
+      conditions.push('end_time IS NOT NULL');
+    }
+
+    const query = `
+      SELECT
+        id,
+        user_id,
+        project,
+        start_time,
+        end_time,
+        duration_seconds,
+        xp_earned,
+        tokens_saved,
+        tasks_completed,
+        perfect_executions,
+        efficiency_multiplier,
+        level_at_start,
+        level_at_end,
+        summary,
+        context_data,
+        ${searchTerm ? `
+          ts_rank(
+            to_tsvector('english', COALESCE(summary, '') || ' ' || COALESCE(context_data::text, '')),
+            plainto_tsquery('english', $2)
+          ) as relevance,
+        ` : ''}
+        context_data->'tags' as tags
+      FROM boss_claude.sessions
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY ${validated.orderBy} ${validated.orderDir}
+      LIMIT $${paramCount + 1} OFFSET $${paramCount + 2}
+    `;
+
+    params.push(limit, offset);
+
+    const result = await queryWithTimeout(this.pool, query, params);
+    return result.rows;
+  }
+
+  /**
+   * Get session statistics and aggregations
+   * @param {string} userId - User identifier
+   * @param {Object} filters - Filters to apply before aggregation
+   * @returns {Promise<Object>} Aggregated statistics
+   */
+  async getSessionStats(userId, filters = {}) {
+    const {
+      startDate,
+      endDate,
+      project,
+      tags
+    } = filters;
+
+    let conditions = ['user_id = $1'];
+    let params = [userId];
+    let paramCount = 1;
+
+    if (startDate) {
+      paramCount++;
+      conditions.push(`start_time >= $${paramCount}`);
+      params.push(startDate);
+    }
+    if (endDate) {
+      paramCount++;
+      conditions.push(`start_time <= $${paramCount}`);
+      params.push(endDate);
+    }
+    if (project) {
+      paramCount++;
+      conditions.push(`project = $${paramCount}`);
+      params.push(project);
+    }
+    if (tags && tags.length > 0) {
+      const tagConditions = tags.map(tag => {
+        paramCount++;
+        params.push(JSON.stringify([tag]));
+        return `context_data->'tags' @> $${paramCount}`;
+      }).join(' OR ');
+      conditions.push(`(${tagConditions})`);
+    }
+
+    const query = `
+      SELECT
+        COUNT(*) as total_sessions,
+        COUNT(*) FILTER (WHERE end_time IS NOT NULL) as completed_sessions,
+        COUNT(*) FILTER (WHERE end_time IS NULL) as active_sessions,
+        COALESCE(SUM(xp_earned), 0) as total_xp,
+        COALESCE(SUM(tokens_saved), 0) as total_tokens_saved,
+        COALESCE(SUM(tasks_completed), 0) as total_tasks,
+        COALESCE(SUM(perfect_executions), 0) as total_perfect_executions,
+        COALESCE(AVG(efficiency_multiplier), 0) as avg_efficiency,
+        COALESCE(MAX(efficiency_multiplier), 0) as max_efficiency,
+        COALESCE(AVG(duration_seconds), 0) as avg_duration_seconds,
+        COALESCE(MAX(xp_earned), 0) as max_xp_session,
+        MIN(start_time) as earliest_session,
+        MAX(start_time) as latest_session,
+        COUNT(DISTINCT project) as unique_projects
+      FROM boss_claude.sessions
+      WHERE ${conditions.join(' AND ')}
+    `;
+
+    const result = await queryWithTimeout(this.pool, query, params);
+    return result.rows[0];
+  }
+
+  /**
+   * Get top performing sessions
+   * @param {string} userId - User identifier
+   * @param {Object} options - Query options
+   * @returns {Promise<Array>} Top sessions by metric
+   */
+  async getTopSessions(userId, options = {}) {
+    const {
+      metric = 'xp_earned', // xp_earned, tokens_saved, efficiency_multiplier, tasks_completed
+      limit = 10,
+      startDate,
+      endDate
+    } = options;
+
+    const validMetrics = ['xp_earned', 'tokens_saved', 'efficiency_multiplier', 'tasks_completed'];
+    if (!validMetrics.includes(metric)) {
+      throw new Error(`Invalid metric: ${metric}. Must be one of: ${validMetrics.join(', ')}`);
+    }
+
+    let conditions = ['user_id = $1', 'end_time IS NOT NULL'];
+    let params = [userId];
+    let paramCount = 1;
+
+    if (startDate) {
+      paramCount++;
+      conditions.push(`start_time >= $${paramCount}`);
+      params.push(startDate);
+    }
+    if (endDate) {
+      paramCount++;
+      conditions.push(`start_time <= $${paramCount}`);
+      params.push(endDate);
+    }
+
+    const query = `
+      SELECT
+        id,
+        project,
+        start_time,
+        end_time,
+        duration_seconds,
+        xp_earned,
+        tokens_saved,
+        tasks_completed,
+        perfect_executions,
+        efficiency_multiplier,
+        summary,
+        context_data
+      FROM boss_claude.sessions
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY ${metric} DESC, start_time DESC
+      LIMIT $${paramCount + 1}
+    `;
+
+    params.push(limit);
+
+    const result = await queryWithTimeout(this.pool, query, params);
+    return result.rows;
+  }
+
+  /**
+   * Close the connection pool
+   */
+  async close() {
+    try {
+      if (pool) {
+        await pool.end();
+        pool = null;
+      }
+    } catch (error) {
+      console.error('[PostgresMemoryEngineer] Error closing pool:', error);
+      throw error;
+    }
+  }
+}
+
+/**
+ * Factory function to create a PostgreSQL Memory Engineer instance
+ */
+export function createPostgresMemoryEngineer() {
+  return new PostgresMemoryEngineer();
+}
+
+export default PostgresMemoryEngineer;