@cpretzinger/boss-claude 1.0.0 → 1.0.2

package/lib/agents/memory-supervisor.js

@@ -0,0 +1,526 @@
+/**
+ * MEMORY SUPERVISOR AGENT
+ *
+ * Boss-level coordinator that queries 4 specialized engineer agents in PARALLEL
+ * to retrieve comprehensive memory data across multiple domains.
+ *
+ * Architecture:
+ * - Redis cache-first strategy (5-minute TTL)
+ * - Parallel queries to 4 domain engineers
+ * - 5-second timeout for all operations
+ * - Result aggregation and ranking
+ * - Automatic cache invalidation on updates
+ *
+ * Engineers:
+ * 1. PostgresMemoryEngineer - Database sessions with full-text search
+ * 2. RedisMemoryEngineer - Fast cache layer for recent sessions
+ * 3. QdrantMemoryEngineer - Vector similarity search (semantic)
+ * 4. GitHubMemoryEngineer - Long-term archive in GitHub Issues
+ */
+
+import Redis from 'ioredis';
+import crypto from 'crypto';
+import dotenv from 'dotenv';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync } from 'fs';
+import os from 'os';
+
+// Import real memory engineers
+import { PostgresMemoryEngineer } from './memory-engineers/postgres-memory-engineer.js';
+import { RedisMemoryEngineer } from './memory-engineers/redis-memory-engineer.js';
+import { getQdrantMemoryEngineer } from './memory-engineers/qdrant-memory-engineer.js';
+import { GitHubMemoryEngineer } from './memory-engineers/github-memory-engineer.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Load environment variables
+const envPath = join(os.homedir(), '.boss-claude', '.env');
+if (existsSync(envPath)) {
+  dotenv.config({ path: envPath });
+}
+
+// Redis client singleton
+let redis = null;
+
+function getRedis() {
+  if (!redis) {
+    if (!process.env.REDIS_URL) {
+      throw new Error('REDIS_URL not found. Please run: boss-claude init');
+    }
+    redis = new Redis(process.env.REDIS_URL);
+  }
+  return redis;
+}
+
+/**
+ * Generate cache key for a query
+ */
+function generateCacheKey(query, options = {}) {
+  const hashInput = JSON.stringify({ query, ...options });
+  const hash = crypto.createHash('sha256').update(hashInput).digest('hex').slice(0, 16);
+  return `boss:cache:memory:${hash}`;
+}
+
+/**
+ * Real engineer agent instances
+ * Lazy-loaded to avoid circular dependency issues
+ */
+let postgresEngineer = null;
+let redisEngineer = null;
+let qdrantEngineer = null;
+let githubEngineer = null;
+
+function getEngineers() {
+  if (!postgresEngineer) {
+    postgresEngineer = new PostgresMemoryEngineer();
+    redisEngineer = new RedisMemoryEngineer();
+    qdrantEngineer = getQdrantMemoryEngineer();
+    githubEngineer = new GitHubMemoryEngineer();
+  }
+  return { postgresEngineer, redisEngineer, qdrantEngineer, githubEngineer };
+}
+
+/**
+ * Get user ID from environment or default
+ */
+function getUserId() {
+  return process.env.USER_ID || process.env.USER || 'default-user';
+}
+
+async function queryPostgresEngineer(query, timeout = 5000) {
+  return Promise.race([
+    (async () => {
+      try {
+        const userId = getUserId();
+        // Full-text search on session summaries and context data
+        const results = await postgresEngineer.fullTextSearch(userId, query, { limit: 5 });
+
+        return {
+          engineer: 'postgres-n8n-specialist',
+          domain: 'postgres',
+          results: results.map(r => ({
+            id: r.id,
+            title: `Session: ${r.project || 'Unknown'}`,
+            summary: r.summary || '',
+            url: `postgres://session/${r.id}`,
+            created_at: r.start_time,
+            labels: r.context_data?.tags || [],
+            relevance: calculateRelevance(query, {
+              title: r.project || '',
+              summary: r.summary || '',
+              labels: r.context_data?.tags || [],
+              created_at: r.start_time
+            }),
+            source: 'postgres-engineer',
+            metadata: {
+              xp_earned: r.xp_earned,
+              tokens_saved: r.tokens_saved,
+              duration_seconds: r.duration_seconds
+            }
+          }))
+        };
+      } catch (err) {
+        console.error('[Postgres Engineer] Error:', err.message);
+        return {
+          engineer: 'postgres-n8n-specialist',
+          domain: 'postgres',
+          error: err.message,
+          results: []
+        };
+      }
+    })(),
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('Postgres engineer timeout')), timeout)
+    )
+  ]).catch(err => ({
+    engineer: 'postgres-n8n-specialist',
+    domain: 'postgres',
+    error: err.message,
+    results: []
+  }));
+}
+
+async function queryRedisEngineer(query, timeout = 5000) {
+  return Promise.race([
+    (async () => {
+      try {
+        // Query Redis cache for recent sessions
+        const response = await redisEngineer.query(query, {}, 5);
+
+        return {
+          engineer: 'redis-architect',
+          domain: 'redis',
+          results: response.results.map(r => ({
+            id: r.id || r.session_id,
+            title: `Session: ${r.repo?.name || r.project || 'Unknown'}`,
+            summary: r.summary || '',
+            url: `redis://session/${r.id || r.session_id}`,
+            created_at: r.started_at || r.timestamp,
+            labels: r.tags || [],
+            relevance: calculateRelevance(query, {
+              title: r.repo?.name || r.project || '',
+              summary: r.summary || '',
+              labels: r.tags || [],
+              created_at: r.started_at || r.timestamp
+            }),
+            source: 'redis-engineer',
+            cache_source: response.source
+          }))
+        };
+      } catch (err) {
+        console.error('[Redis Engineer] Error:', err.message);
+        return {
+          engineer: 'redis-architect',
+          domain: 'redis',
+          error: err.message,
+          results: []
+        };
+      }
+    })(),
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('Redis engineer timeout')), timeout)
+    )
+  ]).catch(err => ({
+    engineer: 'redis-architect',
+    domain: 'redis',
+    error: err.message,
+    results: []
+  }));
+}
+
+async function queryQdrantEngineer(query, timeout = 5000) {
+  return Promise.race([
+    (async () => {
+      try {
+        // Vector similarity search
+        const results = await qdrantEngineer.searchSimilar(query, 5, 0.7);
+
+        return {
+          engineer: 'qdrant-vector-specialist',
+          domain: 'qdrant',
+          results: results.map(r => ({
+            id: r.id,
+            title: `Vector Match: ${r.metadata.title || 'Memory'}`,
+            summary: r.text || '',
+            url: `qdrant://vector/${r.id}`,
+            created_at: r.metadata.stored_at,
+            labels: r.metadata.tags || [],
+            relevance: Math.round(r.score * 10), // Scale 0-1 to 0-10
+            source: 'qdrant-engineer',
+            vector_score: r.score
+          }))
+        };
+      } catch (err) {
+        console.error('[Qdrant Engineer] Error:', err.message);
+        return {
+          engineer: 'qdrant-vector-specialist',
+          domain: 'qdrant',
+          error: err.message,
+          results: []
+        };
+      }
+    })(),
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('Qdrant engineer timeout')), timeout)
+    )
+  ]).catch(err => ({
+    engineer: 'qdrant-vector-specialist',
+    domain: 'qdrant',
+    error: err.message,
+    results: []
+  }));
+}
+
+async function queryGitHubEngineer(query, timeout = 5000) {
+  return Promise.race([
+    (async () => {
+      try {
+        // Search GitHub Issues archive
+        const response = await githubEngineer.searchArchive(query, 5);
+
+        if (!response.success) {
+          throw new Error(response.error);
+        }
+
+        return {
+          engineer: 'github-expert',
+          domain: 'github',
+          results: response.memories.map(r => ({
+            id: r.issue_number,
+            title: r.title || '',
+            summary: r.summary || '',
+            url: r.url,
+            created_at: r.created_at,
+            labels: r.labels || [],
+            relevance: calculateRelevance(query, r),
+            source: 'github-engineer'
+          }))
+        };
+      } catch (err) {
+        console.error('[GitHub Engineer] Error:', err.message);
+        return {
+          engineer: 'github-expert',
+          domain: 'github',
+          error: err.message,
+          results: []
+        };
+      }
+    })(),
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('GitHub engineer timeout')), timeout)
+    )
+  ]).catch(err => ({
+    engineer: 'github-expert',
+    domain: 'github',
+    error: err.message,
+    results: []
+  }));
+}
+
+/**
+ * Calculate relevance score for a memory result
+ */
+function calculateRelevance(query, result) {
+  const queryLower = query.toLowerCase();
+  const titleLower = result.title.toLowerCase();
+  const summaryLower = (result.summary || '').toLowerCase();
+
+  let score = 0;
+
+  // Exact title match: +10
+  if (titleLower.includes(queryLower)) {
+    score += 10;
+  }
+
+  // Summary match: +5
+  if (summaryLower.includes(queryLower)) {
+    score += 5;
+  }
+
+  // Label match: +3 per label
+  if (result.labels) {
+    result.labels.forEach(label => {
+      if (label.toLowerCase().includes(queryLower)) {
+        score += 3;
+      }
+    });
+  }
+
+  // Recency bonus (newer = higher score)
+  if (result.created_at) {
+    const ageInDays = (Date.now() - new Date(result.created_at).getTime()) / (1000 * 60 * 60 * 24);
+    if (ageInDays < 7) score += 5;
+    else if (ageInDays < 30) score += 3;
+    else if (ageInDays < 90) score += 1;
+  }
+
+  return score;
+}
+
+/**
+ * Aggregate and rank results from all engineers
+ */
+function aggregateResults(engineerResponses) {
+  const allResults = [];
+  const seenUrls = new Set();
+
+  // Collect all unique results
+  engineerResponses.forEach(response => {
+    if (response.results && response.results.length > 0) {
+      response.results.forEach(result => {
+        if (!seenUrls.has(result.url)) {
+          seenUrls.add(result.url);
+          allResults.push({
+            ...result,
+            engineer: response.engineer,
+            domain: response.domain
+          });
+        }
+      });
+    }
+  });
+
+  // Sort by relevance score (descending)
+  allResults.sort((a, b) => (b.relevance || 0) - (a.relevance || 0));
+
+  return allResults;
+}
+
+/**
+ * Main supervisor query function
+ *
+ * @param {string} query - Search query
+ * @param {object} options - Query options
+ * @param {boolean} options.useCache - Use Redis cache (default: true)
+ * @param {number} options.timeout - Engineer timeout in ms (default: 5000)
+ * @param {number} options.cacheTtl - Cache TTL in seconds (default: 300 = 5 min)
+ * @param {number} options.limit - Max results to return (default: 10)
+ * @returns {object} Aggregated memory results with metadata
+ */
+export async function queryMemorySupervisor(query, options = {}) {
+  const {
+    useCache = true,
+    timeout = 5000,
+    cacheTtl = 300, // 5 minutes
+    limit = 10
+  } = options;
+
+  const startTime = Date.now();
+  const client = getRedis();
+  const cacheKey = generateCacheKey(query, { limit });
+
+  // Step 1: Check Redis cache
+  if (useCache) {
+    try {
+      const cached = await client.get(cacheKey);
+      if (cached) {
+        const cachedData = JSON.parse(cached);
+        return {
+          ...cachedData,
+          cache_hit: true,
+          query_time_ms: Date.now() - startTime,
+          cached_at: cachedData.timestamp
+        };
+      }
+    } catch (err) {
+      console.warn('Cache read error:', err.message);
+      // Continue with fresh query on cache error
+    }
+  }
+
+  // Step 2: Cache miss - spawn parallel queries to all 4 engineers
+  console.log(`[Memory Supervisor] Cache miss for: "${query}"`);
+  console.log('[Memory Supervisor] Querying 4 engineers in parallel...');
+
+  const engineerPromises = [
+    queryPostgresEngineer(query, timeout),
+    queryRedisEngineer(query, timeout),
+    queryQdrantEngineer(query, timeout),
+    queryGitHubEngineer(query, timeout)
+  ];
+
+  // Wait for all engineers (with individual timeouts)
+  const engineerResponses = await Promise.all(engineerPromises);
+
+  // Step 3: Aggregate results
+  const aggregated = aggregateResults(engineerResponses);
+  const topResults = aggregated.slice(0, limit);
+
+  // Step 4: Build response
+  const response = {
+    query,
+    results: topResults,
+    total_results: aggregated.length,
+    engineers_queried: engineerResponses.map(r => ({
+      name: r.engineer,
+      domain: r.domain,
+      result_count: r.results?.length || 0,
+      error: r.error || null
+    })),
+    query_time_ms: Date.now() - startTime,
+    timestamp: new Date().toISOString(),
+    cache_hit: false
+  };
+
+  // Step 5: Cache the results
+  if (useCache) {
+    try {
+      await client.setex(cacheKey, cacheTtl, JSON.stringify(response));
+      console.log(`[Memory Supervisor] Cached results (TTL: ${cacheTtl}s)`);
+    } catch (err) {
+      console.warn('Cache write error:', err.message);
+      // Continue even if caching fails
+    }
+  }
+
+  return response;
+}
+
+/**
+ * Invalidate cache for a specific query or all memory caches
+ */
+export async function invalidateMemoryCache(query = null) {
+  const client = getRedis();
+
+  if (query) {
+    // Invalidate specific query
+    const cacheKey = generateCacheKey(query);
+    await client.del(cacheKey);
+    console.log(`[Memory Supervisor] Invalidated cache for: "${query}"`);
+  } else {
+    // Invalidate all memory caches
+    const keys = await client.keys('boss:cache:memory:*');
+    if (keys.length > 0) {
+      await client.del(...keys);
+      console.log(`[Memory Supervisor] Invalidated ${keys.length} cache entries`);
+    }
+  }
+}
+
+/**
+ * Get cache statistics
+ */
+export async function getMemoryCacheStats() {
+  const client = getRedis();
+  const keys = await client.keys('boss:cache:memory:*');
+
+  const stats = {
+    total_cached_queries: keys.length,
+    cache_keys: []
+  };
+
+  for (const key of keys) {
+    const ttl = await client.ttl(key);
+    const data = await client.get(key);
+    if (data) {
+      const parsed = JSON.parse(data);
+      stats.cache_keys.push({
+        key: key.replace('boss:cache:memory:', ''),
+        query: parsed.query,
+        result_count: parsed.total_results,
+        ttl_remaining: ttl,
+        cached_at: parsed.timestamp
+      });
+    }
+  }
+
+  return stats;
+}
+
+/**
+ * Close all Redis connections (cleanup)
+ */
+export async function closeConnections() {
+  try {
+    if (redis) {
+      await redis.quit();
+      redis = null;
+      console.log('[Memory Supervisor] Closed Redis connection');
+    }
+
+    // Close engineer connections
+    if (redisEngineer && redisEngineer.close) {
+      await redisEngineer.close();
+    }
+    if (postgresEngineer && postgresEngineer.close) {
+      await postgresEngineer.close();
+    }
+    if (qdrantEngineer && qdrantEngineer.close) {
+      await qdrantEngineer.close();
+    }
+    if (githubEngineer && githubEngineer.close) {
+      await githubEngineer.close();
+    }
+  } catch (err) {
+    console.warn('[Memory Supervisor] Cleanup error:', err.message);
+  }
+}
+
+export default {
+  queryMemorySupervisor,
+  invalidateMemoryCache,
+  getMemoryCacheStats,
+  closeConnections
+};

package/lib/agents/registry.js

@@ -0,0 +1,135 @@
+/**
+ * AGENT HIERARCHY REGISTRY
+ *
+ * Defines the canonical mapping of worker agents to their boss agents.
+ * This ensures proper delegation and review chain enforcement.
+ *
+ * Source: AGENT-HIERARCHY-CANON.md
+ */
+
+export const AGENT_HIERARCHY = {
+  /**
+   * Tier 1: Worker Agents (Domain Specialists)
+   * Each worker has an assigned boss who reviews their work
+   */
+  workers: {
+    'n8n-workflow-architect': {
+      boss: 'Boss N8N',
+      domain: 'n8n',
+      description: 'Creates n8n workflows and automations'
+    },
+    'postgres-n8n-specialist': {
+      boss: 'Boss Postgres',
+      domain: 'postgres',
+      description: 'Database queries and PostgreSQL schema'
+    },
+    'redis-architect': {
+      boss: 'Boss Redis',
+      domain: 'redis',
+      description: 'Redis architecture and optimization'
+    },
+    'github-expert': {
+      boss: 'Boss GitHub',
+      domain: 'github',
+      description: 'GitHub operations and CI/CD'
+    },
+    'automation-architect': {
+      boss: 'Boss GitHub',
+      domain: 'automation',
+      description: 'CI/CD and automation infrastructure'
+    },
+    'openai-streaming-expert': {
+      boss: 'Boss OpenAI',
+      domain: 'openai',
+      description: 'OpenAI API integration and streaming'
+    },
+    'data-science-pipeline': {
+      boss: 'Boss Postgres',
+      domain: 'data-science',
+      description: 'ML and data analysis pipelines'
+    }
+  },
+
+  /**
+   * Tier 2: Boss Agents (Domain + Security Reviewers)
+   * Review worker output for bugs and security issues
+   */
+  bosses: {
+    'Boss N8N': {
+      metaBoss: 'Boss Claude',
+      domain: 'n8n',
+      workers: ['n8n-workflow-architect'],
+      description: 'Reviews n8n workflows for security and correctness'
+    },
+    'Boss Postgres': {
+      metaBoss: 'Boss Claude',
+      domain: 'postgres',
+      workers: ['postgres-n8n-specialist', 'data-science-pipeline'],
+      description: 'Reviews database queries and schema changes'
+    },
+    'Boss Redis': {
+      metaBoss: 'Boss Claude',
+      domain: 'redis',
+      workers: ['redis-architect'],
+      description: 'Reviews Redis configuration and optimization'
+    },
+    'Boss GitHub': {
+      metaBoss: 'Boss Claude',
+      domain: 'github',
+      workers: ['github-expert', 'automation-architect'],
+      description: 'Reviews GitHub operations and automation'
+    },
+    'Boss OpenAI': {
+      metaBoss: 'Boss Claude',
+      domain: 'openai',
+      workers: ['openai-streaming-expert'],
+      description: 'Reviews OpenAI integrations for correctness'
+    }
+  },
+
+  /**
+   * Tier 3: Meta-Boss (Final Security Gate)
+   * Cross-domain security review and final approval
+   */
+  metaBoss: 'Boss Claude',
+
+  /**
+   * Helper function: Get boss for a worker agent
+   */
+  getBossForWorker(workerName) {
+    const worker = this.workers[workerName];
+    if (!worker) {
+      throw new Error(`Unknown worker agent: ${workerName}`);
+    }
+    return this.bosses[worker.boss];
+  },
+
+  /**
+   * Helper function: Get all workers under a boss
+   */
+  getWorkersUnderBoss(bossName) {
+    const boss = this.bosses[bossName];
+    if (!boss) {
+      throw new Error(`Unknown boss agent: ${bossName}`);
+    }
+    return boss.workers.map(w => this.workers[w]);
+  },
+
+  /**
+   * Helper function: Validate hierarchy chain
+   * Returns true if worker -> boss -> metaboss chain is valid
+   */
+  validateChain(workerName, bossName, metaBossName = 'Boss Claude') {
+    const worker = this.workers[workerName];
+    if (!worker) return false;
+
+    const boss = this.bosses[bossName];
+    if (!boss) return false;
+
+    if (boss.metaBoss !== metaBossName) return false;
+
+    return worker.boss === bossName;
+  }
+};
+
+export default AGENT_HIERARCHY;