elsabro 2.3.0 → 3.8.0

package/references/streaming.md

@@ -0,0 +1,696 @@
+---
+name: streaming
+description: Sistema de streaming de progreso en tiempo real
+version: 1.0.0
+---
+
+# ELSABRO Progress Streaming System
+
+## Vision General
+
+El sistema de streaming proporciona actualizaciones en tiempo real sobre el progreso de ejecución, permitiendo al usuario ver qué está pasando sin esperar a que termine.
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                      STREAMING MODES                                      │
+├──────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│   MODE: VALUES                                                           │
+│   ┌────────────────────────────────────────────────────────────────┐    │
+│   │ Emite el estado completo después de cada nodo                   │    │
+│   │                                                                  │    │
+│   │ { nodes: { analyze: {...}, implement: {...} }, current: "impl" }│    │
+│   └────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+│   MODE: UPDATES                                                          │
+│   ┌────────────────────────────────────────────────────────────────┐    │
+│   │ Emite solo los cambios (delta) después de cada operación        │    │
+│   │                                                                  │    │
+│   │ { type: "node_complete", node: "analyze", output: {...} }       │    │
+│   └────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+│   MODE: MESSAGES                                                         │
+│   ┌────────────────────────────────────────────────────────────────┐    │
+│   │ Emite mensajes de texto legibles para el usuario                │    │
+│   │                                                                  │    │
+│   │ "✓ Analysis complete - found 3 files to modify"                 │    │
+│   └────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Modos de Streaming
+
+### 1. Values Mode
+
+Emite el estado completo después de cada operación. Útil para debugging y UIs que necesitan el estado completo.
+
+```javascript
+// Ejemplo de output en values mode
+{
+  "mode": "values",
+  "timestamp": "2024-01-20T15:30:45.123Z",
+  "state": {
+    "flowId": "development_flow",
+    "status": "RUNNING",
+    "currentNode": "implement",
+    "progress": 0.45,
+    "nodes": {
+      "start": { "status": "COMPLETE", "duration": 50 },
+      "analyze": { "status": "COMPLETE", "duration": 15000, "output": {...} },
+      "implement": { "status": "RUNNING", "startedAt": "..." }
+    },
+    "variables": {
+      "filesAnalyzed": 12,
+      "planCreated": true
+    }
+  }
+}
+```
+
+### 2. Updates Mode
+
+Emite solo los cambios (deltas). Más eficiente en ancho de banda y procesamiento.
+
+```javascript
+// Ejemplo de outputs en updates mode
+{ "type": "flow_started", "flowId": "development_flow", "at": "..." }
+{ "type": "node_started", "node": "analyze", "at": "..." }
+{ "type": "agent_started", "agent": "Explore", "node": "analyze" }
+{ "type": "agent_complete", "agent": "Explore", "duration": 12000, "output": {...} }
+{ "type": "node_complete", "node": "analyze", "duration": 15000 }
+{ "type": "node_started", "node": "implement", "at": "..." }
+{ "type": "progress", "value": 0.45 }
+{ "type": "variable_set", "key": "filesModified", "value": ["src/auth.ts"] }
+```
+
+### 3. Messages Mode
+
+Emite mensajes de texto legibles para humanos. Ideal para CLI y logs de usuario.
+
+```javascript
+// Ejemplo de outputs en messages mode
+"🚀 Starting flow: development_flow"
+"📊 Phase 1: Analyzing codebase..."
+"  ├─ Explore agent: scanning structure"
+"  ├─ Plan agent: creating implementation plan"
+"  └─ Code-explorer: analyzing existing code"
+"✓ Analysis complete - found 5 files to modify"
+"⚙️ Phase 2: Implementing changes..."
+"  ├─ Executor: implementing auth module"
+"  └─ QA: writing tests"
+"✓ Implementation complete - 3 files created, 2 modified"
+"🔍 Phase 3: Reviewing code..."
+"✅ Flow complete! Duration: 2m 34s"
+```
+
+---
+
+## API de Streaming
+
+### StreamManager
+
+```javascript
+/**
+ * StreamManager
+ * Gestiona streaming de progreso en tiempo real
+ */
+class StreamManager {
+  constructor(options = {}) {
+    this.config = {
+      mode: options.mode || 'messages', // 'values' | 'updates' | 'messages'
+      throttle: options.throttle || 100, // ms entre emisiones
+      buffer: options.buffer || true,
+      maxBufferSize: options.maxBufferSize || 100
+    };
+
+    this.subscribers = new Set();
+    this.buffer = [];
+    this.state = {};
+    this.lastEmit = 0;
+  }
+
+  // ==================== Subscription ====================
+
+  /**
+   * Suscribe un listener al stream
+   */
+  subscribe(callback) {
+    this.subscribers.add(callback);
+
+    // Retornar función para desuscribir
+    return () => {
+      this.subscribers.delete(callback);
+    };
+  }
+
+  /**
+   * Emite a todos los suscriptores
+   */
+  emit(data) {
+    const now = Date.now();
+
+    // Throttling
+    if (this.config.throttle && now - this.lastEmit < this.config.throttle) {
+      if (this.config.buffer) {
+        this.buffer.push(data);
+        if (this.buffer.length > this.config.maxBufferSize) {
+          this.buffer.shift();
+        }
+      }
+      return;
+    }
+
+    // Flush buffer si hay
+    if (this.buffer.length > 0) {
+      const buffered = [...this.buffer];
+      this.buffer = [];
+
+      for (const item of buffered) {
+        this.emitToSubscribers(item);
+      }
+    }
+
+    this.emitToSubscribers(data);
+    this.lastEmit = now;
+  }
+
+  emitToSubscribers(data) {
+    for (const callback of this.subscribers) {
+      try {
+        callback(data);
+      } catch (error) {
+        console.error('Stream subscriber error:', error);
+      }
+    }
+  }
+
+  // ==================== Mode-Specific Emitters ====================
+
+  /**
+   * Emite según el modo configurado
+   */
+  emitProgress(event, context = {}) {
+    switch (this.config.mode) {
+      case 'values':
+        this.emitValues(event, context);
+        break;
+      case 'updates':
+        this.emitUpdates(event, context);
+        break;
+      case 'messages':
+        this.emitMessages(event, context);
+        break;
+    }
+  }
+
+  /**
+   * Emite estado completo (values mode)
+   */
+  emitValues(event, context) {
+    // Actualizar estado interno
+    this.updateState(event, context);
+
+    this.emit({
+      mode: 'values',
+      timestamp: new Date().toISOString(),
+      event: event.type,
+      state: { ...this.state }
+    });
+  }
+
+  /**
+   * Emite delta (updates mode)
+   */
+  emitUpdates(event, context) {
+    this.emit({
+      mode: 'updates',
+      timestamp: new Date().toISOString(),
+      type: event.type,
+      ...event.data,
+      ...context
+    });
+  }
+
+  /**
+   * Emite mensaje legible (messages mode)
+   */
+  emitMessages(event, context) {
+    const message = this.formatMessage(event, context);
+
+    if (message) {
+      this.emit({
+        mode: 'messages',
+        timestamp: new Date().toISOString(),
+        message
+      });
+
+      // También imprimir a consola
+      console.log(message);
+    }
+  }
+
+  // ==================== State Management ====================
+
+  /**
+   * Actualiza estado interno
+   */
+  updateState(event, context) {
+    switch (event.type) {
+      case 'flow_started':
+        this.state = {
+          flowId: event.data.flowId,
+          status: 'RUNNING',
+          startedAt: new Date().toISOString(),
+          currentNode: null,
+          progress: 0,
+          nodes: {},
+          variables: {}
+        };
+        break;
+
+      case 'node_started':
+        this.state.currentNode = event.data.nodeId;
+        this.state.nodes[event.data.nodeId] = {
+          status: 'RUNNING',
+          startedAt: new Date().toISOString()
+        };
+        break;
+
+      case 'node_complete':
+        if (this.state.nodes[event.data.nodeId]) {
+          this.state.nodes[event.data.nodeId].status = 'COMPLETE';
+          this.state.nodes[event.data.nodeId].duration = event.data.duration;
+          this.state.nodes[event.data.nodeId].output = event.data.output;
+        }
+        break;
+
+      case 'progress':
+        this.state.progress = event.data.value;
+        break;
+
+      case 'variable_set':
+        this.state.variables[event.data.key] = event.data.value;
+        break;
+
+      case 'flow_complete':
+        this.state.status = event.data.success ? 'COMPLETE' : 'FAILED';
+        this.state.completedAt = new Date().toISOString();
+        this.state.result = event.data.result;
+        break;
+    }
+  }
+
+  // ==================== Message Formatting ====================
+
+  /**
+   * Formatea evento como mensaje legible
+   */
+  formatMessage(event, context) {
+    const icons = {
+      flow_started: '🚀',
+      flow_complete: '✅',
+      flow_failed: '❌',
+      node_started: '⚙️',
+      node_complete: '✓',
+      agent_started: '  ├─',
+      agent_complete: '  ├─',
+      progress: '📊',
+      checkpoint: '💾',
+      interrupt: '⏸️',
+      error: '⚠️',
+      warning: '⚡'
+    };
+
+    const icon = icons[event.type] || '•';
+
+    switch (event.type) {
+      case 'flow_started':
+        return `${icon} Starting flow: ${event.data.flowId}`;
+
+      case 'flow_complete':
+        const duration = this.formatDuration(event.data.duration);
+        return event.data.success
+          ? `${icon} Flow complete! Duration: ${duration}`
+          : `❌ Flow failed after ${duration}`;
+
+      case 'node_started':
+        return `${icon} Phase: ${this.formatNodeName(event.data.nodeId)}...`;
+
+      case 'node_complete':
+        const nodeDuration = this.formatDuration(event.data.duration);
+        return `${icon} ${this.formatNodeName(event.data.nodeId)} complete (${nodeDuration})`;
+
+      case 'agent_started':
+        return `${icon} ${event.data.agent}: ${event.data.task || 'executing'}`;
+
+      case 'agent_complete':
+        const agentInfo = event.data.filesModified
+          ? `modified ${event.data.filesModified.length} files`
+          : 'done';
+        return `${icon} ${event.data.agent}: ${agentInfo}`;
+
+      case 'progress':
+        const percent = Math.round(event.data.value * 100);
+        const bar = this.renderProgressBar(event.data.value);
+        return `${icon} Progress: ${bar} ${percent}%`;
+
+      case 'checkpoint':
+        return `${icon} Checkpoint saved: ${event.data.checkpointId}`;
+
+      case 'interrupt':
+        return `${icon} Waiting for input: ${event.data.reason}`;
+
+      case 'error':
+        return `${icon} Error: ${event.data.message}`;
+
+      case 'parallel_started':
+        const agents = event.data.agents.join(', ');
+        return `${icon} Running ${event.data.agents.length} agents in parallel: ${agents}`;
+
+      case 'parallel_complete':
+        return `${icon} Parallel execution complete (${event.data.successful}/${event.data.total} succeeded)`;
+
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * Formatea duración en formato legible
+   */
+  formatDuration(ms) {
+    if (ms < 1000) return `${ms}ms`;
+    if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+    const minutes = Math.floor(ms / 60000);
+    const seconds = Math.round((ms % 60000) / 1000);
+    return `${minutes}m ${seconds}s`;
+  }
+
+  /**
+   * Formatea nombre de nodo para display
+   */
+  formatNodeName(nodeId) {
+    return nodeId
+      .replace(/_/g, ' ')
+      .replace(/\b\w/g, c => c.toUpperCase());
+  }
+
+  /**
+   * Renderiza barra de progreso ASCII
+   */
+  renderProgressBar(value, width = 20) {
+    const filled = Math.round(value * width);
+    const empty = width - filled;
+    return `[${'█'.repeat(filled)}${'░'.repeat(empty)}]`;
+  }
+
+  // ==================== High-Level Events ====================
+
+  /**
+   * Flow started
+   */
+  flowStarted(flowId, inputs = {}) {
+    this.emitProgress({
+      type: 'flow_started',
+      data: { flowId, inputs }
+    });
+  }
+
+  /**
+   * Flow completed
+   */
+  flowComplete(success, result = {}) {
+    const duration = this.state.startedAt
+      ? Date.now() - new Date(this.state.startedAt).getTime()
+      : 0;
+
+    this.emitProgress({
+      type: 'flow_complete',
+      data: { success, result, duration }
+    });
+  }
+
+  /**
+   * Node started
+   */
+  nodeStarted(nodeId, nodeType) {
+    this.emitProgress({
+      type: 'node_started',
+      data: { nodeId, nodeType }
+    });
+  }
+
+  /**
+   * Node completed
+   */
+  nodeComplete(nodeId, output, duration) {
+    this.emitProgress({
+      type: 'node_complete',
+      data: { nodeId, output, duration }
+    });
+  }
+
+  /**
+   * Agent started
+   */
+  agentStarted(agent, task) {
+    this.emitProgress({
+      type: 'agent_started',
+      data: { agent, task }
+    });
+  }
+
+  /**
+   * Agent completed
+   */
+  agentComplete(agent, result) {
+    this.emitProgress({
+      type: 'agent_complete',
+      data: {
+        agent,
+        success: result.success,
+        filesModified: result.filesModified,
+        duration: result.duration
+      }
+    });
+  }
+
+  /**
+   * Progress update
+   */
+  progress(value) {
+    this.emitProgress({
+      type: 'progress',
+      data: { value }
+    });
+  }
+
+  /**
+   * Parallel execution started
+   */
+  parallelStarted(agents) {
+    this.emitProgress({
+      type: 'parallel_started',
+      data: { agents }
+    });
+  }
+
+  /**
+   * Parallel execution completed
+   */
+  parallelComplete(results) {
+    const successful = results.filter(r => r.success).length;
+    this.emitProgress({
+      type: 'parallel_complete',
+      data: {
+        total: results.length,
+        successful,
+        failed: results.length - successful
+      }
+    });
+  }
+
+  /**
+   * Checkpoint saved
+   */
+  checkpointSaved(checkpointId) {
+    this.emitProgress({
+      type: 'checkpoint',
+      data: { checkpointId }
+    });
+  }
+
+  /**
+   * Interrupt triggered
+   */
+  interruptTriggered(interruptId, reason) {
+    this.emitProgress({
+      type: 'interrupt',
+      data: { interruptId, reason }
+    });
+  }
+
+  /**
+   * Error occurred
+   */
+  error(message, details = {}) {
+    this.emitProgress({
+      type: 'error',
+      data: { message, ...details }
+    });
+  }
+}
+
+// Singleton instance
+let streamInstance = null;
+
+function getStream(options) {
+  if (!streamInstance) {
+    streamInstance = new StreamManager(options);
+  }
+  return streamInstance;
+}
+
+module.exports = { StreamManager, getStream };
+```
+
+---
+
+## Integración con Flow Engine
+
+### Instrumentación Automática
+
+```javascript
+// En FlowEngine
+class FlowEngine {
+  constructor(options = {}) {
+    // ...existing code...
+    this.stream = options.stream || getStream({ mode: 'messages' });
+  }
+
+  async execute(inputs) {
+    this.stream.flowStarted(this.flow.id, inputs);
+
+    try {
+      const result = await this.runFlow(inputs);
+      this.stream.flowComplete(true, result);
+      return result;
+    } catch (error) {
+      this.stream.error(error.message);
+      this.stream.flowComplete(false, { error: error.message });
+      throw error;
+    }
+  }
+
+  async executeNode(node) {
+    this.stream.nodeStarted(node.id, node.type);
+    const startTime = Date.now();
+
+    try {
+      const result = await this.executeByType(node);
+      const duration = Date.now() - startTime;
+      this.stream.nodeComplete(node.id, result, duration);
+      return result;
+    } catch (error) {
+      this.stream.error(`Node ${node.id} failed: ${error.message}`);
+      throw error;
+    }
+  }
+
+  async executeParallelNode(node) {
+    const agents = node.branches.map(b => b.agent);
+    this.stream.parallelStarted(agents);
+
+    const results = await Promise.all(
+      node.branches.map(branch => this.executeBranch(branch))
+    );
+
+    this.stream.parallelComplete(results);
+    return results;
+  }
+}
+```
+
+---
+
+## Display Formats
+
+### Live Progress Display
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ELSABRO - Flow Execution                                     ║
+╠══════════════════════════════════════════════════════════════╣
+║  Flow: development_flow                                       ║
+║  Status: RUNNING                                              ║
+║  Progress: [████████████░░░░░░░░] 60%                        ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                               ║
+║  🚀 Starting flow: development_flow                           ║
+║  ⚙️ Phase: Analyze...                                         ║
+║    ├─ Explore: scanning structure                             ║
+║    ├─ Plan: creating implementation plan                      ║
+║    ├─ Code-explorer: analyzing existing code                  ║
+║    └─ General-purpose: checking tech debt                     ║
+║  ✓ Analyze complete (15.2s)                                   ║
+║  ⚙️ Phase: Implement...                                       ║
+║    ├─ Executor: implementing auth module                      ║
+║    └─ QA: writing tests                                       ║
+║  ⏳ Waiting for implementation...                             ║
+║                                                               ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+### Compact Progress
+
+```
+development_flow [████████████░░░░░░░░] 60% - Implementing auth module
+```
+
+---
+
+## Comandos de Usuario
+
+### /elsabro:stream
+
+```bash
+/elsabro:stream mode values    # Cambiar a modo values
+/elsabro:stream mode updates   # Cambiar a modo updates
+/elsabro:stream mode messages  # Cambiar a modo messages (default)
+/elsabro:stream pause          # Pausar streaming
+/elsabro:stream resume         # Resumir streaming
+/elsabro:stream history        # Ver historial de mensajes
+```
+
+---
+
+## Configuración
+
+### .planning/streaming-config.json
+
+```json
+{
+  "streaming": {
+    "enabled": true,
+    "mode": "messages",
+    "throttle": 100,
+    "buffer": true,
+    "maxBufferSize": 100,
+    "display": {
+      "showProgress": true,
+      "showAgents": true,
+      "showTimestamps": false,
+      "progressBarWidth": 20,
+      "colorize": true
+    },
+    "subscribers": {
+      "console": true,
+      "file": false,
+      "websocket": false
+    }
+  }
+}
+```