create-byan-agent 2.0.1 → 2.1.1

package/install/src/byan-v2/orchestrator/state-machine.js

@@ -0,0 +1,204 @@
+/**
+ * StateMachine Core - Story 4.1
+ * Manages workflow state transitions for BYAN v2 orchestrator
+ * 
+ * States: INTERVIEW → ANALYSIS → GENERATION → COMPLETED (+ ERROR from any state)
+ */
+
+const Logger = require('../observability/logger');
+const ErrorTracker = require('../observability/error-tracker');
+
+class StateMachine {
+  constructor(options = {}) {
+    this.logger = options.logger || new Logger();
+    this.errorTracker = options.errorTracker || new ErrorTracker();
+
+    // AC1: Define five states
+    this.STATES = {
+      INTERVIEW: 'INTERVIEW',
+      ANALYSIS: 'ANALYSIS',
+      GENERATION: 'GENERATION',
+      COMPLETED: 'COMPLETED',
+      ERROR: 'ERROR'
+    };
+
+    // AC2: Valid state transitions
+    this.validTransitions = {
+      INTERVIEW: ['ANALYSIS', 'ERROR'],
+      ANALYSIS: ['GENERATION', 'ERROR'],
+      GENERATION: ['COMPLETED', 'ERROR'],
+      COMPLETED: [], // Terminal state
+      ERROR: []      // Terminal state
+    };
+
+    // State metadata
+    this.currentState = this.STATES.INTERVIEW;
+    this.stateMetadata = {
+      name: this.STATES.INTERVIEW,
+      timestamp: Date.now(),
+      attempts: 0
+    };
+
+    // AC5: Hooks for state enter/exit
+    this.enterHooks = {}; // { stateName: [callbacks] }
+    this.exitHooks = {};  // { stateName: [callbacks] }
+  }
+
+  /**
+   * AC3: Validate and execute state transition
+   * @param {string} newState - Target state
+   * @returns {Object} { success, previousState, newState, error? }
+   */
+  transition(newState) {
+    const previousState = this.currentState;
+
+    // Validate newState exists
+    if (!newState || !this.STATES[newState]) {
+      const error = new Error(`Unknown state: ${newState}`);
+      this.errorTracker.trackError({
+        error,
+        component: 'StateMachine',
+        operation: 'transition',
+        currentState: this.currentState,
+        attemptedState: newState
+      });
+      return {
+        success: false,
+        error: error.message
+      };
+    }
+
+    // Validate transition is allowed
+    if (!this.validTransitions[this.currentState].includes(newState)) {
+      const error = new Error(
+        `Invalid transition from ${this.currentState} to ${newState}`
+      );
+      this.errorTracker.trackError({
+        error,
+        component: 'StateMachine',
+        operation: 'transition',
+        currentState: this.currentState,
+        attemptedState: newState
+      });
+      return {
+        success: false,
+        error: error.message
+      };
+    }
+
+    // Execute transition with hooks
+    try {
+      // AC5: Call exit hooks
+      this._executeHooks(this.exitHooks[this.currentState], {
+        from: this.currentState,
+        to: newState
+      });
+
+      // Update state
+      this.currentState = newState;
+      this.stateMetadata = {
+        name: newState,
+        timestamp: Date.now(),
+        attempts: 0
+      };
+
+      // AC5: Call enter hooks
+      this._executeHooks(this.enterHooks[newState], {
+        from: previousState,
+        to: newState
+      });
+
+      // Log successful transition
+      this.logger.info('State transition', {
+        from: previousState,
+        to: newState,
+        timestamp: this.stateMetadata.timestamp
+      });
+
+      return {
+        success: true,
+        previousState,
+        newState
+      };
+    } catch (error) {
+      // If hooks fail, track but complete transition
+      this.errorTracker.trackError({
+        error,
+        component: 'StateMachine',
+        operation: 'transition-hooks',
+        state: newState
+      });
+
+      return {
+        success: true,
+        previousState,
+        newState,
+        hookError: error.message
+      };
+    }
+  }
+
+  /**
+   * AC4: Get current state with metadata
+   * @returns {Object} { name, timestamp, attempts }
+   */
+  getCurrentState() {
+    return { ...this.stateMetadata };
+  }
+
+  /**
+   * Increment retry attempts for current state
+   */
+  incrementAttempts() {
+    this.stateMetadata.attempts++;
+  }
+
+  /**
+   * AC5: Register state enter hook
+   * @param {string} stateName - State to hook into
+   * @param {Function} callback - Hook function
+   */
+  onStateEnter(stateName, callback) {
+    if (!this.enterHooks[stateName]) {
+      this.enterHooks[stateName] = [];
+    }
+    this.enterHooks[stateName].push(callback);
+  }
+
+  /**
+   * AC5: Register state exit hook
+   * @param {string} stateName - State to hook into
+   * @param {Function} callback - Hook function
+   */
+  onStateExit(stateName, callback) {
+    if (!this.exitHooks[stateName]) {
+      this.exitHooks[stateName] = [];
+    }
+    this.exitHooks[stateName].push(callback);
+  }
+
+  /**
+   * Execute all hooks for a state
+   * @private
+   */
+  _executeHooks(hooks, context) {
+    if (!hooks || hooks.length === 0) return;
+
+    hooks.forEach(hook => {
+      try {
+        hook(context);
+      } catch (error) {
+        // Track hook error but don't block transition
+        this.errorTracker.trackError({
+          error,
+          component: 'StateMachine',
+          operation: 'hook-execution',
+          context
+        });
+        throw error; // Re-throw to be caught by transition()
+      }
+    });
+  }
+}
+
+module.exports = StateMachine;

package/install/src/core/cache/cache.js

@@ -0,0 +1,126 @@
+/**
+ * Simple Cache with TTL support for reducing token consumption
+ * Provides in-memory caching with automatic expiration
+ * 
+ * @class SimpleCache
+ * @example
+ * const cache = new SimpleCache();
+ * cache.set('key1', 'value1', 5000); // TTL 5 seconds
+ * const value = cache.get('key1');
+ */
+class SimpleCache {
+  /**
+   * Initialize a new SimpleCache instance
+   */
+  constructor() {
+    this.store = new Map();
+  }
+
+  /**
+   * Store a value in cache with optional TTL
+   * @param {string} key - Cache key
+   * @param {*} value - Value to cache
+   * @param {number} [ttl] - Time to live in milliseconds (optional)
+   * @throws {Error} If key is not a string
+   * @returns {void}
+   */
+  set(key, value, ttl) {
+    if (typeof key !== 'string' || !key) {
+      throw new Error('Cache key must be a non-empty string');
+    }
+
+    const entry = {
+      value,
+      timestamp: Date.now(),
+      ttl: ttl || null
+    };
+
+    this.store.set(key, entry);
+  }
+
+  /**
+   * Retrieve a value from cache
+   * @param {string} key - Cache key
+   * @returns {*|null} Cached value or null if not found or expired
+   */
+  get(key) {
+    const entry = this.store.get(key);
+
+    if (!entry) {
+      return null;
+    }
+
+    // Check if TTL has expired
+    if (entry.ttl && (Date.now() - entry.timestamp) > entry.ttl) {
+      this.store.delete(key);
+      return null;
+    }
+
+    return entry.value;
+  }
+
+  /**
+   * Check if a key exists and is not expired
+   * @param {string} key - Cache key
+   * @returns {boolean} True if key exists and not expired
+   */
+  has(key) {
+    const value = this.get(key);
+    return value !== null;
+  }
+
+  /**
+   * Delete a specific cache entry
+   * @param {string} key - Cache key to delete
+   * @returns {boolean} True if key was deleted, false if not found
+   */
+  delete(key) {
+    return this.store.delete(key);
+  }
+
+  /**
+   * Clear all cache entries
+   * @returns {void}
+   */
+  clear() {
+    this.store.clear();
+  }
+
+  /**
+   * Get the number of entries in cache (includes expired but not cleaned)
+   * @returns {number} Number of cache entries
+   */
+  size() {
+    return this.store.size;
+  }
+
+  /**
+   * Get all non-expired keys
+   * @returns {string[]} Array of valid keys
+   */
+  keys() {
+    const validKeys = [];
+    for (const [key] of this.store) {
+      if (this.get(key) !== null) {
+        validKeys.push(key);
+      }
+    }
+    return validKeys;
+  }
+
+  /**
+   * Clean up expired entries
+   * @returns {number} Number of entries removed
+   */
+  cleanup() {
+    let removed = 0;
+    for (const [key] of this.store) {
+      if (this.get(key) === null) {
+        removed++;
+      }
+    }
+    return removed;
+  }
+}
+
+module.exports = SimpleCache;

package/install/src/core/context/context.js

@@ -0,0 +1,86 @@
+/**
+ * Context Layer for managing conversational context across agents
+ * Provides a hierarchical structure for storing and retrieving context data
+ * 
+ * @class ContextLayer
+ * @example
+ * const ctx = new ContextLayer();
+ * ctx.addLayer('user', { name: 'Yan', role: 'dev' });
+ * const userData = ctx.getLayer('user');
+ */
+class ContextLayer {
+  /**
+   * Initialize a new ContextLayer instance
+   */
+  constructor() {
+    this.layers = {};
+  }
+
+  /**
+   * Add or update a context layer
+   * @param {string} name - Layer name/identifier
+   * @param {object} data - Layer data to store
+   * @throws {Error} If name is not a string or data is not an object
+   * @returns {void}
+   */
+  addLayer(name, data) {
+    if (typeof name !== 'string' || !name) {
+      throw new Error('Layer name must be a non-empty string');
+    }
+    if (typeof data !== 'object' || data === null) {
+      throw new Error('Layer data must be an object');
+    }
+    this.layers[name] = { ...data, _timestamp: Date.now() };
+  }
+
+  /**
+   * Retrieve a specific context layer
+   * @param {string} name - Layer name to retrieve
+   * @returns {object|null} Layer data (deep copy) or null if not found
+   */
+  getLayer(name) {
+    if (!this.layers[name]) {
+      return null;
+    }
+    return JSON.parse(JSON.stringify(this.layers[name]));
+  }
+
+  /**
+   * Get all context layers
+   * @returns {object} All layers as a key-value object (deep copy)
+   */
+  getAllLayers() {
+    return JSON.parse(JSON.stringify(this.layers));
+  }
+
+  /**
+   * Remove a specific context layer
+   * @param {string} name - Layer name to remove
+   * @returns {boolean} True if layer was removed, false if not found
+   */
+  clearLayer(name) {
+    if (this.layers[name]) {
+      delete this.layers[name];
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Serialize all layers to JSON string
+   * @returns {string} JSON representation of all layers
+   */
+  serialize() {
+    return JSON.stringify(this.layers);
+  }
+
+  /**
+   * Clear all context layers
+   * @returns {void}
+   */
+  clearAll() {
+    this.layers = {};
+  }
+}
+
+module.exports = ContextLayer;

package/install/src/core/dispatcher/dispatcher.js

@@ -0,0 +1,135 @@
+/**
+ * Economic Dispatcher for routing tasks to appropriate AI models
+ * Routes tasks based on complexity keywords to optimize cost/performance
+ * 
+ * @class EconomicDispatcher
+ * @example
+ * const dispatcher = new EconomicDispatcher();
+ * const model = dispatcher.dispatch('explore codebase'); // Returns 'haiku'
+ */
+class EconomicDispatcher {
+  /**
+   * Initialize a new EconomicDispatcher instance
+   */
+  constructor() {
+    // Model classification patterns
+    this.patterns = {
+      haiku: [
+        'explore', 'simple', 'quick', 'search', 'find', 'list', 'show',
+        'check', 'verify', 'read', 'get', 'view', 'display', 'basic'
+      ],
+      sonnet: [
+        'implement', 'code', 'complex', 'develop', 'create', 'build',
+        'write', 'fix', 'refactor', 'optimize', 'integrate', 'design'
+      ],
+      opus: [
+        'architect', 'critical', 'review', 'analyze', 'evaluate', 'plan',
+        'strategy', 'security', 'performance', 'scalability', 'system-design',
+        'architectural', 'mission-critical', 'production'
+      ]
+    };
+
+    // Relative costs (Haiku = 1x baseline)
+    this.costs = {
+      haiku: 1,
+      sonnet: 5,
+      opus: 15
+    };
+  }
+
+  /**
+   * Dispatch a task to the appropriate model
+   * @param {string} task - Task description
+   * @returns {string} Model name ('haiku', 'sonnet', or 'opus')
+   * @throws {Error} If task is not a string
+   */
+  dispatch(task) {
+    if (typeof task !== 'string' || !task) {
+      throw new Error('Task must be a non-empty string');
+    }
+
+    const taskLower = task.toLowerCase();
+    
+    // Helper to check for whole word match or start of compound words
+    const hasKeyword = (patterns) => {
+      return patterns.some(pattern => {
+        const regex = new RegExp(`\\b${pattern}\\b`, 'i');
+        return regex.test(task);
+      });
+    };
+
+    // Check Opus patterns first (highest priority for critical tasks)
+    if (hasKeyword(this.patterns.opus)) {
+      return 'opus';
+    }
+
+    // Check Sonnet patterns (medium complexity)
+    if (hasKeyword(this.patterns.sonnet)) {
+      return 'sonnet';
+    }
+
+    // Check Haiku patterns (simple tasks)
+    if (hasKeyword(this.patterns.haiku)) {
+      return 'haiku';
+    }
+
+    // Default to Sonnet for unclassified tasks (balanced choice)
+    return 'sonnet';
+  }
+
+  /**
+   * Get the relative cost of a model
+   * @param {string} model - Model name ('haiku', 'sonnet', or 'opus')
+   * @returns {number} Relative cost multiplier
+   * @throws {Error} If model is unknown
+   */
+  getModelCost(model) {
+    if (!this.costs[model]) {
+      throw new Error(`Unknown model: ${model}`);
+    }
+    return this.costs[model];
+  }
+
+  /**
+   * Get cost comparison between two models
+   * @param {string} model1 - First model
+   * @param {string} model2 - Second model
+   * @returns {number} Cost ratio (model1/model2)
+   */
+  compareCosts(model1, model2) {
+    const cost1 = this.getModelCost(model1);
+    const cost2 = this.getModelCost(model2);
+    return cost1 / cost2;
+  }
+
+  /**
+   * Get all available models with their costs
+   * @returns {object} Models and their costs
+   */
+  getAllModels() {
+    return { ...this.costs };
+  }
+
+  /**
+   * Estimate cost savings by using recommended model vs default
+   * @param {string} task - Task description
+   * @param {string} defaultModel - Default model to compare against
+   * @returns {object} Savings information
+   */
+  estimateSavings(task, defaultModel = 'sonnet') {
+    const recommended = this.dispatch(task);
+    const recommendedCost = this.getModelCost(recommended);
+    const defaultCost = this.getModelCost(defaultModel);
+    const savings = ((defaultCost - recommendedCost) / defaultCost) * 100;
+
+    return {
+      recommended,
+      recommendedCost,
+      defaultCost,
+      savingsPercent: Math.round(savings),
+      shouldSwitch: savings > 0
+    };
+  }
+}
+
+module.exports = EconomicDispatcher;