agileflow 2.89.3 → 2.90.1

package/scripts/tui/lib/eventStream.js

@@ -0,0 +1,309 @@
+'use strict';
+
+/**
+ * Event Stream - Real-time event monitoring from agent bus
+ *
+ * Watches docs/09-agents/bus/log.jsonl for new events and emits them
+ * to subscribers. Handles file rotation and truncation gracefully.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const EventEmitter = require('events');
+
+// Get project root
+let getProjectRoot;
+try {
+  getProjectRoot = require('../../../lib/paths').getProjectRoot;
+} catch (e) {
+  // Fallback
+  getProjectRoot = () => process.cwd();
+}
+
+/**
+ * EventStream class - watches agent bus log and emits events
+ */
+class EventStream extends EventEmitter {
+  constructor(options = {}) {
+    super();
+
+    this.options = {
+      // Path to log file (defaults to agent bus)
+      logPath:
+        options.logPath || path.join(getProjectRoot(), 'docs', '09-agents', 'bus', 'log.jsonl'),
+      // Polling interval in ms (fallback if fs.watch fails)
+      pollInterval: options.pollInterval || 1000,
+      // Maximum events to keep in buffer
+      maxBufferSize: options.maxBufferSize || 100,
+      // Whether to emit historical events on start
+      emitHistory: options.emitHistory || false,
+      // How many historical events to emit
+      historyLimit: options.historyLimit || 10,
+    };
+
+    this.buffer = [];
+    this.filePosition = 0;
+    this.watcher = null;
+    this.pollTimer = null;
+    this.isWatching = false;
+  }
+
+  /**
+   * Start watching the log file
+   */
+  start() {
+    if (this.isWatching) return;
+
+    // Check if file exists
+    if (!fs.existsSync(this.options.logPath)) {
+      this.emit('error', new Error(`Log file not found: ${this.options.logPath}`));
+      // Continue anyway - file might be created later
+    }
+
+    // Get initial file size
+    this._updateFilePosition();
+
+    // Emit historical events if requested
+    if (this.options.emitHistory) {
+      this._emitHistory();
+    }
+
+    // Try to use fs.watch (more efficient)
+    try {
+      this.watcher = fs.watch(this.options.logPath, eventType => {
+        if (eventType === 'change') {
+          this._processNewLines();
+        }
+      });
+
+      this.watcher.on('error', err => {
+        this.emit('error', err);
+        // Fall back to polling
+        this._startPolling();
+      });
+    } catch (e) {
+      // Fall back to polling
+      this._startPolling();
+    }
+
+    this.isWatching = true;
+    this.emit('started');
+  }
+
+  /**
+   * Stop watching the log file
+   */
+  stop() {
+    if (!this.isWatching) return;
+
+    if (this.watcher) {
+      this.watcher.close();
+      this.watcher = null;
+    }
+
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+
+    this.isWatching = false;
+    this.emit('stopped');
+  }
+
+  /**
+   * Start polling as fallback
+   */
+  _startPolling() {
+    if (this.pollTimer) return;
+
+    this.pollTimer = setInterval(() => {
+      this._processNewLines();
+    }, this.options.pollInterval);
+  }
+
+  /**
+   * Update tracked file position
+   */
+  _updateFilePosition() {
+    try {
+      if (fs.existsSync(this.options.logPath)) {
+        const stats = fs.statSync(this.options.logPath);
+        this.filePosition = stats.size;
+      }
+    } catch (e) {
+      // Ignore errors
+    }
+  }
+
+  /**
+   * Emit historical events from file start
+   */
+  _emitHistory() {
+    try {
+      if (!fs.existsSync(this.options.logPath)) return;
+
+      const content = fs.readFileSync(this.options.logPath, 'utf8');
+      const lines = content.trim().split('\n').filter(Boolean);
+
+      // Get last N lines
+      const historyLines = lines.slice(-this.options.historyLimit);
+
+      for (const line of historyLines) {
+        try {
+          const event = JSON.parse(line);
+          this._addToBuffer(event);
+          this.emit('event', event);
+        } catch (e) {
+          // Skip invalid JSON
+        }
+      }
+    } catch (e) {
+      this.emit('error', e);
+    }
+  }
+
+  /**
+   * Process new lines added to the file
+   */
+  _processNewLines() {
+    try {
+      if (!fs.existsSync(this.options.logPath)) return;
+
+      const stats = fs.statSync(this.options.logPath);
+
+      // Handle file truncation (rotation)
+      if (stats.size < this.filePosition) {
+        this.filePosition = 0;
+        this.emit('truncated');
+      }
+
+      // No new content
+      if (stats.size <= this.filePosition) return;
+
+      // Read new content
+      const fd = fs.openSync(this.options.logPath, 'r');
+      const bufferSize = stats.size - this.filePosition;
+      const buffer = Buffer.alloc(bufferSize);
+
+      fs.readSync(fd, buffer, 0, bufferSize, this.filePosition);
+      fs.closeSync(fd);
+
+      // Update position
+      this.filePosition = stats.size;
+
+      // Process lines
+      const content = buffer.toString('utf8');
+      const lines = content.split('\n').filter(Boolean);
+
+      for (const line of lines) {
+        try {
+          const event = JSON.parse(line);
+          this._addToBuffer(event);
+          this.emit('event', event);
+        } catch (e) {
+          // Skip invalid JSON lines
+        }
+      }
+    } catch (e) {
+      this.emit('error', e);
+    }
+  }
+
+  /**
+   * Add event to buffer (with size limit)
+   */
+  _addToBuffer(event) {
+    this.buffer.push(event);
+
+    // Trim buffer if too large
+    while (this.buffer.length > this.options.maxBufferSize) {
+      this.buffer.shift();
+    }
+  }
+
+  /**
+   * Get buffered events
+   */
+  getBuffer() {
+    return [...this.buffer];
+  }
+
+  /**
+   * Clear buffer
+   */
+  clearBuffer() {
+    this.buffer = [];
+  }
+
+  /**
+   * Get events by type
+   */
+  getEventsByType(type) {
+    return this.buffer.filter(e => e.type === type);
+  }
+
+  /**
+   * Get events by agent
+   */
+  getEventsByAgent(agent) {
+    return this.buffer.filter(e => e.agent === agent);
+  }
+}
+
+/**
+ * Create a singleton event stream instance
+ */
+let defaultStream = null;
+
+function getDefaultStream() {
+  if (!defaultStream) {
+    defaultStream = new EventStream();
+  }
+  return defaultStream;
+}
+
+/**
+ * Format event for display
+ */
+function formatEvent(event) {
+  const timestamp = event.timestamp ? new Date(event.timestamp).toLocaleTimeString() : '';
+
+  const agent = event.agent || 'unknown';
+  const eventType = event.event || event.type || 'unknown';
+
+  let message = '';
+
+  switch (event.event) {
+    case 'init':
+      message = `Loop started: gate=${event.gate}, max=${event.max_iterations}`;
+      break;
+    case 'iteration':
+      message = `Iteration ${event.iter}: value=${event.value}, passed=${event.passed}`;
+      break;
+    case 'passed':
+      message = `Loop passed! final=${event.final_value}`;
+      break;
+    case 'failed':
+      message = `Loop failed: ${event.reason}, final=${event.final_value}`;
+      break;
+    case 'abort':
+      message = `Loop aborted: ${event.reason}`;
+      break;
+    default:
+      message = JSON.stringify(event);
+  }
+
+  return {
+    timestamp,
+    agent,
+    eventType,
+    message,
+    raw: event,
+  };
+}
+
+module.exports = {
+  EventStream,
+  getDefaultStream,
+  formatEvent,
+};

package/scripts/tui/lib/keyboard.js

@@ -0,0 +1,261 @@
+'use strict';
+
+/**
+ * Keyboard Handler - Key bindings for TUI
+ *
+ * Provides centralized keyboard handling with configurable bindings
+ * and event emission for TUI components.
+ */
+
+const EventEmitter = require('events');
+
+/**
+ * Default key bindings
+ */
+const DEFAULT_BINDINGS = {
+  quit: { key: 'q', description: 'Quit TUI' },
+  start: { key: 's', description: 'Start loop' },
+  pause: { key: 'p', description: 'Pause loop' },
+  resume: { key: 'r', description: 'Resume loop' },
+  trace: { key: 't', description: 'Toggle trace' },
+  help: { key: '?', description: 'Show help' },
+  // Session switching (1-9)
+  session1: { key: '1', description: 'Session 1' },
+  session2: { key: '2', description: 'Session 2' },
+  session3: { key: '3', description: 'Session 3' },
+  session4: { key: '4', description: 'Session 4' },
+  session5: { key: '5', description: 'Session 5' },
+  session6: { key: '6', description: 'Session 6' },
+  session7: { key: '7', description: 'Session 7' },
+  session8: { key: '8', description: 'Session 8' },
+  session9: { key: '9', description: 'Session 9' },
+};
+
+/**
+ * KeyboardHandler class - centralized keyboard handling
+ */
+class KeyboardHandler extends EventEmitter {
+  constructor(options = {}) {
+    super();
+
+    this.bindings = { ...DEFAULT_BINDINGS, ...options.bindings };
+    this.enabled = true;
+    this.keyHistory = [];
+    this.historyLimit = options.historyLimit || 50;
+  }
+
+  /**
+   * Process a key press
+   * @param {string} input - The key character
+   * @param {object} key - The key object from useInput
+   * @returns {object|null} - Action performed or null
+   */
+  processKey(input, key = {}) {
+    if (!this.enabled) return null;
+
+    // Record key press
+    this._recordKey(input, key);
+
+    // Handle Ctrl+C for quit
+    if (key.ctrl && input === 'c') {
+      const action = { action: 'quit', key: 'ctrl+c' };
+      this.emit('action', action);
+      this.emit('quit');
+      return action;
+    }
+
+    // Handle escape for quit
+    if (key.escape) {
+      const action = { action: 'quit', key: 'escape' };
+      this.emit('action', action);
+      this.emit('quit');
+      return action;
+    }
+
+    // Normalize input to lowercase for matching
+    const normalizedInput = input.toLowerCase();
+
+    // Check against bindings
+    for (const [actionName, binding] of Object.entries(this.bindings)) {
+      if (binding.key === normalizedInput || binding.key === input) {
+        const action = { action: actionName, key: input };
+        this.emit('action', action);
+        this.emit(actionName, action);
+
+        // Special handling for session switching
+        if (actionName.startsWith('session')) {
+          const sessionNum = parseInt(actionName.replace('session', ''), 10);
+          this.emit('sessionSwitch', { session: sessionNum });
+        }
+
+        return action;
+      }
+    }
+
+    // Unknown key
+    this.emit('unknownKey', { key: input });
+    return null;
+  }
+
+  /**
+   * Record key press to history
+   */
+  _recordKey(input, key) {
+    this.keyHistory.push({
+      input,
+      key,
+      timestamp: Date.now(),
+    });
+
+    // Trim history
+    while (this.keyHistory.length > this.historyLimit) {
+      this.keyHistory.shift();
+    }
+  }
+
+  /**
+   * Get key history
+   */
+  getHistory() {
+    return [...this.keyHistory];
+  }
+
+  /**
+   * Clear key history
+   */
+  clearHistory() {
+    this.keyHistory = [];
+  }
+
+  /**
+   * Enable keyboard handling
+   */
+  enable() {
+    this.enabled = true;
+  }
+
+  /**
+   * Disable keyboard handling
+   */
+  disable() {
+    this.enabled = false;
+  }
+
+  /**
+   * Check if a key is bound
+   */
+  isBound(key) {
+    return Object.values(this.bindings).some(b => b.key === key);
+  }
+
+  /**
+   * Get binding for action
+   */
+  getBinding(action) {
+    return this.bindings[action] || null;
+  }
+
+  /**
+   * Get all bindings
+   */
+  getBindings() {
+    return { ...this.bindings };
+  }
+
+  /**
+   * Set custom binding
+   */
+  setBinding(action, key, description) {
+    this.bindings[action] = { key, description };
+  }
+}
+
+/**
+ * Format key bindings for footer display
+ * @param {object} bindings - Key bindings object
+ * @returns {string[]} - Array of formatted binding strings
+ */
+function formatBindings(bindings = DEFAULT_BINDINGS) {
+  // Primary bindings to show in footer (exclude session numbers)
+  const primaryBindings = ['quit', 'start', 'pause', 'resume', 'trace', 'help'];
+
+  return primaryBindings
+    .filter(name => bindings[name])
+    .map(name => {
+      const binding = bindings[name];
+      return `${binding.key.toUpperCase()}:${binding.description}`;
+    });
+}
+
+/**
+ * Format bindings as help text
+ * @param {object} bindings - Key bindings object
+ * @returns {string} - Multi-line help text
+ */
+function formatHelp(bindings = DEFAULT_BINDINGS) {
+  const lines = ['Key Bindings:', ''];
+
+  // Group bindings
+  const groups = {
+    'Loop Control': ['start', 'pause', 'resume'],
+    View: ['trace', 'help'],
+    Navigation: ['quit'],
+    Sessions: [
+      'session1',
+      'session2',
+      'session3',
+      'session4',
+      'session5',
+      'session6',
+      'session7',
+      'session8',
+      'session9',
+    ],
+  };
+
+  for (const [groupName, actions] of Object.entries(groups)) {
+    lines.push(`  ${groupName}:`);
+    for (const action of actions) {
+      if (bindings[action]) {
+        const binding = bindings[action];
+        lines.push(`    ${binding.key.toUpperCase()} - ${binding.description}`);
+      }
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Create default keyboard handler instance
+ */
+let defaultHandler = null;
+
+function getDefaultHandler() {
+  if (!defaultHandler) {
+    defaultHandler = new KeyboardHandler();
+  }
+  return defaultHandler;
+}
+
+/**
+ * React hook factory for keyboard handling
+ * Returns a function that can be used with useInput
+ */
+function createKeyHandler(handler = null) {
+  const kbd = handler || getDefaultHandler();
+
+  return function handleKey(input, key) {
+    return kbd.processKey(input, key);
+  };
+}
+
+module.exports = {
+  KeyboardHandler,
+  DEFAULT_BINDINGS,
+  formatBindings,
+  formatHelp,
+  getDefaultHandler,
+  createKeyHandler,
+};