create-byan-agent 2.0.1 → 2.1.0

package/install/src/byan-v2/dispatcher/local-executor.js

@@ -0,0 +1,221 @@
+/**
+ * LocalExecutor - Story 3.1
+ * Handles high-complexity tasks (>60) locally without delegation
+ * 
+ * Integrates:
+ * - Logger: Log execution start/completion
+ * - MetricsCollector: Track execution metrics
+ * - ErrorTracker: Track errors
+ */
+
+const Logger = require('../observability/logger');
+const ErrorTracker = require('../observability/error-tracker');
+const MetricsCollector = require('../observability/metrics-collector');
+
+class LocalExecutor {
+  constructor() {
+    this.logger = new Logger();
+    this.errorTracker = new ErrorTracker();
+    this.metricsCollector = new MetricsCollector();
+  }
+
+  /**
+   * AC2: Execute task locally without delegation
+   * AC3: Returns { output, tokens, duration, executor: 'local' }
+   * 
+   * @param {Object} task - Task object { type, prompt, complexity, metadata? }
+   * @returns {Promise<Object>} Execution result
+   */
+  async execute(task) {
+    const startTime = Date.now();
+
+    try {
+      // AC6: Validate task
+      if (!task || typeof task !== 'object') {
+        const error = new Error('Task must be a valid object');
+        this.errorTracker.track({
+          error,
+          component: 'LocalExecutor',
+          operation: 'execute',
+          task
+        });
+        throw error;
+      }
+
+      // AC5: Log execution start
+      this.logger.info('Local execution started', {
+        type: task.type,
+        complexity: task.complexity,
+        promptLength: task.prompt?.length || 0
+      });
+
+      // AC2: Process task locally (no delegation)
+      const output = await this._processTaskLocally(task);
+
+      // Calculate metrics
+      const duration = Date.now() - startTime;
+      const tokens = this._estimateTokens(task.prompt, output);
+
+      // AC3: Build result object
+      const result = {
+        output,
+        tokens,
+        duration,
+        executor: 'local'
+      };
+
+      // AC4: Record metrics
+      this.metricsCollector.recordTaskExecution({
+        executor: 'local',
+        duration,
+        tokens,
+        success: true,
+        taskType: task.type,
+        complexity: task.complexity
+      });
+
+      // AC5: Log completion
+      this.logger.info('Local execution completed', {
+        duration,
+        tokens,
+        outputLength: output.length
+      });
+
+      return result;
+
+    } catch (error) {
+      const duration = Date.now() - startTime;
+
+      // AC6: Track error
+      this.errorTracker.track({
+        error,
+        component: 'LocalExecutor',
+        operation: 'execute',
+        task,
+        duration
+      });
+
+      // Record failed execution
+      this.metricsCollector.recordTaskExecution({
+        executor: 'local',
+        duration,
+        tokens: 0,
+        success: false,
+        error: error.message
+      });
+
+      throw error;
+    }
+  }
+
+  /**
+   * Process task using BYAN's expertise
+   * Simulates local processing for analysis/generation tasks
+   * @private
+   */
+  async _processTaskLocally(task) {
+    const { type, prompt, metadata = {} } = task;
+
+    // Simulate processing based on task type
+    switch (type) {
+      case 'analysis':
+        return this._processAnalysisTask(prompt, metadata);
+      
+      case 'generation':
+        return this._processGenerationTask(prompt, metadata);
+      
+      case 'task':
+      case 'general-purpose':
+        return this._processGeneralTask(prompt, metadata);
+      
+      default:
+        return this._processGenericTask(prompt, metadata);
+    }
+  }
+
+  /**
+   * Process analysis tasks (extract requirements, patterns)
+   * @private
+   */
+  _processAnalysisTask(prompt, metadata) {
+    // Simulated analysis output
+    const analysis = {
+      type: 'analysis',
+      input: prompt,
+      findings: [
+        'Identified key requirements from prompt',
+        'Detected patterns and themes',
+        'Extracted structured information'
+      ],
+      context: metadata.context || {},
+      timestamp: new Date().toISOString()
+    };
+
+    return JSON.stringify(analysis, null, 2);
+  }
+
+  /**
+   * Process generation tasks (create agent profiles, content)
+   * @private
+   */
+  _processGenerationTask(prompt, metadata) {
+    // Simulated generation output
+    const generation = {
+      type: 'generation',
+      prompt,
+      generated: 'Generated content based on requirements',
+      metadata: metadata,
+      timestamp: new Date().toISOString()
+    };
+
+    return JSON.stringify(generation, null, 2);
+  }
+
+  /**
+   * Process general/task type tasks
+   * @private
+   */
+  _processGeneralTask(prompt, metadata) {
+    const result = {
+      type: 'general',
+      input: prompt,
+      output: 'Processed task locally with full BYAN expertise',
+      metadata,
+      timestamp: new Date().toISOString()
+    };
+
+    return JSON.stringify(result, null, 2);
+  }
+
+  /**
+   * Process generic tasks (fallback)
+   * @private
+   */
+  _processGenericTask(prompt, metadata) {
+    const result = {
+      type: 'generic',
+      input: prompt || '',
+      output: 'Processed with local executor',
+      metadata,
+      timestamp: new Date().toISOString()
+    };
+
+    return JSON.stringify(result, null, 2);
+  }
+
+  /**
+   * Estimate token count from input/output
+   * Simple heuristic: ~1.3 tokens per word
+   * @private
+   */
+  _estimateTokens(prompt = '', output = '') {
+    const promptWords = prompt.split(/\s+/).filter(w => w.length > 0).length;
+    const outputWords = output.split(/\s+/).filter(w => w.length > 0).length;
+    
+    // Rough token estimation
+    const totalWords = promptWords + outputWords;
+    return Math.ceil(totalWords * 1.3);
+  }
+}
+
+module.exports = LocalExecutor;

package/install/src/byan-v2/dispatcher/task-router.js

@@ -0,0 +1,122 @@
+/**
+ * TaskRouter - Routes tasks based on complexity
+ * Integrates ComplexityScorer + TaskToolInterface
+ * 
+ * Thresholds:
+ * - < 30: task-tool only
+ * - 30-60: task-tool with fallback capability
+ * - > 60: local execution
+ */
+
+class ComplexityScorer {
+  /**
+   * Calculate task complexity score (0-100)
+   * Based on: prompt length, type, metadata indicators
+   */
+  calculateComplexity(task) {
+    if (!task || typeof task !== 'object') {
+      return 0;
+    }
+
+    let score = 0;
+
+    // Base score from prompt length
+    const prompt = task.prompt || '';
+    const wordCount = prompt.split(/\s+/).filter(w => w.length > 0).length;
+    score += Math.min(wordCount * 0.4, 20); // Max 20 points from length
+
+    // Type-based scoring
+    const typeScores = {
+      'explore': 8,
+      'task': 28,
+      'general-purpose': 50,
+      'code-review': 40
+    };
+    score += typeScores[task.type] || 20;
+
+    // Metadata indicators
+    const metadata = task.metadata || {};
+    if (metadata.requiresContext) score += 10;
+    if (metadata.requiresMultipleSteps) score += 20;
+    if (metadata.requiresReasoning) score += 15;
+    if (metadata.estimatedDuration === 'medium') score += 8;
+    if (metadata.estimatedDuration === 'long') score += 20;
+
+    // Keyword analysis in prompt
+    const complexityKeywords = [
+      'refactor', 'architecture', 'design', 'comprehensive',
+      'multiple', 'across', 'entire', 'system', 'migration',
+      'analyze', 'detailed'
+    ];
+
+    const lowerPrompt = prompt.toLowerCase();
+    complexityKeywords.forEach(keyword => {
+      if (lowerPrompt.includes(keyword)) {
+        score += 3;
+      }
+    });
+
+    // Cap at 100
+    return Math.min(Math.round(score), 100);
+  }
+}
+
+class TaskRouter {
+  constructor(customThresholds = {}) {
+    this.thresholds = {
+      taskToolOnly: customThresholds.taskToolOnly || 30,
+      taskToolWithFallback: customThresholds.taskToolWithFallback || 60
+    };
+    
+    this.complexityScorer = new ComplexityScorer();
+  }
+
+  /**
+   * Route a task to appropriate executor
+   * @param {Object} task - Task object with type, prompt, metadata
+   * @returns {Object} Routing decision with executor, canFallback, complexity, reasoning
+   */
+  routeTask(task) {
+    // Validation
+    if (!task) {
+      throw new Error('Task cannot be null or undefined');
+    }
+
+    if (typeof task !== 'object' || Array.isArray(task)) {
+      throw new Error('Task must be an object');
+    }
+
+    // Calculate complexity
+    const complexity = this.complexityScorer.calculateComplexity(task);
+
+    // Determine executor and fallback capability
+    let executor;
+    let canFallback;
+    let reasoning;
+
+    if (complexity < this.thresholds.taskToolOnly) {
+      executor = 'task-tool';
+      canFallback = false;
+      reasoning = `Low complexity (${complexity}) - routing to task-tool only`;
+    } else if (complexity <= this.thresholds.taskToolWithFallback) {
+      executor = 'task-tool';
+      canFallback = true;
+      reasoning = `Medium complexity (${complexity}) - routing to task-tool with fallback capability`;
+    } else {
+      executor = 'local';
+      canFallback = false;
+      reasoning = `High complexity (${complexity}) - routing to local execution for comprehensive handling`;
+    }
+
+    return {
+      executor,
+      canFallback,
+      complexity,
+      task,
+      reasoning,
+      timestamp: new Date().toISOString()
+    };
+  }
+}
+
+module.exports = TaskRouter;

package/install/src/byan-v2/dispatcher/task-tool-interface-mock.js

@@ -0,0 +1,134 @@
+/**
+ * MockTaskToolInterface - Test double for TaskToolInterface
+ * 
+ * Simulates GitHub Copilot Task Tool behavior for testing:
+ * - Predefined responses
+ * - Configurable delays
+ * - Call history tracking
+ * - Error simulation
+ */
+
+const VALID_AGENT_TYPES = ['task', 'explore', 'general-purpose'];
+
+class MockTaskToolInterface {
+  constructor(options = {}) {
+    this.delay = options.delay !== undefined ? options.delay : this._randomDelay();
+    this.responses = options.responses || {};
+    this.behavior = options.behavior || null;
+    this.callHistory = [];
+    this.maxRetries = options.maxRetries !== undefined ? options.maxRetries : 1;
+  }
+
+  /**
+   * Mock delegateTask - simulates Task Tool call
+   */
+  async delegateTask(taskPrompt, agentType) {
+    // Validation (same as real implementation)
+    if (!taskPrompt || taskPrompt.trim() === '') {
+      throw new Error('taskPrompt cannot be empty');
+    }
+
+    if (!agentType) {
+      throw new Error('agentType is required');
+    }
+
+    if (!VALID_AGENT_TYPES.includes(agentType)) {
+      throw new Error(`Invalid agent type: ${agentType}. Valid types: ${VALID_AGENT_TYPES.join(', ')}`);
+    }
+
+    // Record call
+    const call = {
+      prompt: taskPrompt,
+      agentType: agentType,
+      timestamp: Date.now()
+    };
+    this.callHistory.push(call);
+
+    // Simulate delay
+    await this._sleep(this.delay);
+
+    // Use custom behavior if provided (with retry logic for transient errors)
+    if (this.behavior) {
+      const TRANSIENT_ERRORS = ['ECONNRESET', 'ETIMEDOUT', 'ECONNREFUSED'];
+      let lastError;
+      
+      for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+        try {
+          return this.behavior(taskPrompt, agentType);
+        } catch (error) {
+          lastError = error;
+          
+          // Only retry on transient errors and if we have retries left
+          const isTransient = TRANSIENT_ERRORS.some(errCode => error.message.includes(errCode));
+          if (isTransient && attempt < this.maxRetries) {
+            await this._sleep(this.delay);
+            continue;
+          }
+          
+          // Non-transient error or out of retries - throw immediately
+          break;
+        }
+      }
+      
+      throw lastError;
+    }
+
+    // Check for predefined response
+    if (this.responses[taskPrompt]) {
+      return this.responses[taskPrompt];
+    }
+
+    // Generate default response
+    return this._generateDefaultResponse(taskPrompt, agentType);
+  }
+
+  /**
+   * Generate realistic mock response
+   */
+  _generateDefaultResponse(taskPrompt, agentType) {
+    const outputMap = {
+      'task': `Task completed: ${taskPrompt}`,
+      'explore': `Exploration results for: ${taskPrompt}`,
+      'general-purpose': `General analysis: ${taskPrompt}`
+    };
+
+    return {
+      output: outputMap[agentType] || `Response for: ${taskPrompt}`,
+      metadata: {
+        tokens: Math.floor(Math.random() * 1000) + 100,
+        duration: Math.floor(Math.random() * 2000) + 500,
+        agentType: agentType
+      }
+    };
+  }
+
+  /**
+   * Random delay between 100-500ms
+   */
+  _randomDelay() {
+    return Math.floor(Math.random() * 400) + 100;
+  }
+
+  /**
+   * Sleep utility
+   */
+  _sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Get call history
+   */
+  getCallHistory() {
+    return [...this.callHistory];
+  }
+
+  /**
+   * Clear call history
+   */
+  clearHistory() {
+    this.callHistory = [];
+  }
+}
+
+module.exports = MockTaskToolInterface;

package/install/src/byan-v2/dispatcher/task-tool-interface.js

@@ -0,0 +1,123 @@
+/**
+ * TaskToolInterface - Interface to GitHub Copilot CLI Task Tool
+ * 
+ * IMPORTANT: GitHub Copilot CLI does NOT expose a programmatic API for Task Tool.
+ * This is a conceptual interface for BYAN v2.0 architecture design.
+ * 
+ * In production, this would:
+ * 1. Use future Copilot SDK when available
+ * 2. Or shell out to `gh copilot` CLI commands
+ * 3. Or use inter-process communication with Copilot CLI
+ * 
+ * For MVP, this is a stub with comprehensive tests using MockTaskToolInterface.
+ */
+
+const VALID_AGENT_TYPES = ['task', 'explore', 'general-purpose'];
+const DEFAULT_TIMEOUT = 30000; // 30 seconds
+const TRANSIENT_ERRORS = ['ECONNRESET', 'ETIMEDOUT', 'ECONNREFUSED'];
+
+class TaskToolInterface {
+  constructor(options = {}) {
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+    this.maxRetries = options.maxRetries || 1;
+  }
+
+  /**
+   * Delegate task to GitHub Copilot agent via Task Tool
+   * 
+   * @param {string} taskPrompt - The task description for the agent
+   * @param {string} agentType - Agent type: 'task', 'explore', or 'general-purpose'
+   * @returns {Promise<{output: string, metadata: {tokens: number, duration: number}}>}
+   */
+  async delegateTask(taskPrompt, agentType) {
+    // Validation
+    if (!taskPrompt || taskPrompt.trim() === '') {
+      throw new Error('taskPrompt cannot be empty');
+    }
+
+    if (!agentType) {
+      throw new Error('agentType is required');
+    }
+
+    if (!VALID_AGENT_TYPES.includes(agentType)) {
+      throw new Error(`Invalid agent type: ${agentType}. Valid types: ${VALID_AGENT_TYPES.join(', ')}`);
+    }
+
+    // Attempt execution with retry logic
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        return await this._executeTaskWithTimeout(taskPrompt, agentType);
+      } catch (error) {
+        lastError = error;
+        
+        // Only retry on transient errors and if we have retries left
+        const isTransient = TRANSIENT_ERRORS.some(errCode => error.message.includes(errCode));
+        if (isTransient && attempt < this.maxRetries) {
+          continue;
+        }
+        
+        // Non-transient error or out of retries - throw immediately
+        break;
+      }
+    }
+
+    throw lastError;
+  }
+
+  async _executeTaskWithTimeout(taskPrompt, agentType) {
+    return new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        reject(new Error(`Task execution timeout after ${this.timeout}ms`));
+      }, this.timeout);
+
+      // TODO: Actual implementation would call Copilot Task Tool here
+      // For now, this is a stub that throws to force use of Mock in tests
+      clearTimeout(timeoutId);
+      reject(new Error('TaskToolInterface is a stub. Use MockTaskToolInterface for testing.'));
+    });
+  }
+
+  /**
+   * Build the call syntax for Task Tool (documentation)
+   * Format: Uses GitHub Copilot CLI agent invocation syntax
+   * 
+   * @param {string} prompt - Task prompt
+   * @param {string} agentType - Agent type
+   * @returns {string} - Call syntax string
+   */
+  static buildTaskCallSyntax(prompt, agentType) {
+    // Escape and sanitize prompt
+    const sanitizedPrompt = prompt
+      .replace(/\n/g, ' ')
+      .replace(/"/g, '\\"');
+
+    // Documented syntax format (conceptual - actual CLI syntax may vary)
+    return `@${agentType} "${sanitizedPrompt}"`;
+  }
+
+  /**
+   * Get documentation for Task Tool call syntax
+   * @returns {string} - Documentation
+   */
+  static getCallSyntaxDocumentation() {
+    return `
+GitHub Copilot CLI Task Tool Syntax (Conceptual):
+
+@<agent_type> "<prompt>"
+
+Where:
+- agent_type: 'task' | 'explore' | 'general-purpose'
+- prompt: Natural language task description
+
+Examples:
+- @task "Run all unit tests and report results"
+- @explore "Find all API endpoint definitions"
+- @general-purpose "Refactor authentication logic"
+
+Note: Actual implementation depends on Copilot CLI SDK availability.
+    `.trim();
+  }
+}
+
+module.exports = TaskToolInterface;

package/install/src/byan-v2/generation/agent-profile-validator.js

@@ -0,0 +1,113 @@
+const yaml = require('js-yaml');
+
+class AgentProfileValidator {
+  validate(profileContent) {
+    const result = {
+      valid: true,
+      errors: [],
+      warnings: []
+    };
+
+    if (!this.checkFileSize(profileContent)) {
+      result.valid = false;
+      result.errors.push('Profile exceeds 50KB size limit');
+      return result;
+    }
+
+    const frontmatterResult = this.validateYamlFrontmatter(profileContent);
+    if (!frontmatterResult.valid) {
+      result.valid = false;
+      result.errors.push(...frontmatterResult.errors);
+      return result;
+    }
+
+    const { data } = frontmatterResult;
+
+    if (!data.name) {
+      result.valid = false;
+      result.errors.push('Missing required field: name');
+    } else if (!this.validateNameFormat(data.name)) {
+      result.valid = false;
+      result.errors.push('Invalid name format (use lowercase, alphanumeric, hyphens only)');
+    }
+
+    if (!data.description) {
+      result.valid = false;
+      result.errors.push('Missing required field: description');
+    } else if (!this.validateDescriptionLength(data.description)) {
+      result.valid = false;
+      result.errors.push('Description must be 10-200 characters');
+    }
+
+    if (this.detectEmojis(profileContent)) {
+      result.warnings.push('Emoji detected (Mantra IA-23: Zero Emoji Pollution)');
+    }
+
+    if (!this.hasCapabilitiesSection(profileContent)) {
+      result.warnings.push('No capabilities section found');
+    }
+
+    return result;
+  }
+
+  validateYamlFrontmatter(content) {
+    const result = {
+      valid: true,
+      errors: [],
+      data: null
+    };
+
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    
+    if (!match) {
+      result.valid = false;
+      result.errors.push('Missing YAML frontmatter');
+      return result;
+    }
+
+    try {
+      result.data = yaml.load(match[1]);
+    } catch (e) {
+      result.valid = false;
+      result.errors.push(`Invalid YAML: ${e.message}`);
+    }
+
+    return result;
+  }
+
+  validateNameFormat(name) {
+    if (!name || name.length === 0) {
+      return false;
+    }
+
+    const validNameRegex = /^[a-z0-9-]+$/;
+    return validNameRegex.test(name);
+  }
+
+  validateDescriptionLength(description) {
+    if (!description) {
+      return false;
+    }
+
+    const len = description.length;
+    return len >= 10 && len <= 200;
+  }
+
+  detectEmojis(text) {
+    const emojiRegex = /[\u{1F300}-\u{1F9FF}]|[\u{2600}-\u{26FF}]|[\u{2700}-\u{27BF}]/u;
+    return emojiRegex.test(text);
+  }
+
+  checkFileSize(content) {
+    const sizeInBytes = Buffer.byteLength(content, 'utf-8');
+    const maxSize = 50 * 1024;
+    return sizeInBytes <= maxSize;
+  }
+
+  hasCapabilitiesSection(content) {
+    const capabilitiesRegex = /^#{1,3}\s+(Capabilit(y|ies))/mi;
+    return capabilitiesRegex.test(content);
+  }
+}
+
+module.exports = AgentProfileValidator;