@saulwade/swl-ses 1.3.8 → 1.4.0

package/gateway/agent-executor.js

@@ -0,0 +1,322 @@
+'use strict';
+
+/**
+ * agent-executor.js
+ *
+ * Contrato unificado de ejecución de agentes SWL.
+ *
+ * Implementa el patrón "execute(name, input) → string" de Managed Agents:
+ * cualquier agente SWL expone la misma interfaz al orquestador, independientemente
+ * de su tipo (implementador, planificador, revisor, etc.).
+ *
+ * Esto permite que el gateway/cron y el orquestador-swl invoquen agentes
+ * de forma programática con trazabilidad completa via run-log.js y HandoffContext.
+ *
+ * Integra con:
+ *   - manifiestos/handoff-context.json  — schema de trazabilidad entre agentes
+ *   - hooks/lib/run-log.js              — observabilidad de invocaciones
+ *   - hooks/lib/abort-registry.js       — cancelación cooperativa
+ *
+ * Uso:
+ *   const executor = require('./agent-executor');
+ *
+ *   // Invocación simple
+ *   const result = await executor.executeAgent('planificador-swl', 'Planifica la feature X');
+ *
+ *   // Con HandoffContext (trazabilidad multi-agente)
+ *   const result = await executor.executeAgent('implementador-swl', prompt, {
+ *     handoff: {
+ *       reason:        'task_delegation',
+ *       parentAgent:   'orquestador-swl',
+ *       transferCount: 1,
+ *       sessionId:     'abc123',
+ *     },
+ *     timeoutMs: 300_000,
+ *   });
+ *
+ *   console.log(result.output);   // string con respuesta del agente
+ *   console.log(result.status);   // 'completed' | 'failed' | 'aborted' | 'timeout'
+ *   console.log(result.handoff);  // HandoffContext actualizado (transferCount++)
+ *
+ * @module gateway/agent-executor
+ */
+
+const { execFile }  = require('child_process');
+const path          = require('path');
+
+// run-log puede no estar disponible fuera del repo — importación defensiva
+let runLog;
+try { runLog = require('../hooks/lib/run-log'); } catch (_) { runLog = null; }
+
+// abort-registry — cancelación cooperativa
+let abortRegistry;
+try { abortRegistry = require('../hooks/lib/abort-registry'); } catch (_) { abortRegistry = null; }
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+/** Máximo de transferencias en cadena antes de rechazar (anti-loop). */
+const MAX_TRANSFER_COUNT = 10;
+
+/** Timeout por defecto en ms (5 minutos). */
+const DEFAULT_TIMEOUT_MS = 300_000;
+
+/** Modelo Claude por defecto para agentes programáticos. */
+const DEFAULT_MODEL = 'claude-sonnet-4-6';
+
+// ---------------------------------------------------------------------------
+// Tipos (JSDoc)
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {{
+ *   reason:        string,
+ *   parentAgent:   string,
+ *   transferCount: number,
+ *   sessionId?:    string,
+ *   metadata?:     object,
+ * }} HandoffContext
+ *
+ * @typedef {{
+ *   output:    string,
+ *   sessionId: string|null,
+ *   status:    'completed'|'failed'|'aborted'|'timeout',
+ *   handoff:   HandoffContext|null,
+ *   durationMs: number,
+ *   error?:    string,
+ * }} ExecuteResult
+ *
+ * @typedef {{
+ *   handoff?:   HandoffContext,
+ *   sessionId?: string,
+ *   timeoutMs?: number,
+ *   model?:     string,
+ *   cwd?:       string,
+ * }} ExecuteOptions
+ */
+
+// ---------------------------------------------------------------------------
+// API principal
+// ---------------------------------------------------------------------------
+
+/**
+ * Ejecuta un agente SWL con una entrada dada y retorna su output.
+ * Implementa el contrato unificado execute(name, input) → string de Managed Agents.
+ *
+ * @param {string}         agentName - Nombre del agente SWL (ej: 'planificador-swl').
+ * @param {string}         input     - Prompt de entrada para el agente.
+ * @param {ExecuteOptions} [opts]    - Opciones de ejecución.
+ * @returns {Promise<ExecuteResult>}
+ */
+async function executeAgent(agentName, input, opts) {
+  const {
+    handoff    = null,
+    sessionId  = null,
+    timeoutMs  = DEFAULT_TIMEOUT_MS,
+    model      = DEFAULT_MODEL,
+    cwd        = process.cwd(),
+  } = opts || {};
+
+  const startMs = Date.now();
+
+  // --- Validación de anti-loop de HandoffContext ---
+  if (handoff && handoff.transferCount >= MAX_TRANSFER_COUNT) {
+    return {
+      output:     '',
+      sessionId,
+      status:     'failed',
+      handoff:    null,
+      durationMs: 0,
+      error:      `transferCount (${handoff.transferCount}) supera el máximo permitido (${MAX_TRANSFER_COUNT}). Posible loop de agentes.`,
+    };
+  }
+
+  // --- Verificar si hay abort activo ---
+  if (abortRegistry) {
+    try {
+      const estado = abortRegistry.getStatus();
+      if (estado === 'force' || estado === 'graceful') {
+        return {
+          output:     '',
+          sessionId,
+          status:     'aborted',
+          handoff:    null,
+          durationMs: Date.now() - startMs,
+          error:      `Ejecución cancelada: abort ${estado} activo.`,
+        };
+      }
+    } catch (_) { /* abort-registry no crítico */ }
+  }
+
+  // --- Registrar invocación en run-log ---
+  if (runLog && sessionId) {
+    try {
+      runLog.agentInvoked(sessionId, agentName);
+    } catch (_) { /* observabilidad no crítica */ }
+  }
+
+  // --- Construir HandoffContext actualizado ---
+  const handoffActualizado = handoff ? {
+    ...handoff,
+    transferCount: handoff.transferCount + 1,
+    sessionId:     sessionId || handoff.sessionId,
+  } : null;
+
+  // --- Construir prompt con contexto de agente ---
+  const promptCompleto = _buildPrompt(agentName, input, handoffActualizado);
+
+  // --- Ejecutar via claude CLI ---
+  return new Promise((resolve) => {
+    const args = [
+      '--print',
+      '--model', model,
+      '--no-update-check',
+      promptCompleto,
+    ];
+
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+
+    const proc = execFile('claude', args, {
+      cwd,
+      timeout:   timeoutMs,
+      maxBuffer: 10 * 1024 * 1024, // 10 MB
+      env:       { ...process.env },
+    }, (err, out, err2) => {
+      stdout = out || '';
+      stderr = err2 || '';
+
+      const durationMs = Date.now() - startMs;
+
+      if (timedOut) {
+        resolve({ output: stdout, sessionId, status: 'timeout', handoff: handoffActualizado, durationMs, error: 'timeout' });
+        return;
+      }
+
+      if (err && !stdout) {
+        resolve({
+          output:     stderr || err.message,
+          sessionId,
+          status:     'failed',
+          handoff:    handoffActualizado,
+          durationMs,
+          error:      err.message,
+        });
+        return;
+      }
+
+      resolve({
+        output:    stdout.trim(),
+        sessionId,
+        status:    'completed',
+        handoff:   handoffActualizado,
+        durationMs,
+      });
+    });
+
+    proc.on('error', (err) => {
+      if (err.code === 'ETIMEDOUT') timedOut = true;
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Construye el prompt completo incluyendo el rol del agente y el HandoffContext.
+ * El agente recibirá suficiente contexto para actuar sin conocer la conversación padre.
+ *
+ * @param {string}           agentName
+ * @param {string}           input
+ * @param {HandoffContext|null} handoff
+ * @returns {string}
+ */
+function _buildPrompt(agentName, input, handoff) {
+  const partes = [];
+
+  if (handoff) {
+    partes.push(`[Contexto de transferencia]`);
+    partes.push(`Agente solicitante: ${handoff.parentAgent}`);
+    partes.push(`Motivo: ${handoff.reason}`);
+    partes.push(`Transferencia #${handoff.transferCount}`);
+    if (handoff.sessionId) partes.push(`Sesión: ${handoff.sessionId}`);
+    partes.push('');
+  }
+
+  partes.push(`Eres el agente ${agentName} del sistema SWL.`);
+  partes.push('');
+  partes.push(input);
+
+  return partes.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Ejecución en lote (pipeline)
+// ---------------------------------------------------------------------------
+
+/**
+ * Ejecuta una secuencia de agentes en pipeline, pasando el output de cada uno
+ * como parte del input del siguiente. Implementa el patrón PipelineContext.
+ *
+ * @param {Array<{ agentName: string, buildInput: (prevOutput: string, stepResults: object[]) => string }>} pasos
+ * @param {{ pipelineName: string, sessionId?: string, timeoutMs?: number }} opts
+ * @returns {Promise<{ status: string, stepResults: object[], finalOutput: string }>}
+ */
+async function executePipeline(pasos, opts) {
+  const { pipelineName, sessionId = null, timeoutMs = DEFAULT_TIMEOUT_MS } = opts || {};
+  const stepResults = [];
+  let prevOutput    = '';
+  let finalOutput   = '';
+
+  for (let i = 0; i < pasos.length; i++) {
+    const { agentName, buildInput } = pasos[i];
+    const input = buildInput(prevOutput, stepResults);
+
+    const handoff = {
+      reason:        'pipeline_execution',
+      parentAgent:   pipelineName,
+      transferCount: i,
+      sessionId,
+      metadata: {
+        pipelineName,
+        currentStep: i + 1,
+        totalSteps:  pasos.length,
+        isLastStep:  i === pasos.length - 1,
+      },
+    };
+
+    const result = await executeAgent(agentName, input, { handoff, sessionId, timeoutMs });
+
+    stepResults.push({
+      step:      i + 1,
+      agentName,
+      output:    { text: result.output },
+      status:    result.status === 'completed' ? 'completed' : 'failed',
+      durationMs: result.durationMs,
+    });
+
+    if (result.status !== 'completed') {
+      return { status: result.status, stepResults, finalOutput: result.output };
+    }
+
+    prevOutput  = result.output;
+    finalOutput = result.output;
+  }
+
+  return { status: 'completed', stepResults, finalOutput };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  executeAgent,
+  executePipeline,
+  MAX_TRANSFER_COUNT,
+  DEFAULT_TIMEOUT_MS,
+};

package/gateway/command-relay.js

@@ -0,0 +1,271 @@
+'use strict';
+
+/**
+ * Command Relay — Componente que recibe comandos entrantes desde cualquier
+ * adaptador del gateway (Telegram, Discord, Webhook, etc.) y los encola en
+ * `.planning/inbox/` para su procesamiento por Claude Code.
+ *
+ * Complementa a GatewayRunner._handleIncoming() añadiendo:
+ *   - Whitelist estricta de usuarios (allowedUsers)
+ *   - Whitelist de plataformas con relay habilitado
+ *   - Sanitización de texto (previene payload injection)
+ *   - Audit trail en .planning/inbox/audit.jsonl
+ *   - Rate limiting por usuario (opcional)
+ *   - Dedup por content hash en ventana corta
+ *
+ * Inspirado en Claude-Code-Remote (smart-injector.js) pero portable
+ * Windows/Linux/macOS: no depende de AppleScript ni tmux. El consumo se
+ * realiza vía el comando /swl:inbox o un daemon tmux opt-in.
+ *
+ * Uso (desde gateway/index.js):
+ *   const relay = new CommandRelay(baseDir, config);
+ *   relay.recibirComando(message);
+ *
+ * @module gateway/command-relay
+ */
+
+const fs     = require('fs');
+const path   = require('path');
+const crypto = require('crypto');
+const { atomicWriteJSON } = require('../hooks/lib/atomic-write');
+const { EventChannel, EVENTS } = require('./lib/event-channel');
+
+const INBOX_DIR = '.planning/inbox';
+const AUDIT_FILE = 'audit.jsonl';
+const MAX_TEXT_LEN = 4000;
+const DEDUP_WINDOW_MS = 30 * 1000; // 30 segundos
+
+// Patrones prohibidos en el texto (prevención de payload injection básica)
+const PATRONES_PROHIBIDOS = [
+  /<\s*script/i,
+  /javascript:/i,
+  /data:text\/html/i,
+  // Referencias directas a archivos sensibles
+  /\.env\b/,
+  /id_rsa\b/,
+  /\.ssh\/\b/,
+];
+
+class CommandRelay {
+  /**
+   * @param {string} baseDir - Raíz del proyecto
+   * @param {object} config  - Configuración del gateway (gateway-config.json)
+   */
+  constructor(baseDir, config = {}) {
+    this.baseDir = baseDir;
+    this.relayConfig = config.relay || {};
+    this._dedupCache = new Map(); // hash → ts
+    this._rateCache  = new Map(); // userId → { ts, count }
+    this.events = new EventChannel();  // pub/sub: cmd:received|rejected|queued|processed
+  }
+
+  /**
+   * Suscribir a eventos del relay. Retorna función de unsubscribe.
+   * Tipos disponibles en EVENTS (gateway/lib/event-channel.js):
+   *   'cmd:received' | 'cmd:rejected' | 'cmd:queued' | 'cmd:processed' | '*'
+   */
+  on(eventType, callback) {
+    return this.events.on(eventType, callback);
+  }
+
+  /**
+   * Verifica si el relay está habilitado globalmente.
+   */
+  habilitado() {
+    return this.relayConfig.enabled === true;
+  }
+
+  /**
+   * Verifica si un usuario está autorizado para enviar comandos.
+   * @param {string} platform - nombre del adaptador (telegram, discord, etc.)
+   * @param {string} userId - ID del usuario en esa plataforma
+   */
+  usuarioAutorizado(platform, userId) {
+    if (!this.habilitado()) return false;
+    const platforms = this.relayConfig.platforms || {};
+    const pconf = platforms[platform];
+    if (!pconf || pconf.enabled !== true) return false;
+    const allowed = pconf.allowedUsers || [];
+    if (allowed.length === 0) return false; // sin whitelist, bloquear
+    return allowed.includes(String(userId));
+  }
+
+  /**
+   * Sanitiza un texto entrante. Retorna null si es inválido.
+   */
+  sanitizar(texto) {
+    if (typeof texto !== 'string') return null;
+    const t = texto.trim();
+    if (!t) return null;
+    if (t.length > MAX_TEXT_LEN) return null;
+    for (const re of PATRONES_PROHIBIDOS) {
+      if (re.test(t)) return null;
+    }
+    return t;
+  }
+
+  /**
+   * Rate limit simple: máx N mensajes por usuario cada M segundos.
+   */
+  dentroDeRateLimit(userId) {
+    const lim = this.relayConfig.rateLimit || { maxPerMinute: 10 };
+    const ventanaMs = 60 * 1000;
+    const ahora = Date.now();
+    const estado = this._rateCache.get(userId) || { resetAt: ahora + ventanaMs, count: 0 };
+    if (ahora > estado.resetAt) {
+      estado.resetAt = ahora + ventanaMs;
+      estado.count = 0;
+    }
+    estado.count += 1;
+    this._rateCache.set(userId, estado);
+    return estado.count <= (lim.maxPerMinute || 10);
+  }
+
+  /**
+   * Dedup por hash de contenido en ventana corta.
+   */
+  esDuplicado(platform, userId, texto) {
+    const hash = crypto.createHash('sha1')
+      .update(`${platform}:${userId}:${texto}`)
+      .digest('hex');
+    const ahora = Date.now();
+    // Limpiar entradas viejas
+    for (const [h, ts] of this._dedupCache.entries()) {
+      if (ahora - ts > DEDUP_WINDOW_MS) this._dedupCache.delete(h);
+    }
+    if (this._dedupCache.has(hash)) return true;
+    this._dedupCache.set(hash, ahora);
+    return false;
+  }
+
+  /**
+   * Recibe un comando entrante y lo encola en .planning/inbox/ si pasa
+   * todas las validaciones. Retorna { success: boolean, reason?: string, id?: string }.
+   */
+  recibirComando(message) {
+    if (!this.habilitado()) {
+      return { success: false, reason: 'relay-disabled' };
+    }
+
+    const platform = message.platform || 'unknown';
+    const userId   = String(message.userId || 'unknown');
+    const userName = message.userName || 'unknown';
+
+    this.events.emit({ type: EVENTS.CMD_RECEIVED, platform, userId, userName, textoPreview: (message.text || '').slice(0, 80) });
+
+    if (!this.usuarioAutorizado(platform, userId)) {
+      this._auditar({ platform, userId, userName, accion: 'rechazado', razon: 'usuario-no-autorizado', textoPreview: (message.text || '').slice(0, 80) });
+      this.events.emit({ type: EVENTS.CMD_REJECTED, platform, userId, userName, reason: 'user-not-authorized' });
+      return { success: false, reason: 'user-not-authorized' };
+    }
+
+    const texto = this.sanitizar(message.text || message.args || '');
+    if (!texto) {
+      this._auditar({ platform, userId, userName, accion: 'rechazado', razon: 'texto-invalido' });
+      this.events.emit({ type: EVENTS.CMD_REJECTED, platform, userId, userName, reason: 'invalid-text' });
+      return { success: false, reason: 'invalid-text' };
+    }
+
+    if (!this.dentroDeRateLimit(userId)) {
+      this._auditar({ platform, userId, userName, accion: 'rechazado', razon: 'rate-limit', textoPreview: texto.slice(0, 80) });
+      this.events.emit({ type: EVENTS.CMD_REJECTED, platform, userId, userName, reason: 'rate-limit-exceeded' });
+      return { success: false, reason: 'rate-limit-exceeded' };
+    }
+
+    if (this.esDuplicado(platform, userId, texto)) {
+      this._auditar({ platform, userId, userName, accion: 'dedup', textoPreview: texto.slice(0, 80) });
+      this.events.emit({ type: EVENTS.CMD_REJECTED, platform, userId, userName, reason: 'duplicate' });
+      return { success: false, reason: 'duplicate' };
+    }
+
+    // Encolar
+    const id = `cmd-${Date.now().toString(36)}-${crypto.randomBytes(3).toString('hex')}`;
+    const inboxDir = path.join(this.baseDir, INBOX_DIR);
+    if (!fs.existsSync(inboxDir)) fs.mkdirSync(inboxDir, { recursive: true });
+
+    const cmd = {
+      id,
+      platform,
+      userId,
+      userName,
+      texto,
+      recibidoEn: new Date().toISOString(),
+      estado: 'pending',
+      chatId: message.chatId || null,
+      comando: message.command || null,
+    };
+
+    try {
+      atomicWriteJSON(path.join(inboxDir, `${id}.json`), cmd);
+      this._auditar({ platform, userId, userName, accion: 'encolado', id, textoPreview: texto.slice(0, 80) });
+      this.events.emit({ type: EVENTS.CMD_QUEUED, id, platform, userId, userName, textoPreview: texto.slice(0, 80) });
+      return { success: true, id };
+    } catch (err) {
+      this._auditar({ platform, userId, userName, accion: 'error-escritura', razon: err.message });
+      this.events.emit({ type: EVENTS.CMD_REJECTED, platform, userId, userName, reason: 'write-error', error: err.message });
+      return { success: false, reason: 'write-error' };
+    }
+  }
+
+  /**
+   * Lista comandos pendientes en el inbox.
+   * @param {object} [opts]
+   * @param {number} [opts.limit=20]
+   * @returns {Array<object>}
+   */
+  listarPendientes(opts = {}) {
+    const limit = opts.limit || 20;
+    const inboxDir = path.join(this.baseDir, INBOX_DIR);
+    if (!fs.existsSync(inboxDir)) return [];
+    const archivos = fs.readdirSync(inboxDir)
+      .filter(f => f.startsWith('cmd-') && f.endsWith('.json'));
+    const items = [];
+    for (const a of archivos.sort()) {
+      try {
+        const obj = JSON.parse(fs.readFileSync(path.join(inboxDir, a), 'utf8'));
+        if (obj.estado === 'pending') items.push(obj);
+      } catch (err) {
+        // Archivo malformado o concurrencia con marcarProcesado: ignorar este
+        // archivo y continuar con el resto del inbox. No bloquear la lista.
+      }
+      if (items.length >= limit) break;
+    }
+    return items;
+  }
+
+  /**
+   * Marca un comando como procesado.
+   */
+  marcarProcesado(id, resultado = {}) {
+    const inboxDir = path.join(this.baseDir, INBOX_DIR);
+    const filePath = path.join(inboxDir, `${id}.json`);
+    if (!fs.existsSync(filePath)) return false;
+    try {
+      const obj = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      obj.estado = 'processed';
+      obj.procesadoEn = new Date().toISOString();
+      obj.resultado = resultado;
+      atomicWriteJSON(filePath, obj);
+      this._auditar({ platform: obj.platform, userId: obj.userId, accion: 'procesado', id });
+      this.events.emit({ type: EVENTS.CMD_PROCESSED, id, platform: obj.platform, userId: obj.userId, resultado });
+      return true;
+    } catch (_) {
+      return false;
+    }
+  }
+
+  /**
+   * Escribe una entrada al audit trail del inbox.
+   * @private
+   */
+  _auditar(entrada) {
+    try {
+      const inboxDir = path.join(this.baseDir, INBOX_DIR);
+      if (!fs.existsSync(inboxDir)) fs.mkdirSync(inboxDir, { recursive: true });
+      const linea = JSON.stringify({ ts: new Date().toISOString(), ...entrada }) + '\n';
+      fs.appendFileSync(path.join(inboxDir, AUDIT_FILE), linea);
+    } catch (_) { /* silencioso */ }
+  }
+}
+
+module.exports = CommandRelay;