@cpretzinger/boss-claude 1.0.0 → 1.0.2

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

@@ -0,0 +1,251 @@
+/**
+ * GitHub Memory Engineer
+ *
+ * Long-term memory archive using GitHub Issues API
+ * - Async search with timeout handling (5s max)
+ * - Retry logic for failed requests
+ * - Integration with lib/memory.js functions
+ *
+ * @module lib/agents/memory-engineers/github-memory-engineer
+ */
+
+import { saveMemory, searchMemory, getMemoryByIssue } from '../../memory.js';
+
+const DEFAULT_TIMEOUT = 5000; // 5 seconds
+const MAX_RETRIES = 3;
+const RETRY_DELAY = 1000; // 1 second
+
+/**
+ * Sleep utility for retry delays
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Wraps a promise with timeout
+ * FIX: Clear timeout to prevent race condition and memory leak
+ */
+function withTimeout(promise, timeoutMs = DEFAULT_TIMEOUT) {
+  let timeoutHandle;
+
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutHandle = setTimeout(() => reject(new Error(`Operation timed out after ${timeoutMs}ms`)), timeoutMs);
+  });
+
+  return Promise.race([
+    promise.then(result => {
+      clearTimeout(timeoutHandle);
+      return result;
+    }).catch(error => {
+      clearTimeout(timeoutHandle);
+      throw error;
+    }),
+    timeoutPromise
+  ]);
+}
+
+/**
+ * Executes function with retry logic
+ */
+async function withRetry(fn, retries = MAX_RETRIES, delay = RETRY_DELAY) {
+  let lastError;
+
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      if (attempt < retries) {
+        console.warn(`Attempt ${attempt} failed: ${error.message}. Retrying in ${delay}ms...`);
+        await sleep(delay);
+        // FIX: Add jitter to prevent thundering herd
+        // Exponential backoff with +/- 25% jitter
+        const jitter = delay * 0.25 * (Math.random() * 2 - 1);
+        delay = (delay * 2) + jitter;
+      }
+    }
+  }
+
+  throw new Error(`Failed after ${retries} attempts: ${lastError.message}`);
+}
+
+/**
+ * GitHub Memory Engineer Class
+ */
+export class GitHubMemoryEngineer {
+  constructor(options = {}) {
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+    this.maxRetries = options.maxRetries || MAX_RETRIES;
+    this.retryDelay = options.retryDelay || RETRY_DELAY;
+  }
+
+  /**
+   * Archive a session to GitHub Issues
+   *
+   * @param {Object} sessionData - Session data to archive
+   * @param {string} sessionData.repo_name - Repository/project name
+   * @param {string} sessionData.summary - Brief summary of session
+   * @param {string} sessionData.content - Full session content (JSON string)
+   * @param {string[]} sessionData.tags - Optional tags for categorization
+   * @returns {Promise<Object>} Created issue details
+   */
+  async archiveSession(sessionData) {
+    const operation = () => saveMemory(sessionData);
+
+    try {
+      const result = await withTimeout(
+        withRetry(operation, this.maxRetries, this.retryDelay),
+        this.timeout
+      );
+
+      return {
+        success: true,
+        ...result
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message,
+        operation: 'archiveSession'
+      };
+    }
+  }
+
+  /**
+   * Search GitHub Issues for relevant memories
+   *
+   * @param {string} query - Search query
+   * @param {number} limit - Maximum number of results (default: 5)
+   * @returns {Promise<Object>} Search results with memories
+   */
+  async searchArchive(query, limit = 5) {
+    const operation = () => searchMemory(query, limit);
+
+    try {
+      const results = await withTimeout(
+        withRetry(operation, this.maxRetries, this.retryDelay),
+        this.timeout
+      );
+
+      return {
+        success: true,
+        query,
+        count: results.length,
+        memories: results
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message,
+        query,
+        operation: 'searchArchive'
+      };
+    }
+  }
+
+  /**
+   * Retrieve specific memory by issue number
+   *
+   * @param {number} issueNumber - GitHub issue number
+   * @returns {Promise<Object>} Memory details
+   */
+  async retrieveMemory(issueNumber) {
+    const operation = () => getMemoryByIssue(issueNumber);
+
+    try {
+      const memory = await withTimeout(
+        withRetry(operation, this.maxRetries, this.retryDelay),
+        this.timeout
+      );
+
+      return {
+        success: true,
+        memory
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message,
+        issueNumber,
+        operation: 'retrieveMemory'
+      };
+    }
+  }
+
+  /**
+   * Health check - verifies GitHub API connectivity
+   *
+   * @returns {Promise<Object>} Health status
+   */
+  async healthCheck() {
+    try {
+      // Quick search with minimal timeout
+      const result = await withTimeout(
+        searchMemory('test', 1),
+        2000 // 2 second timeout for health check
+      );
+
+      return {
+        success: true,
+        status: 'healthy',
+        message: 'GitHub API connection successful'
+      };
+    } catch (error) {
+      return {
+        success: false,
+        status: 'unhealthy',
+        error: error.message
+      };
+    }
+  }
+
+  /**
+   * Batch archive multiple sessions
+   *
+   * @param {Object[]} sessions - Array of session data objects
+   * @returns {Promise<Object>} Batch operation results
+   */
+  async batchArchive(sessions) {
+    const results = {
+      success: [],
+      failed: [],
+      total: sessions.length
+    };
+
+    for (const session of sessions) {
+      const result = await this.archiveSession(session);
+
+      if (result.success) {
+        results.success.push({
+          repo_name: session.repo_name,
+          issue_number: result.issue_number,
+          url: result.url
+        });
+      } else {
+        results.failed.push({
+          repo_name: session.repo_name,
+          error: result.error
+        });
+      }
+    }
+
+    return {
+      success: results.failed.length === 0,
+      ...results
+    };
+  }
+}
+
+/**
+ * Factory function to create GitHub Memory Engineer instance
+ */
+export function createGitHubMemoryEngineer(options) {
+  return new GitHubMemoryEngineer(options);
+}
+
+/**
+ * Default export
+ */
+export default GitHubMemoryEngineer;