create-byan-agent 2.0.1 → 2.1.1

package/src/byan-v2/orchestrator/interview-state.js

@@ -0,0 +1,353 @@
+/**
+ * InterviewState - Story 4.2
+ * Manages structured interview flow through 4 phases
+ * 
+ * Phases:
+ * 1. CONTEXT: Project context, domain, users
+ * 2. BUSINESS: Goals, problems, success criteria
+ * 3. AGENT_NEEDS: Agent capabilities, behavior, constraints
+ * 4. VALIDATION: Confirm understanding, clarifications
+ * 
+ * Integrates with SessionState to persist interview data
+ */
+
+const Logger = require('../observability/logger');
+const crypto = require('crypto');
+
+class InterviewState {
+  constructor(sessionState) {
+    this.sessionState = sessionState;
+    this.logger = new Logger();
+
+    // AC1: Define 4 phases
+    this.PHASES = {
+      CONTEXT: 'CONTEXT',
+      BUSINESS: 'BUSINESS',
+      AGENT_NEEDS: 'AGENT_NEEDS',
+      VALIDATION: 'VALIDATION'
+    };
+
+    // Current interview state
+    this.currentPhase = this.PHASES.CONTEXT;
+    this.currentQuestionIndex = 0;
+    this.awaitingResponse = false;
+    this.lastAskedQuestion = null;
+
+    // v2.1.0: BMAD integration tracking
+    this.activeListeningCounter = 0;      // Track responses for active listening
+    this.painPointsDetected = false;      // Flag if pain points found
+    this.glossaryTriggered = false;       // Flag if glossary should trigger
+    this.reformulatedResponses = [];      // Store reformulated responses alongside originals
+
+    // AC4: Track responses per phase
+    this.phaseResponses = {
+      CONTEXT: [],
+      BUSINESS: [],
+      AGENT_NEEDS: [],
+      VALIDATION: []
+    };
+
+    // AC1: Question banks for each phase (min 3 per phase)
+    this.questionBanks = {
+      CONTEXT: [
+        'What is the main purpose or domain of your project?',
+        'Who are the primary users or stakeholders?',
+        'What is the current workflow or process this agent will support?',
+        'What technologies or platforms are you using?',
+        'What is the scale or scope of your project?'
+      ],
+      BUSINESS: [
+        'What specific problem or challenge does this agent need to solve?',
+        'What are the key goals or objectives for this agent?',
+        'How will you measure the success of this agent?',
+        'What are the most time-consuming or error-prone tasks currently?',
+        'What business value or ROI do you expect?'
+      ],
+      AGENT_NEEDS: [
+        'What specific capabilities should this agent have?',
+        'What knowledge or expertise should the agent possess?',
+        'How should the agent interact with users (tone, style, format)?',
+        'What are the critical constraints or limitations for the agent?',
+        'What level of autonomy should the agent have in decision-making?'
+      ],
+      VALIDATION: [
+        'Let me confirm: The agent will help with [SUMMARY]. Is this correct?',
+        'Are there any critical requirements or edge cases we haven\'t covered?',
+        'What would make this agent a complete failure in your eyes?',
+        'Is there anything else important I should know about this agent?'
+      ]
+    };
+
+    this.phaseOrder = ['CONTEXT', 'BUSINESS', 'AGENT_NEEDS', 'VALIDATION'];
+    this.minResponsesPerPhase = 3;
+  }
+
+  /**
+   * AC2: Ask next question based on phase and responses
+   * @returns {Object|null} Question object or null if complete
+   */
+  askNextQuestion() {
+    // Check if waiting for response to last question
+    if (this.awaitingResponse && this.lastAskedQuestion) {
+      this.logger.warn('Awaiting response to previous question');
+      return this.lastAskedQuestion;
+    }
+
+    // Check if interview complete
+    if (this.isInterviewComplete()) {
+      this.logger.info('Interview complete - no more questions');
+      return null;
+    }
+
+    // Check if current phase needs transition
+    if (this.isPhaseComplete(this.currentPhase)) {
+      this._transitionToNextPhase();
+    }
+
+    // Get question from current phase
+    const phaseQuestions = this.questionBanks[this.currentPhase];
+    const phaseResponseCount = this.phaseResponses[this.currentPhase].length;
+    
+    // Use response count as index (allows revisiting questions)
+    const questionIndex = Math.min(phaseResponseCount, phaseQuestions.length - 1);
+    const questionText = phaseQuestions[questionIndex];
+
+    // Build question object
+    const question = {
+      questionId: crypto.randomUUID(),
+      text: questionText,
+      phase: this.currentPhase,
+      questionNumber: this.currentQuestionIndex + 1,
+      totalInPhase: phaseQuestions.length,
+      phaseProgress: `${phaseResponseCount + 1}/${this.minResponsesPerPhase} (min)`
+    };
+
+    // Store in SessionState
+    this.sessionState.addQuestion(questionText);
+
+    // Mark as awaiting response
+    this.awaitingResponse = true;
+    this.lastAskedQuestion = question;
+
+    this.logger.info('Question asked', {
+      phase: this.currentPhase,
+      questionNumber: question.questionNumber,
+      phaseProgress: question.phaseProgress
+    });
+
+    return question;
+  }
+
+  /**
+   * AC3: Process user response and store
+   * @param {string} response - User's response
+   * @param {Object} metadata - Optional metadata (v2.1.0: reformulated, painPoints)
+   */
+  processResponse(response, metadata = {}) {
+    if (!this.awaitingResponse) {
+      this.logger.warn('No question pending - ignoring response');
+      return false;
+    }
+
+    // Store response in current phase
+    const responseData = {
+      questionId: this.lastAskedQuestion.questionId,
+      response: response || '',
+      timestamp: Date.now(),
+      phase: this.currentPhase,
+      // v2.1.0: BMAD metadata
+      reformulated: metadata.reformulated || null,
+      painPointsDetected: metadata.painPointsDetected || false,
+      clarityScore: metadata.clarityScore || null
+    };
+
+    this.phaseResponses[this.currentPhase].push(responseData);
+
+    // v2.1.0: Track reformulated responses
+    if (metadata.reformulated) {
+      this.reformulatedResponses.push({
+        original: response,
+        reformulated: metadata.reformulated,
+        questionId: this.lastAskedQuestion.questionId,
+        phase: this.currentPhase
+      });
+    }
+
+    // v2.1.0: Track pain points
+    if (metadata.painPointsDetected) {
+      this.painPointsDetected = true;
+    }
+
+    // v2.1.0: Increment active listening counter
+    this.activeListeningCounter++;
+
+    // Store in SessionState
+    this.sessionState.addResponse(this.lastAskedQuestion.questionId, response);
+
+    // Update state
+    this.currentQuestionIndex++;
+    this.awaitingResponse = false;
+    this.lastAskedQuestion = null;
+
+    this.logger.info('Response processed', {
+      phase: this.currentPhase,
+      responseCount: this.phaseResponses[this.currentPhase].length,
+      phaseComplete: this.isPhaseComplete(this.currentPhase),
+      activeListeningCounter: this.activeListeningCounter
+    });
+
+    // Transition to next phase if current phase is complete
+    if (this.isPhaseComplete(this.currentPhase)) {
+      const currentPhaseIndex = this.phaseOrder.indexOf(this.currentPhase);
+      if (currentPhaseIndex < this.phaseOrder.length - 1) {
+        this._transitionToNextPhase();
+      }
+    }
+
+    return this.isInterviewComplete();
+  }
+
+  /**
+   * AC4: Check if phase has minimum responses
+   * @param {string} phase - Phase name
+   * @returns {boolean} True if phase complete
+   */
+  isPhaseComplete(phase) {
+    return this.phaseResponses[phase].length >= this.minResponsesPerPhase;
+  }
+
+  /**
+   * AC5: Check if all phases complete and can transition to ANALYSIS
+   * @returns {boolean} True if interview complete
+   */
+  canTransitionToAnalysis() {
+    return this.phaseOrder.every(phase => this.isPhaseComplete(phase));
+  }
+
+  /**
+   * Check if interview is complete
+   * @returns {boolean} True if all phases done
+   */
+  isInterviewComplete() {
+    return this.canTransitionToAnalysis();
+  }
+
+  /**
+   * Get all collected responses
+   * @returns {Object} All phase responses
+   */
+  getAllResponses() {
+    return { ...this.phaseResponses };
+  }
+
+  /**
+   * Get responses for specific phase
+   * @param {string} phase - Phase name
+   * @returns {Array} Phase responses
+   */
+  getPhaseResponses(phase) {
+    return [...this.phaseResponses[phase]];
+  }
+
+  /**
+   * Get interview progress summary
+   * @returns {Object} Progress data
+   */
+  getProgress() {
+    const phaseProgress = {};
+    
+    this.phaseOrder.forEach(phase => {
+      const count = this.phaseResponses[phase].length;
+      phaseProgress[phase] = {
+        responses: count,
+        complete: this.isPhaseComplete(phase),
+        progress: `${count}/${this.minResponsesPerPhase}`
+      };
+    });
+
+    return {
+      currentPhase: this.currentPhase,
+      totalQuestions: this.currentQuestionIndex,
+      phases: phaseProgress,
+      canTransitionToAnalysis: this.canTransitionToAnalysis()
+    };
+  }
+
+  /**
+   * Transition to next phase
+   * @private
+   */
+  _transitionToNextPhase() {
+    const currentIndex = this.phaseOrder.indexOf(this.currentPhase);
+    
+    if (currentIndex === -1 || currentIndex >= this.phaseOrder.length - 1) {
+      // Already at last phase or invalid
+      return;
+    }
+
+    const nextPhase = this.phaseOrder[currentIndex + 1];
+    const previousPhase = this.currentPhase;
+    
+    this.currentPhase = nextPhase;
+
+    this.logger.info('Interview phase transition', {
+      from: previousPhase,
+      to: nextPhase,
+      previousPhaseResponses: this.phaseResponses[previousPhase].length
+    });
+  }
+
+  // v2.1.0: BMAD integration methods
+
+  /**
+   * Get active listening counter
+   * @returns {number} Number of responses processed
+   */
+  getActiveListeningCounter() {
+    return this.activeListeningCounter;
+  }
+
+  /**
+   * Check if active listening validation needed
+   * @param {number} frequency - Validation frequency (default: 3)
+   * @returns {boolean} True if validation needed
+   */
+  shouldValidateUnderstanding(frequency = 3) {
+    return this.activeListeningCounter > 0 && 
+           this.activeListeningCounter % frequency === 0;
+  }
+
+  /**
+   * Check if pain points were detected
+   * @returns {boolean} True if pain points found
+   */
+  hasPainPointsDetected() {
+    return this.painPointsDetected;
+  }
+
+  /**
+   * Get all reformulated responses
+   * @returns {Array} Reformulated response objects
+   */
+  getReformulatedResponses() {
+    return [...this.reformulatedResponses];
+  }
+
+  /**
+   * Set glossary trigger flag
+   * @param {boolean} value - Flag value
+   */
+  setGlossaryTriggered(value) {
+    this.glossaryTriggered = value;
+  }
+
+  /**
+   * Check if glossary should be triggered
+   * @returns {boolean} Glossary trigger flag
+   */
+  shouldTriggerGlossary() {
+    return this.glossaryTriggered;
+  }
+}
+
+module.exports = InterviewState;

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

@@ -0,0 +1,253 @@
+/**
+ * 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 states (v2.1.0: added GLOSSARY, VALIDATION)
+    this.STATES = {
+      INTERVIEW: 'INTERVIEW',
+      GLOSSARY: 'GLOSSARY',      // Optional: Business glossary creation (v2.1.0)
+      ANALYSIS: 'ANALYSIS',
+      GENERATION: 'GENERATION',
+      VALIDATION: 'VALIDATION',  // Optional: Agent validation (v2.1.0)
+      COMPLETED: 'COMPLETED',
+      ERROR: 'ERROR'
+    };
+
+    // AC2: Valid state transitions (v2.1.0: added optional states)
+    // Backwards compatible: INTERVIEW -> ANALYSIS still valid
+    this.validTransitions = {
+      INTERVIEW: ['GLOSSARY', 'ANALYSIS', 'ERROR'],
+      GLOSSARY: ['ANALYSIS', 'ERROR'],
+      ANALYSIS: ['GENERATION', 'ERROR'],
+      GENERATION: ['VALIDATION', 'COMPLETED', 'ERROR'],
+      VALIDATION: ['COMPLETED', 'ERROR'],
+      COMPLETED: [], // Terminal state
+      ERROR: []      // Terminal state
+    };
+
+    // State metadata (v2.1.0: enhanced with optional state info)
+    this.currentState = this.STATES.INTERVIEW;
+    this.stateMetadata = {
+      name: this.STATES.INTERVIEW,
+      timestamp: Date.now(),
+      attempts: 0,
+      optional: false,  // Track if current state is optional
+      skippable: false,  // Track if state can be skipped
+      description: 'Collecting user requirements through structured interview'
+    };
+
+    // v2.1.0: Optional states configuration
+    this.optionalStates = ['GLOSSARY', 'VALIDATION'];
+    this.stateDescriptions = {
+      INTERVIEW: 'Collecting user requirements through structured interview',
+      GLOSSARY: 'Building business glossary for domain clarity (optional)',
+      ANALYSIS: 'Analyzing requirements and extracting insights',
+      GENERATION: 'Generating agent profile from analysis',
+      VALIDATION: 'Validating agent against mantras (optional)',
+      COMPLETED: 'Session completed successfully',
+      ERROR: 'Session terminated with error'
+    };
+
+    // 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 (v2.1.0: enhanced metadata)
+      this.currentState = newState;
+      this.stateMetadata = {
+        name: newState,
+        timestamp: Date.now(),
+        attempts: 0,
+        optional: this.optionalStates.includes(newState),
+        skippable: this.optionalStates.includes(newState),
+        description: this.stateDescriptions[newState] || ''
+      };
+
+      // 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, optional, skippable, description }
+   */
+  getCurrentState() {
+    return { ...this.stateMetadata };
+  }
+
+  /**
+   * v2.1.0: Check if current state is optional
+   * @returns {boolean} True if state is optional
+   */
+  isCurrentStateOptional() {
+    return this.optionalStates.includes(this.currentState);
+  }
+
+  /**
+   * v2.1.0: Check if a specific state is optional
+   * @param {string} stateName - State to check
+   * @returns {boolean} True if state is optional
+   */
+  isStateOptional(stateName) {
+    return this.optionalStates.includes(stateName);
+  }
+
+  /**
+   * v2.1.0: Get state description
+   * @param {string} stateName - State name
+   * @returns {string} State description
+   */
+  getStateDescription(stateName) {
+    return this.stateDescriptions[stateName] || 'Unknown state';
+  }
+
+  /**
+   * 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;