clearctx 3.0.0

package/src/team-hub.js

@@ -0,0 +1,615 @@
+/**
+ * TeamHub - Layer 1 Chat System for clearctx
+ *
+ * This class manages team-based messaging between Claude sessions.
+ * It handles:
+ * - Team roster (who's in the team)
+ * - Direct messaging between members
+ * - Broadcast messages to all members
+ * - Ask/reply system for synchronous questions
+ * - Inbox management and compaction
+ *
+ * @class TeamHub
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+// Import our atomic file operations
+const { atomicWriteJson, readJsonSafe, appendJsonl } = require('./atomic-io');
+const { acquireLock, releaseLock } = require('./file-lock');
+
+/**
+ * TeamHub class - manages team communication and roster
+ */
+class TeamHub {
+  /**
+   * Creates a new TeamHub instance
+   *
+   * @param {string} teamName - Name of the team (default: 'default')
+   */
+  constructor(teamName = 'default') {
+    // Set the team name
+    this.teamName = teamName;
+
+    // Create the base directory path: ~/.clearctx
+    const baseDir = path.join(os.homedir(), '.clearctx');
+
+    // Create the team directory path: ~/.clearctx/team/{teamName}
+    this.teamDir = path.join(baseDir, 'team', teamName);
+
+    // Create subdirectories for inbox and asks if they don't exist
+    const inboxDir = path.join(this.teamDir, 'inbox');
+    const asksDir = path.join(this.teamDir, 'asks');
+
+    // Create locks directory for roster locking
+    this.locksDir = path.join(baseDir, 'team', teamName, 'locks');
+
+    // Make sure all directories exist
+    fs.mkdirSync(inboxDir, { recursive: true });
+    fs.mkdirSync(asksDir, { recursive: true });
+    fs.mkdirSync(this.locksDir, { recursive: true });
+
+    // Rate limiting: track message counts per sender
+    // Map structure: { senderName: { count: number, windowStart: timestamp } }
+    this.rateLimitMap = new Map();
+
+    // Loop detection: track exchanges between pairs
+    // Map structure: { 'sender:receiver': [ timestamps ] }
+    this.loopDetectionMap = new Map();
+  }
+
+  // ========== ROSTER METHODS ==========
+
+  /**
+   * Get the current team roster
+   *
+   * @returns {Array} Array of team member objects
+   */
+  getRoster() {
+    const rosterPath = path.join(this.teamDir, 'roster.json');
+    // readJsonSafe returns empty array if file doesn't exist
+    const data = readJsonSafe(rosterPath, []);
+    // Defensive: ensure we always return an array, even if file contains {}
+    return Array.isArray(data) ? data : [];
+  }
+
+  /**
+   * Add a new member to the team
+   *
+   * @param {string} name - Member name (unique identifier)
+   * @param {Object} options - Member details
+   * @param {string} options.role - Member's role in the team
+   * @param {string} options.task - Member's current task
+   * @param {string} options.model - AI model being used (e.g., 'sonnet', 'opus')
+   */
+  joinTeam(name, { role, task, model }) {
+    // Acquire lock for roster modification
+    acquireLock(this.locksDir, 'roster');
+
+    try {
+      // Get current roster
+      const roster = this.getRoster();
+
+      // Create new member entry with all required fields
+      const newMember = {
+        name,
+        role,
+        task,
+        model,
+        status: 'active',
+        joinedAt: new Date().toISOString(),
+        lastSeen: new Date().toISOString()
+      };
+
+      // Remove existing entry if member is rejoining
+      const filtered = roster.filter(m => m.name !== name);
+
+      // Add the new member
+      filtered.push(newMember);
+
+      // Save the updated roster
+      const rosterPath = path.join(this.teamDir, 'roster.json');
+      atomicWriteJson(rosterPath, filtered);
+    } finally {
+      // Always release the lock
+      releaseLock(this.locksDir, 'roster');
+    }
+  }
+
+  /**
+   * Remove a member from the team
+   *
+   * @param {string} name - Name of member to remove
+   */
+  leaveTeam(name) {
+    // Acquire lock for roster modification
+    acquireLock(this.locksDir, 'roster');
+
+    try {
+      // Get current roster
+      const roster = this.getRoster();
+
+      // Filter out the member
+      const filtered = roster.filter(m => m.name !== name);
+
+      // Save the updated roster
+      const rosterPath = path.join(this.teamDir, 'roster.json');
+      atomicWriteJson(rosterPath, filtered);
+    } finally {
+      // Always release the lock
+      releaseLock(this.locksDir, 'roster');
+    }
+  }
+
+  /**
+   * Update a member's information
+   *
+   * @param {string} name - Name of member to update
+   * @param {Object} updates - Fields to update (status, task, role, etc.)
+   */
+  updateMember(name, updates) {
+    // Acquire lock for roster modification
+    acquireLock(this.locksDir, 'roster');
+
+    try {
+      // Get current roster
+      const roster = this.getRoster();
+
+      // Find and update the member
+      const updated = roster.map(member => {
+        if (member.name === name) {
+          // Merge updates into existing member object
+          return { ...member, ...updates };
+        }
+        return member;
+      });
+
+      // Save the updated roster
+      const rosterPath = path.join(this.teamDir, 'roster.json');
+      atomicWriteJson(rosterPath, updated);
+    } finally {
+      // Always release the lock
+      releaseLock(this.locksDir, 'roster');
+    }
+  }
+
+  /**
+   * Update a member's lastSeen timestamp to now
+   *
+   * @param {string} name - Name of member
+   */
+  touchLastSeen(name) {
+    this.updateMember(name, { lastSeen: new Date().toISOString() });
+  }
+
+  // ========== MESSAGING METHODS ==========
+
+  /**
+   * Check rate limits for a sender
+   * Max 10 messages per minute
+   *
+   * @param {string} from - Sender name
+   * @throws {Error} If rate limit exceeded
+   */
+  _checkRateLimit(from) {
+    const now = Date.now();
+    const windowSize = 60000; // 60 seconds in milliseconds
+    const maxMessages = 10;
+
+    // Get or create rate limit entry for this sender
+    let rateLimitEntry = this.rateLimitMap.get(from);
+
+    if (!rateLimitEntry) {
+      // First message from this sender
+      rateLimitEntry = { count: 0, windowStart: now };
+      this.rateLimitMap.set(from, rateLimitEntry);
+    }
+
+    // Check if we need to reset the window
+    if (now - rateLimitEntry.windowStart > windowSize) {
+      // Window expired, reset
+      rateLimitEntry.count = 0;
+      rateLimitEntry.windowStart = now;
+    }
+
+    // Check if limit exceeded
+    if (rateLimitEntry.count >= maxMessages) {
+      throw new Error(`Rate limit exceeded for ${from}: max ${maxMessages} messages per minute`);
+    }
+
+    // Increment counter
+    rateLimitEntry.count++;
+  }
+
+  /**
+   * Check for messaging loops between two parties
+   * Max 5 messages between same pair in 60 seconds
+   *
+   * @param {string} from - Sender name
+   * @param {string} to - Receiver name
+   * @throws {Error} If loop detected
+   */
+  _checkLoopDetection(from, to) {
+    const now = Date.now();
+    const windowSize = 60000; // 60 seconds
+    const maxExchanges = 5;
+
+    // Create a consistent key for this pair (alphabetically sorted)
+    const pair = [from, to].sort().join(':');
+
+    // Get or create exchange history for this pair
+    let exchanges = this.loopDetectionMap.get(pair);
+
+    if (!exchanges) {
+      exchanges = [];
+      this.loopDetectionMap.set(pair, exchanges);
+    }
+
+    // Remove old timestamps outside the window
+    exchanges = exchanges.filter(timestamp => now - timestamp < windowSize);
+    this.loopDetectionMap.set(pair, exchanges);
+
+    // Check if too many exchanges
+    if (exchanges.length >= maxExchanges) {
+      throw new Error(`Loop detected: too many exchanges between ${from} and ${to} (max ${maxExchanges} per minute)`);
+    }
+
+    // Add this exchange
+    exchanges.push(now);
+  }
+
+  /**
+   * Send a direct message to a specific team member
+   *
+   * @param {string} from - Sender name
+   * @param {string} to - Recipient name
+   * @param {string} content - Message content
+   * @param {Object} options - Message options
+   * @param {string} options.priority - Priority level ('normal' or 'urgent')
+   * @returns {Object} The created message object
+   */
+  sendDirect(from, to, content, { priority = 'normal' } = {}) {
+    // Check rate limits and loop detection
+    this._checkRateLimit(from);
+    this._checkLoopDetection(from, to);
+
+    // Create the message object
+    const message = {
+      id: crypto.randomUUID(),
+      from,
+      to,
+      type: 'direct',
+      content,
+      timestamp: new Date().toISOString(),
+      status: 'pending',
+      priority
+    };
+
+    // Append to recipient's inbox
+    const inboxPath = path.join(this.teamDir, 'inbox', `${to}.jsonl`);
+    appendJsonl(inboxPath, message);
+
+    return message;
+  }
+
+  /**
+   * Send a broadcast message to all team members
+   *
+   * @param {string} from - Sender name
+   * @param {string} content - Message content
+   * @param {Object} options - Message options
+   * @param {string} options.priority - Priority level ('normal' or 'urgent')
+   * @returns {Object} The created message object
+   */
+  sendBroadcast(from, content, { priority = 'normal' } = {}) {
+    // Check rate limits (loop detection doesn't apply to broadcasts)
+    this._checkRateLimit(from);
+
+    // Create the message object
+    const message = {
+      id: crypto.randomUUID(),
+      from,
+      to: 'all',
+      type: 'broadcast',
+      content,
+      timestamp: new Date().toISOString(),
+      status: 'pending',
+      priority
+    };
+
+    // Get all team members
+    const roster = this.getRoster();
+
+    // Append to every member's inbox (including sender for record-keeping)
+    for (const member of roster) {
+      const inboxPath = path.join(this.teamDir, 'inbox', `${member.name}.jsonl`);
+      appendJsonl(inboxPath, message);
+    }
+
+    return message;
+  }
+
+  // ========== INBOX METHODS ==========
+
+  /**
+   * Get messages from a member's inbox
+   *
+   * @param {string} name - Member name
+   * @param {Object} options - Inbox options
+   * @param {boolean} options.markRead - Whether to mark messages as read (default: false)
+   * @param {number} options.limit - Max number of messages to return (default: 20)
+   * @returns {Array} Array of message objects
+   */
+  getInbox(name, { markRead = false, limit = 20 } = {}) {
+    const inboxPath = path.join(this.teamDir, 'inbox', `${name}.jsonl`);
+
+    // Read the inbox file
+    let allMessages = [];
+
+    // Check if file exists
+    if (fs.existsSync(inboxPath)) {
+      // Read file and parse each line as JSON
+      const content = fs.readFileSync(inboxPath, 'utf-8');
+      const lines = content.trim().split('\n').filter(line => line.length > 0);
+
+      allMessages = lines.map(line => JSON.parse(line));
+
+      // Auto-compaction if total messages exceed 1000
+      if (allMessages.length > 1000) {
+        this.compactInbox(name);
+        // Re-read after compaction
+        const newContent = fs.readFileSync(inboxPath, 'utf-8');
+        const newLines = newContent.trim().split('\n').filter(line => line.length > 0);
+        allMessages = newLines.map(line => JSON.parse(line));
+      }
+    }
+
+    // Filter to only pending (unread) messages
+    const unreadMessages = allMessages.filter(msg => msg.status === 'pending');
+
+    // Sort by priority (urgent first), then timestamp
+    unreadMessages.sort((a, b) => {
+      // Priority comparison (urgent comes before normal)
+      if (a.priority === 'urgent' && b.priority !== 'urgent') return -1;
+      if (a.priority !== 'urgent' && b.priority === 'urgent') return 1;
+
+      // If same priority, sort by timestamp (oldest first)
+      return new Date(a.timestamp) - new Date(b.timestamp);
+    });
+
+    // Limit the results
+    const limitedMessages = unreadMessages.slice(0, limit);
+
+    // Mark as read if requested
+    if (markRead && limitedMessages.length > 0) {
+      // Create a set of IDs to mark as read
+      const idsToMark = new Set(limitedMessages.map(msg => msg.id));
+
+      // Update all messages
+      const updatedMessages = allMessages.map(msg => {
+        if (idsToMark.has(msg.id)) {
+          return { ...msg, status: 'read' };
+        }
+        return msg;
+      });
+
+      // Rewrite the file
+      const newContent = updatedMessages.map(msg => JSON.stringify(msg)).join('\n') + '\n';
+      fs.writeFileSync(inboxPath, newContent, 'utf-8');
+    }
+
+    return limitedMessages;
+  }
+
+  /**
+   * Get count of unread messages in inbox
+   *
+   * @param {string} name - Member name
+   * @returns {number} Count of unread messages
+   */
+  getUnreadCount(name) {
+    const inboxPath = path.join(this.teamDir, 'inbox', `${name}.jsonl`);
+
+    // If file doesn't exist, no unread messages
+    if (!fs.existsSync(inboxPath)) {
+      return 0;
+    }
+
+    // Read and count pending messages
+    const content = fs.readFileSync(inboxPath, 'utf-8');
+    const lines = content.trim().split('\n').filter(line => line.length > 0);
+
+    let count = 0;
+    for (const line of lines) {
+      const msg = JSON.parse(line);
+      if (msg.status === 'pending') {
+        count++;
+      }
+    }
+
+    return count;
+  }
+
+  /**
+   * Compact an inbox by removing old read messages
+   * Keeps all unread messages and the last N read messages
+   *
+   * @param {string} name - Member name
+   * @param {Object} options - Compaction options
+   * @param {number} options.keepLast - Number of read messages to keep (default: 200)
+   * @returns {Object} Object with removed and kept counts
+   */
+  compactInbox(name, { keepLast = 200 } = {}) {
+    const inboxPath = path.join(this.teamDir, 'inbox', `${name}.jsonl`);
+
+    // If file doesn't exist, nothing to compact
+    if (!fs.existsSync(inboxPath)) {
+      return { removed: 0, kept: 0 };
+    }
+
+    // Read all messages
+    const content = fs.readFileSync(inboxPath, 'utf-8');
+    const lines = content.trim().split('\n').filter(line => line.length > 0);
+    const allMessages = lines.map(line => JSON.parse(line));
+
+    // Separate unread and read messages
+    const unreadMessages = allMessages.filter(msg => msg.status === 'pending');
+    const readMessages = allMessages.filter(msg => msg.status === 'read');
+
+    // Keep only the last N read messages
+    const keptReadMessages = readMessages.slice(-keepLast);
+
+    // Combine: all unread + last N read
+    const keptMessages = [...unreadMessages, ...keptReadMessages];
+
+    // Write back to file
+    const newContent = keptMessages.map(msg => JSON.stringify(msg)).join('\n') + '\n';
+    fs.writeFileSync(inboxPath, newContent, 'utf-8');
+
+    return {
+      removed: allMessages.length - keptMessages.length,
+      kept: keptMessages.length
+    };
+  }
+
+  // ========== ASK/REPLY METHODS ==========
+
+  /**
+   * Create an ask (synchronous question) to another member
+   *
+   * @param {string} from - Asker name
+   * @param {string} to - Recipient name
+   * @param {string} question - The question text
+   * @param {number} timeout - Timeout in milliseconds (default: 30000)
+   * @returns {Object} Object with askId
+   */
+  createAsk(from, to, question, timeout = 30000) {
+    // Generate unique ID
+    const id = crypto.randomUUID();
+
+    // Create ask object
+    const ask = {
+      id,
+      from,
+      to,
+      question,
+      status: 'pending',
+      createdAt: new Date().toISOString(),
+      timeout
+    };
+
+    // Write ask file
+    const askPath = path.join(this.teamDir, 'asks', `ask_${id}.json`);
+    atomicWriteJson(askPath, ask);
+
+    // Also send as a message to recipient's inbox
+    const message = {
+      id: crypto.randomUUID(),
+      from,
+      to,
+      type: 'ask',
+      content: question,
+      askId: id,
+      timestamp: new Date().toISOString(),
+      status: 'pending',
+      priority: 'urgent' // Asks are urgent
+    };
+
+    const inboxPath = path.join(this.teamDir, 'inbox', `${to}.jsonl`);
+    appendJsonl(inboxPath, message);
+
+    return { askId: id };
+  }
+
+  /**
+   * Poll for a reply to an ask
+   * Uses exponential backoff: 1s, 2s, 4s, 8s, then 10s cap
+   *
+   * @param {string} askId - The ask ID to poll for
+   * @param {number} timeout - Total timeout in milliseconds (default: 30000)
+   * @returns {Promise<Object>} Promise that resolves with reply or timeout
+   */
+  pollForReply(askId, timeout = 30000) {
+    return new Promise((resolve) => {
+      const askPath = path.join(this.teamDir, 'asks', `ask_${askId}.json`);
+      const startTime = Date.now();
+
+      // Exponential backoff intervals: 1s, 2s, 4s, 8s, 10s cap
+      let backoffDelay = 1000; // Start with 1 second
+
+      const poll = () => {
+        // Check if timeout exceeded
+        if (Date.now() - startTime > timeout) {
+          resolve({
+            timeout: true,
+            suggestion: 'Session may be busy. Check inbox later.'
+          });
+          return;
+        }
+
+        // Try to read the ask file
+        const ask = readJsonSafe(askPath, null);
+
+        if (!ask) {
+          // File doesn't exist or can't be read
+          resolve({
+            timeout: true,
+            suggestion: 'Ask not found or was deleted.'
+          });
+          return;
+        }
+
+        // Check if replied
+        if (ask.status === 'replied') {
+          resolve({
+            reply: ask.answer,
+            from: ask.repliedBy
+          });
+          return;
+        }
+
+        // Schedule next poll with exponential backoff
+        setTimeout(poll, backoffDelay);
+
+        // Increase backoff delay (double it, max 10 seconds)
+        backoffDelay = Math.min(backoffDelay * 2, 10000);
+      };
+
+      // Start polling
+      poll();
+    });
+  }
+
+  /**
+   * Submit a reply to an ask
+   *
+   * @param {string} from - Replier name
+   * @param {string} askId - The ask ID to reply to
+   * @param {string} answer - The answer/reply
+   */
+  submitReply(from, askId, answer) {
+    const askPath = path.join(this.teamDir, 'asks', `ask_${askId}.json`);
+
+    // Read the ask
+    const ask = readJsonSafe(askPath, null);
+
+    if (!ask) {
+      throw new Error(`Ask ${askId} not found`);
+    }
+
+    // Update ask with reply
+    ask.status = 'replied';
+    ask.answer = answer;
+    ask.repliedAt = new Date().toISOString();
+    ask.repliedBy = from;
+
+    // Save updated ask
+    atomicWriteJson(askPath, ask);
+  }
+}
+
+// Export the TeamHub class
+module.exports = TeamHub;