claudehq 1.0.1 → 1.0.3

package/bin/cli.js

@@ -17,7 +17,7 @@ program
   .action((options) => {
     process.env.PORT = options.port;
     process.env.NO_OPEN = options.open ? '' : '1';
-    require('../lib/server.js');
+    require('../lib/index.js');
   });
 
 program
@@ -50,7 +50,7 @@ program
   .action(() => {
     // If no command specified, run start
     process.env.PORT = process.env.PORT || '3456';
-    require('../lib/server.js');
+    require('../lib/index.js');
   });
 
 program.parse();

package/lib/core/claude-events.js

@@ -0,0 +1,308 @@
+/**
+ * Claude Events - Real-time event pipeline for Claude Code hooks
+ *
+ * Captures, processes, stores, and broadcasts Claude Code events.
+ * Events come from hooks (PreToolUse, PostToolUse, Stop, etc.)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { EVENTS_DIR, MAX_EVENTS_IN_MEMORY } = require('./config');
+const { eventBus, EventTypes } = require('./event-bus');
+const { broadcastUpdate } = require('./sse');
+
+const EVENTS_FILE = path.join(EVENTS_DIR, 'events.jsonl');
+const MAX_EVENTS = MAX_EVENTS_IN_MEMORY || 1000;
+
+// Event state
+const claudeEvents = [];
+const seenEventIds = new Set();
+const pendingToolUses = new Map(); // Track pre_tool_use for duration calculation
+let lastEventsFileSize = 0;
+
+// Session update callback (set by sessions module to avoid circular dep)
+let sessionUpdateCallback = null;
+
+// Conversation file finder callback (set by conversation module)
+let findConversationFileCallback = null;
+
+/**
+ * Set callback for updating sessions from events
+ * @param {Function} callback - Function to call with event
+ */
+function setSessionUpdateCallback(callback) {
+  sessionUpdateCallback = callback;
+}
+
+/**
+ * Set callback for finding conversation files
+ * @param {Function} callback - Function to call with sessionId
+ */
+function setConversationFileCallback(callback) {
+  findConversationFileCallback = callback;
+}
+
+/**
+ * Get the latest assistant text from a conversation JSONL file
+ * @param {string} sessionId - Claude session ID
+ * @returns {string} Latest assistant text or empty string
+ */
+function getLatestAssistantText(sessionId) {
+  if (!findConversationFileCallback) return '';
+
+  const filePath = findConversationFileCallback(sessionId);
+  if (!filePath) return '';
+
+  try {
+    const fileData = fs.readFileSync(filePath, 'utf-8');
+    const lines = fileData.trim().split('\n');
+
+    // Parse backwards to find the most recent assistant text
+    for (let i = lines.length - 1; i >= 0; i--) {
+      try {
+        const entry = JSON.parse(lines[i]);
+        if (entry.type === 'assistant' && Array.isArray(entry.message?.content)) {
+          for (const block of entry.message.content) {
+            if (block.type === 'text' && block.text) {
+              return block.text;
+            }
+          }
+        }
+      } catch (e) {
+        // Skip malformed lines
+      }
+    }
+  } catch (e) {
+    // File read error
+  }
+  return '';
+}
+
+/**
+ * Process and enrich event (calculate tool duration, etc.)
+ * @param {Object} event - Raw event
+ * @returns {Object} Processed event
+ */
+function processClaudeEvent(event) {
+  // Track pre_tool_use for duration calculation
+  if (event.type === 'pre_tool_use' && event.toolUseId) {
+    pendingToolUses.set(event.toolUseId, event);
+  }
+
+  // Calculate duration for post_tool_use
+  if (event.type === 'post_tool_use' && event.toolUseId) {
+    const preEvent = pendingToolUses.get(event.toolUseId);
+    if (preEvent) {
+      event.duration = event.timestamp - preEvent.timestamp;
+      pendingToolUses.delete(event.toolUseId);
+    }
+  }
+
+  // Enrich stop events with assistant response from conversation file
+  if (event.type === 'stop' && !event.response && event.sessionId) {
+    event.response = getLatestAssistantText(event.sessionId);
+  }
+
+  return event;
+}
+
+/**
+ * Add event to memory and broadcast
+ * @param {Object} event - Event to add
+ */
+function addClaudeEvent(event) {
+  // Skip duplicates
+  if (seenEventIds.has(event.id)) return;
+  seenEventIds.add(event.id);
+
+  // Trim old IDs to prevent memory leak
+  if (seenEventIds.size > MAX_EVENTS * 2) {
+    const idsToKeep = [...seenEventIds].slice(-MAX_EVENTS);
+    seenEventIds.clear();
+    idsToKeep.forEach(id => seenEventIds.add(id));
+  }
+
+  const processed = processClaudeEvent(event);
+  claudeEvents.push(processed);
+
+  // Trim old events
+  if (claudeEvents.length > MAX_EVENTS) {
+    claudeEvents.splice(0, claudeEvents.length - MAX_EVENTS);
+  }
+
+  // Emit through EventBus
+  eventBus.emit(EventTypes.CLAUDE_EVENT, processed);
+
+  // Update managed session status based on event
+  if (sessionUpdateCallback) {
+    sessionUpdateCallback(processed);
+  }
+
+  // Broadcast to all SSE clients
+  broadcastClaudeEvent(processed);
+}
+
+/**
+ * Broadcast a single Claude event to all SSE clients
+ * @param {Object} event - Event to broadcast
+ */
+function broadcastClaudeEvent(event) {
+  broadcastUpdate('claude_event', { event });
+}
+
+/**
+ * Load existing events from file
+ */
+function loadEventsFromFile() {
+  if (!fs.existsSync(EVENTS_FILE)) return;
+
+  try {
+    const content = fs.readFileSync(EVENTS_FILE, 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean);
+
+    for (const line of lines) {
+      try {
+        const event = JSON.parse(line);
+        processClaudeEvent(event);
+        claudeEvents.push(event);
+        seenEventIds.add(event.id);
+      } catch (e) {
+        // Skip invalid lines
+      }
+    }
+
+    lastEventsFileSize = content.length;
+    console.log(`  Loaded ${claudeEvents.length} Claude events from: ${EVENTS_FILE}`);
+
+    // Discover sessions from loaded events (process unique session IDs)
+    if (sessionUpdateCallback) {
+      const sessionIds = new Set();
+      for (const event of claudeEvents) {
+        if (event.sessionId && !sessionIds.has(event.sessionId)) {
+          sessionIds.add(event.sessionId);
+          sessionUpdateCallback(event);
+        }
+      }
+    }
+  } catch (e) {
+    console.error('Error loading events:', e.message);
+  }
+}
+
+/**
+ * Watch events file for changes
+ */
+function watchEventsFile() {
+  // Ensure directory exists
+  if (!fs.existsSync(EVENTS_DIR)) {
+    fs.mkdirSync(EVENTS_DIR, { recursive: true });
+  }
+
+  // Create file if it doesn't exist
+  if (!fs.existsSync(EVENTS_FILE)) {
+    fs.writeFileSync(EVENTS_FILE, '');
+  }
+
+  // Use polling for reliability (works across all platforms)
+  fs.watchFile(EVENTS_FILE, { interval: 100 }, (curr, prev) => {
+    if (curr.size <= prev.size) return; // File hasn't grown
+
+    try {
+      const content = fs.readFileSync(EVENTS_FILE, 'utf-8');
+
+      // Only process new content
+      if (content.length > lastEventsFileSize) {
+        const newContent = content.slice(lastEventsFileSize);
+        const newLines = newContent.trim().split('\n').filter(Boolean);
+
+        for (const line of newLines) {
+          try {
+            const event = JSON.parse(line);
+            addClaudeEvent(event);
+          } catch (e) {
+            // Skip invalid lines
+          }
+        }
+
+        lastEventsFileSize = content.length;
+      }
+    } catch (e) {
+      // Ignore read errors
+    }
+  });
+
+  console.log(`  Watching for Claude events in: ${EVENTS_FILE}`);
+}
+
+/**
+ * Get all events
+ * @returns {Array} All events in memory
+ */
+function getEvents() {
+  return claudeEvents;
+}
+
+/**
+ * Get events filtered by session
+ * @param {string} sessionId - Session ID to filter by
+ * @returns {Array} Filtered events
+ */
+function getEventsBySession(sessionId) {
+  return claudeEvents.filter(e => e.sessionId === sessionId);
+}
+
+/**
+ * Get event statistics
+ * @returns {Object} Event stats
+ */
+function getEventStats() {
+  const toolCounts = {};
+  const typeCounts = {};
+  const sessionCounts = {};
+
+  for (const event of claudeEvents) {
+    // Count by tool
+    if (event.tool) {
+      toolCounts[event.tool] = (toolCounts[event.tool] || 0) + 1;
+    }
+    // Count by type
+    typeCounts[event.type] = (typeCounts[event.type] || 0) + 1;
+    // Count by session
+    if (event.sessionId) {
+      sessionCounts[event.sessionId] = (sessionCounts[event.sessionId] || 0) + 1;
+    }
+  }
+
+  return {
+    totalEvents: claudeEvents.length,
+    toolCounts,
+    typeCounts,
+    sessionCounts
+  };
+}
+
+/**
+ * Initialize the events module
+ */
+function init() {
+  loadEventsFromFile();
+  watchEventsFile();
+}
+
+module.exports = {
+  // Core functions
+  init,
+  addClaudeEvent,
+  getEvents,
+  getEventsBySession,
+  getEventStats,
+  processClaudeEvent,
+  broadcastClaudeEvent,
+
+  // Callbacks for dependency injection
+  setSessionUpdateCallback,
+  setConversationFileCallback,
+
+  // Direct access (for SSE history, etc.)
+  claudeEvents
+};

package/lib/core/config.js

@@ -0,0 +1,103 @@
+/**
+ * Configuration - Centralized config for Claude HQ
+ *
+ * All paths, constants, and environment configuration in one place.
+ */
+
+const path = require('path');
+const os = require('os');
+
+// Base directories
+const CLAUDE_DIR = path.join(os.homedir(), '.claude');
+
+// Data directories
+const TASKS_DIR = path.join(CLAUDE_DIR, 'tasks');
+const TODOS_DIR = path.join(CLAUDE_DIR, 'todos');
+const PLANS_DIR = path.join(CLAUDE_DIR, 'plans');
+const PROJECTS_DIR = path.join(CLAUDE_DIR, 'projects');
+const EVENTS_DIR = path.join(CLAUDE_DIR, 'tasks-board');
+const ORCHESTRATIONS_DIR = path.join(CLAUDE_DIR, 'tasks-board', 'orchestrations');
+
+// Data files
+const CUSTOM_NAMES_FILE = path.join(TASKS_DIR, 'session-names.json');
+const HIDDEN_SESSIONS_FILE = path.join(EVENTS_DIR, 'hidden-sessions.json');
+const SESSIONS_FILE = path.join(EVENTS_DIR, 'sessions.json');
+const EVENTS_FILE = path.join(EVENTS_DIR, 'events.json');
+
+// Server configuration
+const PORT = process.env.PORT || 3456;
+const TMUX_SESSION = process.env.TMUX_SESSION || 'main';
+
+// Session status constants
+const SESSION_STATUS = {
+  IDLE: 'idle',
+  WORKING: 'working',
+  WAITING: 'waiting',
+  OFFLINE: 'offline'
+};
+
+// Agent status constants (for orchestration)
+const AGENT_STATUS = {
+  PENDING: 'pending',
+  SPAWNING: 'spawning',
+  RUNNING: 'running',
+  WAITING: 'waiting',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+  CANCELLED: 'cancelled'
+};
+
+// Orchestration status constants
+const ORCHESTRATION_STATUS = {
+  DRAFT: 'draft',
+  RUNNING: 'running',
+  PAUSED: 'paused',
+  COMPLETED: 'completed',
+  FAILED: 'failed'
+};
+
+// Timeouts and intervals
+const HEALTH_CHECK_INTERVAL = 5000; // 5 seconds
+const WORKING_TIMEOUT = 5 * 60 * 1000; // 5 minutes
+const PERMISSION_POLL_INTERVAL = 1000; // 1 second
+const EVENT_DEBOUNCE_DELAY = 100; // 100ms
+
+// Limits
+const MAX_EVENTS_IN_MEMORY = 1000;
+const MAX_EVENTS_TO_BROADCAST = 500;
+
+module.exports = {
+  // Directories
+  CLAUDE_DIR,
+  TASKS_DIR,
+  TODOS_DIR,
+  PLANS_DIR,
+  PROJECTS_DIR,
+  EVENTS_DIR,
+  ORCHESTRATIONS_DIR,
+
+  // Files
+  CUSTOM_NAMES_FILE,
+  HIDDEN_SESSIONS_FILE,
+  SESSIONS_FILE,
+  EVENTS_FILE,
+
+  // Server
+  PORT,
+  TMUX_SESSION,
+
+  // Status
+  SESSION_STATUS,
+  AGENT_STATUS,
+  ORCHESTRATION_STATUS,
+
+  // Timing
+  HEALTH_CHECK_INTERVAL,
+  WORKING_TIMEOUT,
+  PERMISSION_POLL_INTERVAL,
+  EVENT_DEBOUNCE_DELAY,
+
+  // Limits
+  MAX_EVENTS_IN_MEMORY,
+  MAX_EVENTS_TO_BROADCAST
+};

package/lib/core/event-bus.js

@@ -0,0 +1,145 @@
+/**
+ * EventBus - Decoupled event handling for Claude HQ
+ *
+ * Provides pub/sub pattern for communication between modules without tight coupling.
+ * Used for broadcasting updates, logging, and inter-module communication.
+ */
+
+const EventTypes = {
+  // Task events
+  TASK_CREATED: 'task:created',
+  TASK_UPDATED: 'task:updated',
+  TASK_STATUS_CHANGED: 'task:status_changed',
+
+  // Todo events
+  TODO_CREATED: 'todo:created',
+  TODO_UPDATED: 'todo:updated',
+  TODO_STATUS_CHANGED: 'todo:status_changed',
+  TODOS_CHANGED: 'todos:changed',
+
+  // Plan events
+  PLAN_CREATED: 'plan:created',
+  PLAN_UPDATED: 'plan:updated',
+  PLANS_CHANGED: 'plans:changed',
+
+  // Session events
+  SESSION_RENAMED: 'session:renamed',
+  SESSION_SELECTED: 'session:selected',
+
+  // Prompt events
+  PROMPT_SENT: 'prompt:sent',
+  PROMPT_SUCCEEDED: 'prompt:succeeded',
+  PROMPT_FAILED: 'prompt:failed',
+
+  // Claude Code events (from hooks)
+  CLAUDE_EVENT: 'claude:event',
+  PRE_TOOL_USE: 'claude:pre_tool_use',
+  POST_TOOL_USE: 'claude:post_tool_use',
+  STOP: 'claude:stop',
+  USER_PROMPT_SUBMIT: 'claude:user_prompt_submit',
+  SUBAGENT_SPAWN: 'claude:subagent_spawn',
+  SUBAGENT_COMPLETE: 'claude:subagent_complete',
+
+  // File system events
+  FILE_CHANGED: 'file:changed',
+
+  // Attention events
+  ATTENTION_NEEDED: 'attention:needed',
+  ATTENTION_CLEARED: 'attention:cleared',
+
+  // Orchestration events
+  ORCHESTRATION_CREATED: 'orchestration:created',
+  ORCHESTRATION_UPDATED: 'orchestration:updated',
+  ORCHESTRATION_STARTED: 'orchestration:started',
+  ORCHESTRATION_PAUSED: 'orchestration:paused',
+  ORCHESTRATION_COMPLETED: 'orchestration:completed',
+  ORCHESTRATION_FAILED: 'orchestration:failed',
+  ORCHESTRATION_DELETED: 'orchestration:deleted',
+
+  // Agent events (within orchestrations)
+  AGENT_CREATED: 'agent:created',
+  AGENT_SPAWNED: 'agent:spawned',
+  AGENT_STATUS_CHANGED: 'agent:status_changed',
+  AGENT_OUTPUT: 'agent:output',
+  AGENT_COMPLETED: 'agent:completed',
+  AGENT_FAILED: 'agent:failed',
+  AGENT_KILLED: 'agent:killed',
+};
+
+class EventBus {
+  constructor() {
+    this.handlers = new Map();
+  }
+
+  /**
+   * Subscribe to an event type
+   * @param {string} type - Event type from EventTypes
+   * @param {Function} handler - Handler function
+   * @returns {Function} Unsubscribe function
+   */
+  on(type, handler) {
+    if (!this.handlers.has(type)) {
+      this.handlers.set(type, new Set());
+    }
+    this.handlers.get(type).add(handler);
+    // Return unsubscribe function
+    return () => this.handlers.get(type)?.delete(handler);
+  }
+
+  /**
+   * Emit an event to all subscribers
+   * @param {string} type - Event type
+   * @param {Object} payload - Event data
+   */
+  emit(type, payload = {}) {
+    const handlers = this.handlers.get(type);
+    if (!handlers) return;
+    for (const handler of handlers) {
+      try {
+        handler(payload);
+      } catch (error) {
+        console.error(`[EventBus] Error in handler for ${type}:`, error);
+      }
+    }
+  }
+
+  /**
+   * Remove all handlers for an event type
+   * @param {string} type - Event type
+   */
+  off(type) {
+    this.handlers.delete(type);
+  }
+
+  /**
+   * Clear all handlers
+   */
+  clear() {
+    this.handlers.clear();
+  }
+
+  /**
+   * Get handler count for debugging
+   * @param {string} [type] - Optional event type
+   * @returns {number} Handler count
+   */
+  getHandlerCount(type) {
+    if (type) {
+      return this.handlers.get(type)?.size ?? 0;
+    }
+    let total = 0;
+    for (const handlers of this.handlers.values()) {
+      total += handlers.size;
+    }
+    return total;
+  }
+}
+
+// Singleton instance
+const eventBus = new EventBus();
+
+module.exports = {
+  EventBus,
+  EventTypes,
+  eventBus
+};

package/lib/core/sse.js

@@ -0,0 +1,96 @@
+/**
+ * SSE (Server-Sent Events) - Real-time client communication
+ *
+ * Manages SSE connections and broadcasts updates to all connected clients.
+ */
+
+// Connected SSE clients
+const sseClients = new Set();
+
+/**
+ * Add a new SSE client
+ * @param {http.ServerResponse} client - Response object to write SSE events to
+ */
+function addClient(client) {
+  sseClients.add(client);
+}
+
+/**
+ * Remove an SSE client
+ * @param {http.ServerResponse} client - Client to remove
+ */
+function removeClient(client) {
+  sseClients.delete(client);
+}
+
+/**
+ * Get current client count
+ * @returns {number} Number of connected clients
+ */
+function getClientCount() {
+  return sseClients.size;
+}
+
+/**
+ * Broadcast an update to all connected clients
+ * @param {string} eventType - Type of event (e.g., 'update', 'task_created')
+ * @param {Object} payload - Event data
+ */
+function broadcastUpdate(eventType = 'update', payload = {}) {
+  const data = JSON.stringify({
+    type: eventType,
+    timestamp: Date.now(),
+    ...payload
+  });
+  for (const client of sseClients) {
+    try {
+      client.write(`data: ${data}\n\n`);
+    } catch (e) {
+      // Client disconnected, remove it
+      sseClients.delete(client);
+    }
+  }
+}
+
+/**
+ * Broadcast raw data to all clients
+ * @param {string} data - Pre-formatted SSE data
+ */
+function broadcastRaw(data) {
+  for (const client of sseClients) {
+    try {
+      client.write(data);
+    } catch (e) {
+      sseClients.delete(client);
+    }
+  }
+}
+
+/**
+ * Send data to a specific client
+ * @param {http.ServerResponse} client - Target client
+ * @param {string} eventType - Type of event
+ * @param {Object} payload - Event data
+ */
+function sendToClient(client, eventType, payload = {}) {
+  const data = JSON.stringify({
+    type: eventType,
+    timestamp: Date.now(),
+    ...payload
+  });
+  try {
+    client.write(`data: ${data}\n\n`);
+  } catch (e) {
+    sseClients.delete(client);
+  }
+}
+
+module.exports = {
+  sseClients,
+  addClient,
+  removeClient,
+  getClientCount,
+  broadcastUpdate,
+  broadcastRaw,
+  sendToClient
+};