elsabro 2.3.0 → 3.7.0

package/references/interrupt-system.md

@@ -0,0 +1,681 @@
+---
+name: interrupt-system
+description: Sistema de interrupts para intervención humana
+version: 1.0.0
+---
+
+# ELSABRO Interrupt System
+
+## Vision General
+
+El sistema de Interrupts permite pausar la ejecución en puntos críticos para obtener input del usuario, aprobar decisiones, o manejar situaciones excepcionales.
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                      INTERRUPT FLOW                                       │
+├──────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│    EXECUTION                                                             │
+│        │                                                                 │
+│        ▼                                                                 │
+│    ┌──────────┐                                                          │
+│    │  NODE A  │                                                          │
+│    └────┬─────┘                                                          │
+│         │                                                                │
+│         ▼                                                                │
+│    ┌──────────────────────────────────────────┐                         │
+│    │         INTERRUPT TRIGGERED               │                         │
+│    │  ┌────────────────────────────────────┐  │                         │
+│    │  │ Reason: Approval required          │  │                         │
+│    │  │ Data: {...plan details...}         │  │                         │
+│    │  │ Options: [approve, modify, reject] │  │                         │
+│    │  └────────────────────────────────────┘  │                         │
+│    └─────────────────┬────────────────────────┘                         │
+│                      │                                                   │
+│              SAVE CHECKPOINT                                             │
+│                      │                                                   │
+│              WAIT FOR USER                                               │
+│                      │                                                   │
+│                      ▼                                                   │
+│              ┌──────────────┐                                           │
+│              │ USER RESPONDS │                                           │
+│              └──────┬───────┘                                           │
+│                     │                                                    │
+│         ┌──────────┼──────────┐                                         │
+│         ▼          ▼          ▼                                         │
+│    [approve]   [modify]   [reject]                                      │
+│         │          │          │                                         │
+│         ▼          ▼          ▼                                         │
+│      NODE B    NODE A     END                                           │
+│                (retry)                                                   │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Tipos de Interrupts
+
+### 1. Approval Gates
+
+Requiere aprobación antes de continuar.
+
+```json
+{
+  "type": "approval",
+  "trigger": "before",
+  "nodeId": "deploy",
+  "display": {
+    "title": "🚀 Deployment Approval",
+    "content": "Ready to deploy to production",
+    "data": {
+      "environment": "production",
+      "changes": 15,
+      "testsPassed": true
+    }
+  },
+  "options": [
+    { "id": "approve", "label": "Deploy Now", "next": "deploy" },
+    { "id": "delay", "label": "Schedule Later", "next": "schedule" },
+    { "id": "reject", "label": "Cancel", "next": "end" }
+  ],
+  "timeout": 86400000,
+  "default": "reject"
+}
+```
+
+### 2. Decision Points
+
+Usuario debe elegir entre opciones.
+
+```json
+{
+  "type": "decision",
+  "nodeId": "choose_approach",
+  "display": {
+    "title": "💡 Choose Implementation Approach",
+    "content": "Multiple valid approaches found",
+    "options": [
+      {
+        "id": "approach_a",
+        "label": "Server Components",
+        "description": "Better performance, simpler code",
+        "recommended": true
+      },
+      {
+        "id": "approach_b",
+        "label": "Client Components + API",
+        "description": "More flexible, easier testing"
+      }
+    ]
+  },
+  "routes": {
+    "approach_a": "implement_server",
+    "approach_b": "implement_client"
+  }
+}
+```
+
+### 3. Error Recovery
+
+Intervención cuando auto-recovery falla.
+
+```json
+{
+  "type": "error_recovery",
+  "nodeId": "fix_failed",
+  "trigger": "on_max_iterations",
+  "display": {
+    "title": "⚠️ Auto-Fix Failed",
+    "content": "Unable to automatically resolve issues",
+    "errors": ["TypeScript error in auth.ts:45", "Test failure in login.test.ts"],
+    "attempts": 3
+  },
+  "options": [
+    { "id": "retry", "label": "Retry Auto-Fix" },
+    { "id": "manual", "label": "I'll Fix Manually" },
+    { "id": "skip", "label": "Skip and Continue" },
+    { "id": "abort", "label": "Abort Execution" }
+  ]
+}
+```
+
+### 4. Information Request
+
+Necesita input del usuario para continuar.
+
+```json
+{
+  "type": "input",
+  "nodeId": "get_config",
+  "display": {
+    "title": "🔧 Configuration Required",
+    "content": "Need some information to proceed",
+    "fields": [
+      {
+        "id": "api_key",
+        "type": "secret",
+        "label": "API Key",
+        "required": true
+      },
+      {
+        "id": "environment",
+        "type": "select",
+        "label": "Environment",
+        "options": ["development", "staging", "production"],
+        "default": "development"
+      }
+    ]
+  },
+  "next": "continue_with_config"
+}
+```
+
+### 5. Confirmation
+
+Confirmar acción potencialmente destructiva.
+
+```json
+{
+  "type": "confirmation",
+  "nodeId": "before_delete",
+  "display": {
+    "title": "⚠️ Confirm Deletion",
+    "content": "This action cannot be undone",
+    "warning": "You are about to delete 5 files",
+    "files": ["src/old/auth.ts", "src/old/user.ts", "..."]
+  },
+  "options": [
+    { "id": "confirm", "label": "Yes, Delete", "style": "danger" },
+    { "id": "cancel", "label": "Cancel", "style": "default" }
+  ],
+  "default": "cancel"
+}
+```
+
+### 6. Progress Checkpoint
+
+Checkpoint manual durante operación larga.
+
+```json
+{
+  "type": "checkpoint",
+  "nodeId": "midpoint",
+  "display": {
+    "title": "📍 Progress Checkpoint",
+    "content": "50% complete - Want to continue?",
+    "progress": {
+      "completed": ["Phase 1", "Phase 2"],
+      "remaining": ["Phase 3", "Phase 4"]
+    }
+  },
+  "options": [
+    { "id": "continue", "label": "Continue" },
+    { "id": "pause", "label": "Pause Here" },
+    { "id": "stop", "label": "Stop Execution" }
+  ]
+}
+```
+
+---
+
+## API del Sistema de Interrupts
+
+### InterruptManager
+
+```javascript
+/**
+ * InterruptManager
+ * Gestiona interrupts para intervención humana
+ */
+class InterruptManager {
+  constructor(options = {}) {
+    this.checkpointManager = options.checkpointManager;
+    this.notificationService = options.notificationService;
+
+    this.config = {
+      defaultTimeout: options.defaultTimeout || 86400000, // 24 horas
+      persistInterrupts: options.persistInterrupts !== false
+    };
+
+    this.activeInterrupts = new Map();
+    this.history = [];
+  }
+
+  /**
+   * Crea y dispara un interrupt
+   */
+  async trigger(interruptDef, context = {}) {
+    const interrupt = {
+      id: this.generateId(),
+      type: interruptDef.type,
+      nodeId: interruptDef.nodeId,
+      display: this.resolveTemplate(interruptDef.display, context),
+      options: interruptDef.options,
+      routes: interruptDef.routes,
+      timeout: interruptDef.timeout || this.config.defaultTimeout,
+      default: interruptDef.default,
+      createdAt: new Date().toISOString(),
+      context: context,
+      status: 'pending'
+    };
+
+    // Guardar interrupt
+    this.activeInterrupts.set(interrupt.id, interrupt);
+
+    // Persistir en checkpoint si está habilitado
+    if (this.config.persistInterrupts && this.checkpointManager) {
+      await this.checkpointManager.saveInterrupt(interrupt.type, {
+        interruptId: interrupt.id,
+        display: interrupt.display,
+        options: interrupt.options
+      });
+    }
+
+    // Notificar al usuario
+    await this.notifyUser(interrupt);
+
+    // Configurar timeout
+    this.setupTimeout(interrupt);
+
+    return interrupt;
+  }
+
+  /**
+   * Espera respuesta del usuario
+   */
+  async waitForResponse(interruptId) {
+    const interrupt = this.activeInterrupts.get(interruptId);
+
+    if (!interrupt) {
+      throw new Error(`Interrupt ${interruptId} not found`);
+    }
+
+    return new Promise((resolve, reject) => {
+      interrupt.resolver = resolve;
+      interrupt.rejecter = reject;
+    });
+  }
+
+  /**
+   * Procesa respuesta del usuario
+   */
+  async respond(interruptId, response, additionalData = {}) {
+    const interrupt = this.activeInterrupts.get(interruptId);
+
+    if (!interrupt) {
+      throw new Error(`Interrupt ${interruptId} not found`);
+    }
+
+    if (interrupt.status !== 'pending') {
+      throw new Error(`Interrupt ${interruptId} already resolved`);
+    }
+
+    // Validar respuesta
+    const validOptions = interrupt.options.map(o => o.id);
+    if (!validOptions.includes(response)) {
+      throw new Error(`Invalid response: ${response}. Valid: ${validOptions.join(', ')}`);
+    }
+
+    // Actualizar interrupt
+    interrupt.status = 'resolved';
+    interrupt.response = response;
+    interrupt.responseData = additionalData;
+    interrupt.resolvedAt = new Date().toISOString();
+
+    // Determinar siguiente nodo
+    const nextNode = interrupt.routes
+      ? interrupt.routes[response]
+      : interrupt.options.find(o => o.id === response)?.next;
+
+    // Mover a historial
+    this.history.push(interrupt);
+    this.activeInterrupts.delete(interruptId);
+
+    // Resolver promise si existe
+    if (interrupt.resolver) {
+      interrupt.resolver({
+        response,
+        nextNode,
+        data: additionalData
+      });
+    }
+
+    return {
+      response,
+      nextNode,
+      interrupt
+    };
+  }
+
+  /**
+   * Cancela un interrupt
+   */
+  async cancel(interruptId, reason = 'cancelled') {
+    const interrupt = this.activeInterrupts.get(interruptId);
+
+    if (interrupt) {
+      interrupt.status = 'cancelled';
+      interrupt.cancelReason = reason;
+      interrupt.cancelledAt = new Date().toISOString();
+
+      this.history.push(interrupt);
+      this.activeInterrupts.delete(interruptId);
+
+      if (interrupt.rejecter) {
+        interrupt.rejecter(new Error(`Interrupt cancelled: ${reason}`));
+      }
+    }
+  }
+
+  /**
+   * Configura timeout para interrupt
+   */
+  setupTimeout(interrupt) {
+    if (interrupt.timeout > 0) {
+      setTimeout(() => {
+        if (this.activeInterrupts.has(interrupt.id)) {
+          const defaultResponse = interrupt.default;
+
+          if (defaultResponse) {
+            this.respond(interrupt.id, defaultResponse, { timedOut: true });
+          } else {
+            this.cancel(interrupt.id, 'timeout');
+          }
+        }
+      }, interrupt.timeout);
+    }
+  }
+
+  /**
+   * Notifica al usuario sobre el interrupt
+   */
+  async notifyUser(interrupt) {
+    const display = interrupt.display;
+
+    // Formato de consola
+    const notification = `
+╔════════════════════════════════════════════════════════════════╗
+║  ${this.getIcon(interrupt.type)} ${display.title.padEnd(54)}║
+╠════════════════════════════════════════════════════════════════╣
+${this.formatContent(display.content)}
+${display.data ? this.formatData(display.data) : ''}
+${display.warning ? `║  ⚠️  ${display.warning.padEnd(55)}║\n` : ''}
+╠════════════════════════════════════════════════════════════════╣
+${this.formatOptions(interrupt.options)}
+╚════════════════════════════════════════════════════════════════╝
+`;
+
+    console.log(notification);
+
+    // También notificar via servicio si está configurado
+    if (this.notificationService) {
+      await this.notificationService.send({
+        type: 'interrupt',
+        id: interrupt.id,
+        display: display
+      });
+    }
+  }
+
+  /**
+   * Lista interrupts pendientes
+   */
+  listPending() {
+    return Array.from(this.activeInterrupts.values()).map(i => ({
+      id: i.id,
+      type: i.type,
+      title: i.display.title,
+      createdAt: i.createdAt,
+      timeout: i.timeout
+    }));
+  }
+
+  /**
+   * Obtiene historial de interrupts
+   */
+  getHistory(options = {}) {
+    let history = [...this.history];
+
+    if (options.type) {
+      history = history.filter(i => i.type === options.type);
+    }
+
+    if (options.limit) {
+      history = history.slice(-options.limit);
+    }
+
+    return history;
+  }
+
+  // ==================== Helpers ====================
+
+  generateId() {
+    return `int_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;
+  }
+
+  resolveTemplate(template, context) {
+    if (typeof template === 'string') {
+      return template.replace(/\{\{([^}]+)\}\}/g, (match, path) => {
+        return this.getNestedValue(context, path.trim()) || match;
+      });
+    }
+
+    if (typeof template === 'object' && template !== null) {
+      const resolved = Array.isArray(template) ? [] : {};
+      for (const [key, value] of Object.entries(template)) {
+        resolved[key] = this.resolveTemplate(value, context);
+      }
+      return resolved;
+    }
+
+    return template;
+  }
+
+  getNestedValue(obj, path) {
+    return path.split('.').reduce((current, key) => current?.[key], obj);
+  }
+
+  getIcon(type) {
+    const icons = {
+      approval: '✅',
+      decision: '💡',
+      error_recovery: '⚠️',
+      input: '🔧',
+      confirmation: '❓',
+      checkpoint: '📍'
+    };
+    return icons[type] || '📢';
+  }
+
+  formatContent(content) {
+    const lines = content.split('\n');
+    return lines.map(line => `║  ${line.padEnd(60)}║`).join('\n');
+  }
+
+  formatData(data) {
+    let output = '';
+    for (const [key, value] of Object.entries(data)) {
+      output += `║  • ${key}: ${JSON.stringify(value).substring(0, 50).padEnd(52)}║\n`;
+    }
+    return output;
+  }
+
+  formatOptions(options) {
+    return options.map(opt => {
+      const style = opt.style === 'danger' ? '🔴' : opt.recommended ? '⭐' : '  ';
+      return `║  ${style} [${opt.id}] ${opt.label.padEnd(50)}║`;
+    }).join('\n');
+  }
+}
+```
+
+---
+
+## Integración con Flow Engine
+
+### Declaración en Flows
+
+```json
+{
+  "id": "deploy_node",
+  "type": "agent",
+  "agent": "deploy-agent",
+  "interrupt": {
+    "before": {
+      "type": "approval",
+      "condition": "{{inputs.environment}} === 'production'",
+      "display": {
+        "title": "Production Deployment Approval",
+        "content": "Review changes before deploying to production"
+      }
+    }
+  }
+}
+```
+
+### Interrupts Automáticos
+
+Configurar interrupts que se disparan automáticamente:
+
+```json
+{
+  "autoInterrupts": {
+    "onCriticalError": {
+      "type": "error_recovery",
+      "display": {
+        "title": "Critical Error",
+        "content": "{{error.message}}"
+      }
+    },
+    "onHighRisk": {
+      "type": "confirmation",
+      "condition": "{{riskScore}} > 0.8",
+      "display": {
+        "title": "High Risk Operation",
+        "warning": "This operation has been flagged as high risk"
+      }
+    },
+    "beforeDestructive": {
+      "type": "confirmation",
+      "trigger": "destructive_action",
+      "display": {
+        "title": "Confirm Destructive Action"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Comandos de Usuario
+
+### /elsabro:interrupt
+
+```bash
+/elsabro:interrupt list              # Ver interrupts pendientes
+/elsabro:interrupt respond <id> <opt>  # Responder a interrupt
+/elsabro:interrupt cancel <id>       # Cancelar interrupt
+/elsabro:interrupt history           # Ver historial de interrupts
+```
+
+---
+
+## Configuración
+
+### .planning/interrupt-config.json
+
+```json
+{
+  "interrupts": {
+    "enabled": true,
+    "defaultTimeout": 86400000,
+    "persistToCheckpoint": true,
+    "notifications": {
+      "console": true,
+      "sound": false
+    },
+    "autoInterrupts": {
+      "onCriticalError": true,
+      "beforeDestructive": true,
+      "onHighRisk": true,
+      "progressCheckpoints": false
+    },
+    "defaults": {
+      "approval": "reject",
+      "confirmation": "cancel",
+      "error_recovery": "manual"
+    }
+  }
+}
+```
+
+---
+
+## Ejemplos de Uso
+
+### Interrupt en Fase de Deploy
+
+```javascript
+// En el flow de deployment
+const deployInterrupt = await interruptManager.trigger({
+  type: 'approval',
+  nodeId: 'deploy',
+  display: {
+    title: '🚀 Production Deployment',
+    content: 'Ready to deploy v2.3.0 to production',
+    data: {
+      version: '2.3.0',
+      changes: 15,
+      tests: 'All passed',
+      coverage: '87%'
+    }
+  },
+  options: [
+    { id: 'deploy', label: 'Deploy Now', next: 'execute_deploy' },
+    { id: 'staging', label: 'Deploy to Staging First', next: 'staging_deploy' },
+    { id: 'cancel', label: 'Cancel', next: 'end' }
+  ],
+  timeout: 3600000 // 1 hora
+});
+
+const response = await interruptManager.waitForResponse(deployInterrupt.id);
+console.log(`User chose: ${response.response}`);
+```
+
+### Interrupt en Auto-Fix Loop
+
+```javascript
+// Después de N intentos de auto-fix
+if (attempts >= maxAttempts) {
+  const fixInterrupt = await interruptManager.trigger({
+    type: 'error_recovery',
+    nodeId: 'fix_loop',
+    display: {
+      title: '⚠️ Auto-Fix Exhausted',
+      content: `Failed to fix after ${attempts} attempts`,
+      errors: collectedErrors
+    },
+    options: [
+      { id: 'retry', label: 'Retry with Different Approach' },
+      { id: 'manual', label: 'I\'ll Fix Manually' },
+      { id: 'skip', label: 'Skip and Continue' },
+      { id: 'abort', label: 'Abort' }
+    ]
+  });
+
+  const response = await interruptManager.waitForResponse(fixInterrupt.id);
+
+  switch (response.response) {
+    case 'retry':
+      return retryWithDifferentApproach();
+    case 'manual':
+      return waitForManualFix();
+    case 'skip':
+      return continueWithWarning();
+    case 'abort':
+      throw new Error('Aborted by user');
+  }
+}
+```