create-byan-agent 2.0.1 → 2.1.1

package/src/byan-v2/integration/voice-integration.js

@@ -0,0 +1,295 @@
+const fs = require('fs');
+const path = require('path');
+const { exec } = require('child_process');
+const { promisify } = require('util');
+
+const execAsync = promisify(exec);
+
+/**
+ * VoiceIntegration - Turbo Whisper voice input integration for BYAN v2
+ * 
+ * Enables voice-driven agent interaction through Turbo Whisper transcription.
+ * Supports GitHub Copilot CLI, Claude Code, and Codex platforms.
+ * 
+ * @version 2.1.0
+ * @module integration/voice-integration
+ */
+class VoiceIntegration {
+  constructor(sessionState, logger) {
+    this.sessionState = sessionState;
+    this.logger = logger;
+    this.enabled = false;
+    this.config = null;
+    this.serverHealthy = false;
+  }
+
+  /**
+   * Initialize voice integration
+   * Detects Turbo Whisper installation and configuration
+   * @returns {Promise<boolean>} True if initialization successful
+   */
+  async initialize() {
+    try {
+      this.logger.debug('[VoiceIntegration] Initializing...');
+      
+      const installed = await this.detectInstallation();
+      if (!installed) {
+        this.logger.info('[VoiceIntegration] Turbo Whisper not installed');
+        return false;
+      }
+
+      const configLoaded = await this.loadConfig();
+      if (!configLoaded) {
+        this.logger.warn('[VoiceIntegration] Config not found, using defaults');
+        return false;
+      }
+
+      const healthy = await this.checkHealth();
+      if (!healthy) {
+        this.logger.warn('[VoiceIntegration] Server not responding');
+        return false;
+      }
+
+      this.enabled = true;
+      this.logger.info('[VoiceIntegration] Initialized successfully');
+      this.sessionState.set('voice_integration_enabled', true);
+      
+      return true;
+    } catch (error) {
+      this.logger.error('[VoiceIntegration] Initialization failed:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Detect if Turbo Whisper is installed
+   * @returns {Promise<boolean>}
+   */
+  async detectInstallation() {
+    try {
+      const { stdout } = await execAsync('which turbo-whisper');
+      const turboWhisperPath = stdout.trim();
+      
+      if (turboWhisperPath) {
+        this.logger.debug(`[VoiceIntegration] Found at: ${turboWhisperPath}`);
+        return true;
+      }
+      
+      return false;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Load Turbo Whisper configuration
+   * @returns {Promise<boolean>}
+   */
+  async loadConfig() {
+    try {
+      const homeDir = process.env.HOME || process.env.USERPROFILE;
+      const configPath = path.join(homeDir, '.config', 'turbo-whisper', 'config.json');
+
+      if (!fs.existsSync(configPath)) {
+        return false;
+      }
+
+      const configContent = fs.readFileSync(configPath, 'utf8');
+      this.config = JSON.parse(configContent);
+      
+      this.logger.debug('[VoiceIntegration] Config loaded:', {
+        api_url: this.config.api_url,
+        hotkey: this.config.hotkey,
+        claude_integration: this.config.claude_integration
+      });
+
+      return true;
+    } catch (error) {
+      this.logger.error('[VoiceIntegration] Config load failed:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Check if Turbo Whisper server is healthy
+   * @returns {Promise<boolean>}
+   */
+  async checkHealth() {
+    if (!this.config) {
+      return false;
+    }
+
+    try {
+      const apiUrl = this.config.api_url;
+      
+      if (apiUrl.includes('localhost') || apiUrl.includes('127.0.0.1')) {
+        const port = apiUrl.match(/:(\d+)/)?.[1] || '8000';
+        const healthUrl = `http://localhost:${port}/health`;
+        
+        const { stdout } = await execAsync(`curl -s ${healthUrl}`);
+        
+        // fedirz/faster-whisper-server returns "OK" (string)
+        // Other servers may return {"status": "ok"} (object)
+        if (stdout.trim() === 'OK') {
+          this.serverHealthy = true;
+          return true;
+        }
+        
+        try {
+          const response = JSON.parse(stdout);
+          this.serverHealthy = response.status === 'ok';
+          return this.serverHealthy;
+        } catch {
+          // If not JSON and not "OK", server not ready
+          return false;
+        }
+      }
+
+      this.serverHealthy = true;
+      return true;
+    } catch (error) {
+      this.logger.debug('[VoiceIntegration] Health check failed:', error.message);
+      return false;
+    }
+  }
+
+  /**
+   * Get voice integration status
+   * @returns {Object} Status object
+   */
+  getStatus() {
+    return {
+      enabled: this.enabled,
+      installed: this.config !== null,
+      serverHealthy: this.serverHealthy,
+      config: this.config ? {
+        apiUrl: this.config.api_url,
+        hotkey: this.config.hotkey?.join('+'),
+        claudeIntegration: this.config.claude_integration,
+        language: this.config.language
+      } : null
+    };
+  }
+
+  /**
+   * Suggest voice input for long-form responses
+   * @param {string} context - Current interaction context
+   * @returns {string|null} Suggestion message or null
+   */
+  suggestVoiceInput(context) {
+    if (!this.enabled) {
+      return null;
+    }
+
+    const longFormContexts = [
+      'project_description',
+      'pain_points',
+      'requirements',
+      'use_cases',
+      'business_rules'
+    ];
+
+    if (longFormContexts.some(ctx => context.includes(ctx))) {
+      const hotkey = this.config?.hotkey?.join('+') || 'Ctrl+Shift+Space';
+      return `💡 Voice input available: Press ${hotkey} to speak your response`;
+    }
+
+    return null;
+  }
+
+  /**
+   * Guide user to install Turbo Whisper
+   * @returns {Object} Installation guidance
+   */
+  getInstallationGuide() {
+    return {
+      message: 'Turbo Whisper not detected',
+      options: [
+        {
+          title: 'Install via BMAD Agent',
+          command: '@bmad-agent-turbo-whisper-integration',
+          description: 'Guided installation with wizard'
+        },
+        {
+          title: 'Manual Installation',
+          steps: [
+            'Ubuntu/Debian: sudo add-apt-repository ppa:bengweeks/turbo-whisper && sudo apt install turbo-whisper',
+            'Arch Linux: yay -S turbo-whisper',
+            'From source: git clone https://github.com/knowall-ai/turbo-whisper.git && cd turbo-whisper && pip install -e .'
+          ]
+        },
+        {
+          title: 'Skip',
+          description: 'Continue without voice input'
+        }
+      ]
+    };
+  }
+
+  /**
+   * Validate voice transcription quality
+   * @param {string} transcription - Transcribed text
+   * @returns {Object} Quality metrics
+   */
+  validateTranscription(transcription) {
+    const metrics = {
+      length: transcription.length,
+      wordCount: transcription.split(/\s+/).length,
+      hasSpecialChars: /[^\w\s]/g.test(transcription),
+      quality: 'unknown'
+    };
+
+    if (metrics.wordCount < 3) {
+      metrics.quality = 'poor';
+      metrics.warning = 'Transcription too short, may be incomplete';
+    } else if (metrics.wordCount < 10) {
+      metrics.quality = 'fair';
+    } else {
+      metrics.quality = 'good';
+    }
+
+    return metrics;
+  }
+
+  /**
+   * Offer voice input option during interview
+   * @param {string} questionId - Current question identifier
+   * @returns {string|null} Voice prompt suggestion
+   */
+  offerVoicePrompt(questionId) {
+    if (!this.enabled) {
+      return null;
+    }
+
+    const voiceOptimalQuestions = [
+      'project_description',
+      'pain_points',
+      'goals',
+      'requirements',
+      'use_cases',
+      'business_rules'
+    ];
+
+    if (voiceOptimalQuestions.includes(questionId)) {
+      const hotkey = this.config?.hotkey?.join('+') || 'Ctrl+Shift+Space';
+      return `[Voice: ${hotkey}] You can speak your response for faster input`;
+    }
+
+    return null;
+  }
+
+  /**
+   * Log voice usage metrics
+   * @param {Object} metrics - Usage metrics
+   */
+  logUsageMetrics(metrics) {
+    const usage = this.sessionState.get('voice_usage_metrics') || [];
+    usage.push({
+      timestamp: new Date().toISOString(),
+      ...metrics
+    });
+    this.sessionState.set('voice_usage_metrics', usage);
+  }
+}
+
+module.exports = VoiceIntegration;

package/src/byan-v2/observability/error-tracker.js

@@ -0,0 +1,105 @@
+/**
+ * ErrorTracker - Track and store errors with context
+ * 
+ * Error Types:
+ * - ROUTING_ERROR: Errors during task routing
+ * - EXECUTION_ERROR: Errors during task execution
+ * - VALIDATION_ERROR: Errors during validation
+ * 
+ * Features:
+ * - Store up to maxErrors (default 100) in FIFO order
+ * - Track error type, message, stack, context, timestamp
+ * - Filter errors by type
+ * - Get error statistics
+ * 
+ * Methods:
+ * - trackError(errorData)
+ * - getErrors()
+ * - getErrorsByType(type)
+ * - getErrorStats()
+ * - clearErrors()
+ */
+
+class ErrorTracker {
+  constructor(options = {}) {
+    this.maxErrors = options.maxErrors || 100;
+    this.errors = [];
+  }
+
+  /**
+   * Track an error with full context
+   * @param {Object} errorData - Error data with type, message, error, context
+   */
+  trackError(errorData) {
+    if (!errorData) return;
+
+    const { type, message, error, context } = errorData;
+
+    // Build error entry
+    const errorEntry = {
+      type,
+      message: message || error?.message,
+      stack: error?.stack,
+      context,
+      timestamp: new Date().toISOString()
+    };
+
+    // Add to errors array
+    this.errors.push(errorEntry);
+
+    // Enforce max size (FIFO)
+    if (this.errors.length > this.maxErrors) {
+      this.errors.shift(); // Remove oldest
+    }
+  }
+
+  /**
+   * Get all tracked errors
+   * @returns {Array} Array of error objects
+   */
+  getErrors() {
+    // Return copy to prevent external modification
+    return [...this.errors];
+  }
+
+  /**
+   * Get errors filtered by type
+   * @param {string} type - Error type to filter by
+   * @returns {Array} Array of errors matching type
+   */
+  getErrorsByType(type) {
+    return this.errors.filter(error => error.type === type);
+  }
+
+  /**
+   * Get error statistics
+   * @returns {Object} Statistics with total and breakdown by type
+   */
+  getErrorStats() {
+    const stats = {
+      total: this.errors.length,
+      byType: {
+        ROUTING_ERROR: 0,
+        EXECUTION_ERROR: 0,
+        VALIDATION_ERROR: 0
+      }
+    };
+
+    this.errors.forEach(error => {
+      if (stats.byType[error.type] !== undefined) {
+        stats.byType[error.type]++;
+      }
+    });
+
+    return stats;
+  }
+
+  /**
+   * Clear all tracked errors
+   */
+  clearErrors() {
+    this.errors = [];
+  }
+}
+
+module.exports = ErrorTracker;

package/src/byan-v2/observability/logger.js

@@ -0,0 +1,154 @@
+/**
+ * Logger - Winston-based structured logging
+ * 
+ * Features:
+ * - JSON format logging
+ * - File + Console output
+ * - Methods: logTaskRouting(), logTaskExecution(), logError()
+ */
+
+const winston = require('winston');
+const fs = require('fs');
+const path = require('path');
+
+class Logger {
+  constructor(options = {}) {
+    const {
+      logDir = path.join(process.cwd(), 'logs'),
+      logFile = 'byan.log',
+      consoleOutput = true,
+      level = 'info'
+    } = options;
+
+    this.logDir = logDir;
+    this.logFile = logFile;
+    this.logPath = path.join(logDir, logFile);
+
+    // Ensure log directory exists
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true });
+    }
+
+    // Configure transports
+    const transports = [
+      new winston.transports.File({
+        filename: this.logPath,
+        format: winston.format.json()
+      })
+    ];
+
+    if (consoleOutput) {
+      transports.push(
+        new winston.transports.Console({
+          format: winston.format.combine(
+            winston.format.colorize(),
+            winston.format.simple()
+          )
+        })
+      );
+    }
+
+    // Create Winston logger
+    this.logger = winston.createLogger({
+      level,
+      format: winston.format.combine(
+        winston.format.timestamp(),
+        winston.format.json()
+      ),
+      transports
+    });
+  }
+
+  /**
+   * Log task routing decision
+   * @param {Object} routingData - Routing decision data
+   */
+  logTaskRouting(routingData) {
+    if (!routingData) return;
+
+    const { task, executor, complexity, canFallback, reasoning } = routingData;
+
+    this.logger.info('Task routing decision', {
+      taskType: task?.type,
+      prompt: task?.prompt,
+      metadata: task?.metadata,
+      executor,
+      complexity,
+      canFallback,
+      reasoning
+    });
+  }
+
+  /**
+   * Log task execution result
+   * @param {Object} executionData - Execution result data
+   */
+  logTaskExecution(executionData) {
+    if (!executionData) return;
+
+    const { task, executor, duration, success, result, error, tokens } = executionData;
+
+    this.logger.info('Task execution completed', {
+      taskType: task?.type,
+      prompt: task?.prompt,
+      executor,
+      duration,
+      success,
+      result,
+      error,
+      tokens
+    });
+  }
+
+  /**
+   * Log error with context
+   * @param {Object} errorData - Error data with type, message, error, context
+   */
+  logError(errorData) {
+    if (!errorData) return;
+
+    const { type, message, error, context } = errorData;
+
+    this.logger.error(message || 'Error occurred', {
+      errorType: type,
+      stack: error?.stack,
+      context
+    });
+  }
+
+  /**
+   * Generic info log
+   * @param {string} message - Log message
+   * @param {Object} data - Additional data
+   */
+  info(message, data = {}) {
+    this.logger.info(message, data);
+  }
+
+  /**
+   * Generic warn log
+   * @param {string} message - Log message
+   * @param {Object} data - Additional data
+   */
+  warn(message, data = {}) {
+    this.logger.warn(message, data);
+  }
+
+  /**
+   * Generic error log
+   * @param {string} message - Log message
+   * @param {Object} data - Additional data
+   */
+  error(message, data = {}) {
+    this.logger.error(message, data);
+  }
+
+  /**
+   * Close logger and flush transports
+   */
+  close() {
+    this.logger.close();
+  }
+}
+
+module.exports = Logger;