@howlil/ez-agents 3.4.2 → 4.0.0

package/ez-agents/bin/guards/autonomy-guard.cjs

@@ -0,0 +1,346 @@
+/**
+ * EDGE-04: Autonomy Guard
+ * 
+ * Detects irreversible operations requiring human approval.
+ * Prevents unbounded autonomy for sensitive operations.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Operations that require human approval
+const IRREVERSIBLE_OPERATIONS = [
+  // Database operations
+  'drop database',
+  'drop table',
+  'truncate',
+  'delete all',
+  'delete from',
+  'drop column',
+  'drop index',
+  'schema migration',
+  'data migration',
+  
+  // File operations
+  'rm -rf',
+  'del /f',
+  'delete directory',
+  'remove directory',
+  'format',
+  
+  // Deployment operations
+  'production deploy',
+  'deploy to production',
+  'release to production',
+  'push to production',
+  
+  // Security operations
+  'delete user',
+  'revoke access',
+  'reset credentials',
+  'delete api key',
+  'rotate secrets',
+  
+  // Infrastructure
+  'terminate instance',
+  'delete cluster',
+  'destroy environment',
+  'scale down to zero'
+];
+
+// Operations that are generally safe
+const SAFE_OPERATIONS = [
+  'read',
+  'list',
+  'get',
+  'fetch',
+  'query',
+  'select',
+  'create',
+  'insert',
+  'update',
+  'build',
+  'compile',
+  'test',
+  'lint',
+  'format'
+];
+
+/**
+ * Check if an operation is irreversible
+ * @param {string} operation - Operation description
+ * @returns {object} { irreversible: boolean, reason: string, category: string }
+ */
+function checkIrreversibleOps(operation) {
+  const lowerOp = operation.toLowerCase();
+  
+  for (const irreversible of IRREVERSIBLE_OPERATIONS) {
+    if (lowerOp.includes(irreversible)) {
+      return {
+        irreversible: true,
+        requiresApproval: true,
+        reason: `Operation contains irreversible action: "${irreversible}"`,
+        category: categorizeOperation(irreversible)
+      };
+    }
+  }
+  
+  // Check for safe operations
+  for (const safe of SAFE_OPERATIONS) {
+    if (lowerOp.includes(safe)) {
+      return {
+        irreversible: false,
+        requiresApproval: false,
+        reason: `Operation is reversible: "${safe}"`,
+        category: 'safe'
+      };
+    }
+  }
+  
+  // Unknown operation - flag for review
+  return {
+    irreversible: false,
+    requiresApproval: false,
+    reason: 'Operation not classified - assuming safe',
+    category: 'unknown'
+  };
+}
+
+/**
+ * Categorize an operation
+ * @param {string} operation - Operation description
+ * @returns {string} Category name
+ */
+function categorizeOperation(operation) {
+  const lowerOp = operation.toLowerCase();
+  
+  if (lowerOp.includes('database') || lowerOp.includes('table') || lowerOp.includes('schema')) {
+    return 'database';
+  }
+  if (lowerOp.includes('file') || lowerOp.includes('directory') || lowerOp.includes('rm ') || lowerOp.includes('del ')) {
+    return 'filesystem';
+  }
+  if (lowerOp.includes('deploy') || lowerOp.includes('production') || lowerOp.includes('release')) {
+    return 'deployment';
+  }
+  if (lowerOp.includes('user') || lowerOp.includes('access') || lowerOp.includes('credential') || lowerOp.includes('secret')) {
+    return 'security';
+  }
+  if (lowerOp.includes('instance') || lowerOp.includes('cluster') || lowerOp.includes('environment')) {
+    return 'infrastructure';
+  }
+  
+  return 'general';
+}
+
+/**
+ * Check if operation requires human approval
+ * @param {string} operation - Operation description
+ * @returns {boolean} True if approval required
+ */
+function requiresHumanApproval(operation) {
+  const result = checkIrreversibleOps(operation);
+  return result.requiresApproval;
+}
+
+/**
+ * Flag an operation for approval
+ * @param {string} operation - Operation description
+ * @param {string} reason - Reason for flagging
+ * @param {string} approvalFile - Path to write approval request
+ * @returns {object} Approval request result
+ */
+function flagOperation(operation, reason, approvalFile) {
+  const approvalRequest = {
+    timestamp: new Date().toISOString(),
+    operation,
+    reason,
+    status: 'pending',
+    category: categorizeOperation(operation)
+  };
+  
+  try {
+    // Ensure directory exists
+    const dir = path.dirname(approvalFile);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    
+    // Write approval request
+    fs.writeFileSync(
+      approvalFile,
+      `# Approval Request
+
+**Created:** ${approvalRequest.timestamp}
+**Category:** ${approvalRequest.category}
+**Status:** ${approvalRequest.status}
+
+## Operation
+
+\`\`\`
+${operation}
+\`\`\`
+
+## Reason for Approval
+
+${reason}
+
+## Approval
+
+- [ ] Approved by: _______________
+- [ ] Date: _______________
+- [ ] Comments: _______________
+`
+    );
+    
+    return {
+      success: true,
+      file: approvalFile,
+      request: approvalRequest
+    };
+  } catch (e) {
+    return {
+      success: false,
+      error: e.message,
+      request: approvalRequest
+    };
+  }
+}
+
+/**
+ * Full autonomy check
+ * @param {string} output - AI generated output describing operations
+ * @param {string} phaseDir - Phase directory
+ * @returns {object} Complete autonomy check result
+ */
+function checkAutonomy(output, phaseDir) {
+  const operations = extractOperations(output);
+  const flaggedOperations = [];
+  const safeOperations = [];
+  
+  for (const op of operations) {
+    const result = checkIrreversibleOps(op);
+    if (result.requiresApproval) {
+      flaggedOperations.push({
+        operation: op,
+        ...result
+      });
+    } else {
+      safeOperations.push({
+        operation: op,
+        ...result
+      });
+    }
+  }
+  
+  // Flag operations if any need approval
+  const approvalFiles = [];
+  if (flaggedOperations.length > 0 && phaseDir) {
+    const approvalsDir = path.join(phaseDir, '.planning', 'approvals');
+    for (let i = 0; i < flaggedOperations.length; i++) {
+      const flag = flaggedOperations[i];
+      const approvalFile = path.join(approvalsDir, `approval-${Date.now()}-${i}.md`);
+      const result = flagOperation(flag.operation, flag.reason, approvalFile);
+      if (result.success) {
+        approvalFiles.push(result.file);
+      }
+    }
+  }
+  
+  return {
+    requiresApproval: flaggedOperations.length > 0,
+    flaggedOperations,
+    safeOperations,
+    approvalFiles,
+    recommendation: flaggedOperations.length > 0
+      ? `Human approval required for ${flaggedOperations.length} operation(s). Check .planning/approvals/`
+      : 'All operations are safe to execute autonomously'
+  };
+}
+
+/**
+ * Extract operations from text
+ * @param {string} text - Text to analyze
+ * @returns {string[]} Array of operations
+ */
+function extractOperations(text) {
+  const operationPatterns = [
+    /(?:will|would|should|must|need to)\s+(?:then\s+)?([A-Z][^.!?]*(?:database|table|file|directory|deploy|production|user)[^.!?]*)/gi,
+    /(?:step \d+[:\s]+)([A-Z][^.!?]+)/gi,
+    /(?:command|operation)[:\s]+([A-Z][^.!?]+)/gi
+  ];
+  
+  const operations = new Set();
+  
+  for (const pattern of operationPatterns) {
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      const op = match[1].trim();
+      if (op.length > 10 && op.length < 200) {
+        operations.add(op);
+      }
+    }
+  }
+  
+  return Array.from(operations);
+}
+
+/**
+ * CLI entry point
+ */
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  
+  if (command === 'check' && args[1]) {
+    const operation = args.slice(1).join(' ');
+    console.log(`Checking operation: "${operation}"`);
+    
+    const result = checkIrreversibleOps(operation);
+    
+    if (result.requiresApproval) {
+      console.log(`⚠️  Requires human approval`);
+      console.log(`   Category: ${result.category}`);
+      console.log(`   Reason: ${result.reason}`);
+      process.exit(1);
+    } else {
+      console.log(`✅ Safe to execute autonomously`);
+      console.log(`   Category: ${result.category}`);
+      console.log(`   Reason: ${result.reason}`);
+      process.exit(0);
+    }
+    
+  } else if (command === 'flag' && args[1]) {
+    const operation = args[2] || args[1];
+    const reason = args[3] || 'Flagged for review';
+    const approvalFile = args[4] || `.planning/approvals/approval-${Date.now()}.md`;
+    
+    const result = flagOperation(operation, reason, approvalFile);
+    
+    if (result.success) {
+      console.log(`✅ Approval request created: ${result.file}`);
+      process.exit(0);
+    } else {
+      console.log(`❌ Failed to create approval request: ${result.error}`);
+      process.exit(1);
+    }
+    
+  } else {
+    console.log('Usage: node autonomy-guard.cjs <command> [args]');
+    console.log('Commands:');
+    console.log('  check <operation>              - Check if operation requires approval');
+    console.log('  flag <operation> [reason]      - Create approval request');
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  checkIrreversibleOps,
+  requiresHumanApproval,
+  flagOperation,
+  checkAutonomy,
+  extractOperations,
+  categorizeOperation,
+  IRREVERSIBLE_OPERATIONS,
+  SAFE_OPERATIONS
+};

package/ez-agents/bin/guards/context-budget-guard.cjs

@@ -0,0 +1,247 @@
+/**
+ * EDGE-02: Context Budget Guard
+ * 
+ * Monitors token usage and provides progressive warnings.
+ * Prevents context budget exhaustion that degrades AI quality.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Model token limits (approximate)
+const MODEL_LIMITS = {
+  'claude-3-5-sonnet': 200000,
+  'claude-3-opus': 200000,
+  'claude-3-sonnet': 200000,
+  'claude-3-haiku': 200000,
+  'gpt-4-turbo': 128000,
+  'gpt-4': 8192,
+  'gemini-pro': 32000,
+  'default': 100000
+};
+
+// Warning thresholds
+const THRESHOLDS = {
+  info: 50,      // Quality degradation begins
+  warning: 70,   // Efficiency mode engaged
+  error: 80      // Hard stop
+};
+
+/**
+ * Get token usage from executor context
+ * @param {string} contextPath - Path to context file
+ * @returns {object} { current: number, max: number, model: string }
+ */
+function getTokenUsage(contextPath) {
+  // Try to read from context file
+  if (contextPath && fs.existsSync(contextPath)) {
+    try {
+      const content = fs.readFileSync(contextPath, 'utf8');
+      // Look for token usage markers
+      const currentMatch = content.match(/tokens_used[:\s]+(\d+)/i);
+      const maxMatch = content.match(/token_limit[:\s]+(\d+)/i);
+      const modelMatch = content.match(/model[:\s]+(['"]?)([^'"\s,]+)\1/i);
+      
+      if (currentMatch && maxMatch) {
+        return {
+          current: parseInt(currentMatch[1], 10),
+          max: parseInt(maxMatch[1], 10),
+          model: modelMatch ? modelMatch[2] : 'default'
+        };
+      }
+    } catch (e) {
+      // Could not parse context file
+    }
+  }
+  
+  // Default: return estimated usage
+  return {
+    current: 0,
+    max: MODEL_LIMITS.default,
+    model: 'default'
+  };
+}
+
+/**
+ * Check context budget and return warnings
+ * @param {number} tokenUsage - Current token usage
+ * @param {number} modelLimit - Model's token limit
+ * @returns {object} { percent: number, warnings: array, shouldStop: boolean }
+ */
+function checkContextBudget(tokenUsage, modelLimit) {
+  const percent = (tokenUsage / modelLimit) * 100;
+  const warnings = [];
+  
+  if (percent >= THRESHOLDS.info) {
+    warnings.push({
+      level: 'info',
+      threshold: THRESHOLDS.info,
+      message: `Context usage at ${Math.round(percent)}% - quality degradation begins`,
+      recommendation: 'Consider splitting task or summarizing context'
+    });
+  }
+  
+  if (percent >= THRESHOLDS.warning) {
+    warnings.push({
+      level: 'warning',
+      threshold: THRESHOLDS.warning,
+      message: `Context usage at ${Math.round(percent)}% - efficiency mode engaged`,
+      recommendation: 'Strongly recommended to split task'
+    });
+  }
+  
+  if (percent >= THRESHOLDS.error) {
+    warnings.push({
+      level: 'error',
+      threshold: THRESHOLDS.error,
+      message: `Context usage at ${Math.round(percent)}% - hard stop`,
+      recommendation: 'Task MUST be split - context budget exhausted'
+    });
+  }
+  
+  return {
+    percent: Math.round(percent * 100) / 100,
+    warnings,
+    shouldStop: percent >= THRESHOLDS.error,
+    remaining: modelLimit - tokenUsage,
+    remainingPercent: Math.round((100 - percent) * 100) / 100
+  };
+}
+
+/**
+ * Determine if execution should stop
+ * @param {number} tokenUsage - Current token usage
+ * @param {number} modelLimit - Model's token limit
+ * @returns {boolean} True if should stop
+ */
+function shouldStop(tokenUsage, modelLimit) {
+  const percent = (tokenUsage / modelLimit) * 100;
+  return percent >= THRESHOLDS.error;
+}
+
+/**
+ * Get recommended action based on context usage
+ * @param {number} tokenUsage - Current token usage
+ * @param {number} modelLimit - Model's token limit
+ * @returns {string} Recommended action
+ */
+function getRecommendedAction(tokenUsage, modelLimit) {
+  const percent = (tokenUsage / modelLimit) * 100;
+  
+  if (percent >= THRESHOLDS.error) {
+    return 'STOP: Split task immediately and start new context';
+  } else if (percent >= THRESHOLDS.warning) {
+    return 'WARNING: Plan to split task soon - summarize or defer non-essential context';
+  } else if (percent >= THRESHOLDS.info) {
+    return 'INFO: Monitor context usage - consider being more concise';
+  } else {
+    return 'OK: Context usage is healthy';
+  }
+}
+
+/**
+ * Full context budget check with auto-detection
+ * @param {string} contextPath - Path to context file (optional)
+ * @param {string} model - Model name (optional, auto-detected if not provided)
+ * @returns {object} Complete context budget status
+ */
+function checkBudget(contextPath, model) {
+  const usage = getTokenUsage(contextPath);
+  
+  // Override model if provided
+  if (model && MODEL_LIMITS[model]) {
+    usage.max = MODEL_LIMITS[model];
+    usage.model = model;
+  }
+  
+  const budgetCheck = checkContextBudget(usage.current, usage.max);
+  
+  return {
+    model: usage.model,
+    limit: usage.max,
+    used: usage.current,
+    ...budgetCheck,
+    action: getRecommendedAction(usage.current, usage.max)
+  };
+}
+
+/**
+ * CLI entry point
+ */
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  
+  if (command === 'check' && args[1] && args[2]) {
+    const current = parseInt(args[1], 10);
+    const max = parseInt(args[2], 10);
+    
+    console.log(`Context Budget Check`);
+    console.log(`====================`);
+    console.log(`Current: ${current.toLocaleString()} tokens`);
+    console.log(`Limit:   ${max.toLocaleString()} tokens`);
+    console.log(`Usage:   ${((current/max)*100).toFixed(1)}%`);
+    console.log('');
+    
+    const result = checkContextBudget(current, max);
+    
+    if (result.warnings.length > 0) {
+      console.log('Warnings:');
+      result.warnings.forEach(w => {
+        console.log(`  [${w.level.toUpperCase()}] ${w.message}`);
+        console.log(`    → ${w.recommendation}`);
+      });
+    } else {
+      console.log('✅ Context usage is healthy');
+    }
+    
+    console.log('');
+    console.log(`Remaining: ${result.remaining.toLocaleString()} tokens (${result.remainingPercent}%)`);
+    console.log(`Action: ${getRecommendedAction(current, max)}`);
+    
+    process.exit(result.shouldStop ? 1 : 0);
+    
+  } else if (command === 'status') {
+    const contextPath = args[1];
+    const result = checkBudget(contextPath);
+    
+    console.log(`Context Budget Status`);
+    console.log(`=====================`);
+    console.log(`Model:  ${result.model}`);
+    console.log(`Limit:  ${result.limit.toLocaleString()} tokens`);
+    console.log(`Used:   ${result.used.toLocaleString()} tokens`);
+    console.log(`Usage:  ${result.percent}%`);
+    console.log('');
+    
+    if (result.warnings.length > 0) {
+      console.log('Warnings:');
+      result.warnings.forEach(w => {
+        console.log(`  [${w.level.toUpperCase()}] ${w.message}`);
+      });
+    } else {
+      console.log('✅ Context usage is healthy');
+    }
+    
+    console.log('');
+    console.log(`Action: ${result.action}`);
+    
+    process.exit(result.shouldStop ? 1 : 0);
+    
+  } else {
+    console.log('Usage: node context-budget-guard.cjs <command> [args]');
+    console.log('Commands:');
+    console.log('  check <current> <max>  - Check budget with explicit values');
+    console.log('  status [contextPath]   - Check budget from context file');
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  getTokenUsage,
+  checkContextBudget,
+  shouldStop,
+  getRecommendedAction,
+  checkBudget,
+  THRESHOLDS,
+  MODEL_LIMITS
+};