@saulwade/swl-ses 1.0.0

package/hooks/lib/guardrail-metrics.js

@@ -0,0 +1,202 @@
+'use strict';
+
+/**
+ * guardrail-metrics.js — Métricas de activación y bloqueo de guardrails (hooks).
+ *
+ * Registra cuántas veces se activa y cuántas bloquea cada hook por sesión.
+ * Los datos se persisten en /tmp/swl-guardrail-metrics-{sessionId}.json para
+ * sobrevivir entre invocaciones del mismo hook.
+ *
+ * Principio adoptado del PDF "A Practical Guide to Building Agents":
+ *   "Monitorear guardrail effectiveness basado en real-world data.
+ *    Guardrails no son set-and-forget; evolucionan con el agente."
+ *
+ * API pública:
+ *   recordActivation(hookName, sessionId, blocked)  — registra una activación
+ *   getMetrics(sessionId)                            — lee métricas de la sesión
+ *   formatearResumen(metricas)                       — formatea para mostrar al usuario
+ *
+ * Zero-dependencies: solo usa fs, path, os del runtime de Node.
+ *
+ * @module hooks/lib/guardrail-metrics
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+// ---------------------------------------------------------------------------
+// Internos
+// ---------------------------------------------------------------------------
+
+/**
+ * Devuelve la ruta del bridge de métricas para la sesión dada.
+ * @param {string} sessionId
+ * @returns {string}
+ */
+function rutaBridge(sessionId) {
+  const sid = (sessionId || 'default').replace(/[^a-zA-Z0-9_-]/g, '_');
+  return path.join(os.tmpdir(), `swl-guardrail-metrics-${sid}.json`);
+}
+
+/**
+ * Lee el estado actual del bridge o devuelve uno vacío.
+ * @param {string} bridgePath
+ * @returns {object}
+ */
+function leerBridge(bridgePath) {
+  try {
+    const raw = fs.readFileSync(bridgePath, 'utf8');
+    const datos = JSON.parse(raw);
+    datos.hooks = datos.hooks || {};
+    return datos;
+  } catch (_) {
+    return { sessionId: '', hooks: {} };
+  }
+}
+
+/**
+ * Persiste el bridge de métricas.
+ * @param {string} bridgePath
+ * @param {object} datos
+ */
+function guardarBridge(bridgePath, datos) {
+  try {
+    fs.writeFileSync(bridgePath, JSON.stringify(datos, null, 2), 'utf8');
+  } catch (_) {
+    // I/O error — silencioso para no interrumpir hooks
+  }
+}
+
+// ---------------------------------------------------------------------------
+// API pública
+// ---------------------------------------------------------------------------
+
+/**
+ * Registra una activación de guardrail.
+ *
+ * @param {string}  hookName  - Nombre del archivo del hook (ej: "escaneo-secretos.js").
+ * @param {string}  sessionId - ID de la sesión activa.
+ * @param {boolean} blocked   - true si el hook bloqueó (exit code 2), false si fue warning.
+ */
+function recordActivation(hookName, sessionId, blocked) {
+  const bridgePath = rutaBridge(sessionId);
+  const datos = leerBridge(bridgePath);
+
+  datos.sessionId = sessionId || datos.sessionId || 'default';
+
+  if (!datos.hooks[hookName]) {
+    datos.hooks[hookName] = {
+      activaciones: 0,
+      bloqueos: 0,
+      warnings: 0,
+      ultimaActivacion: null,
+      ultimoBloqueo: null,
+    };
+  }
+
+  const entrada = datos.hooks[hookName];
+  entrada.activaciones += 1;
+  entrada.ultimaActivacion = new Date().toISOString();
+
+  if (blocked) {
+    entrada.bloqueos += 1;
+    entrada.ultimoBloqueo = new Date().toISOString();
+  } else {
+    entrada.warnings += 1;
+  }
+
+  guardarBridge(bridgePath, datos);
+}
+
+/**
+ * Lee las métricas de guardrails de la sesión actual.
+ *
+ * @param {string} sessionId
+ * @returns {{ sessionId: string, hooks: object }}
+ */
+function getMetrics(sessionId) {
+  const bridgePath = rutaBridge(sessionId);
+  return leerBridge(bridgePath);
+}
+
+/**
+ * Formatea las métricas de guardrails como texto markdown para mostrar en reportes.
+ *
+ * @param {object} metricas - Resultado de getMetrics().
+ * @returns {string} Sección markdown con tabla de guardrails.
+ */
+function formatearResumen(metricas) {
+  const hooks = metricas.hooks || {};
+  const entradas = Object.entries(hooks);
+
+  if (entradas.length === 0) {
+    return '## Guardrails\n\n_Ningún guardrail se activó en esta sesión._\n\n';
+  }
+
+  // Ordenar por bloqueos desc, luego por activaciones desc
+  entradas.sort(([, a], [, b]) => {
+    if (b.bloqueos !== a.bloqueos) return b.bloqueos - a.bloqueos;
+    return b.activaciones - a.activaciones;
+  });
+
+  const filas = entradas.map(([nombre, datos]) => {
+    const tasaBloqueo = datos.activaciones > 0
+      ? Math.round((datos.bloqueos / datos.activaciones) * 100)
+      : 0;
+    const nombreCorto = nombre.replace('.js', '');
+    return `| ${nombreCorto.padEnd(28)} | ${String(datos.activaciones).padStart(11)} | ${String(datos.bloqueos).padStart(8)} | ${String(datos.warnings).padStart(8)} | ${String(tasaBloqueo + '%').padStart(12)} |`;
+  }).join('\n');
+
+  return [
+    '## Guardrails — Activaciones por Sesión',
+    '',
+    '> Basado en el principio de defensa multicapa: cada hook registra activaciones/bloqueos',
+    '> para detectar patrones de falso-positivo o sub-cobertura.',
+    '',
+    '| Hook                         | Activaciones | Bloqueos | Warnings | Tasa bloqueo |',
+    '|------------------------------|-------------|----------|----------|--------------|',
+    filas,
+    '',
+  ].join('\n');
+}
+
+/**
+ * Genera un reporte de salud de guardrails.
+ * Detecta hooks con tasa de bloqueo anómalamente alta (>50%) o baja (<1%).
+ *
+ * @param {object} metricas - Resultado de getMetrics().
+ * @returns {string[]} Lista de advertencias (vacía si todo está bien).
+ */
+function diagnosticar(metricas) {
+  const hooks = metricas.hooks || {};
+  const advertencias = [];
+
+  for (const [nombre, datos] of Object.entries(hooks)) {
+    if (datos.activaciones < 5) continue; // necesita al menos 5 muestras
+
+    const tasa = datos.bloqueos / datos.activaciones;
+
+    if (tasa > 0.5) {
+      advertencias.push(
+        `${nombre}: tasa de bloqueo alta (${Math.round(tasa * 100)}%). ` +
+        `Posible falso-positivo recurrente — revisar umbrales en hooks-config.json.`
+      );
+    }
+    if (tasa === 0 && datos.activaciones >= 20) {
+      advertencias.push(
+        `${nombre}: nunca bloqueó en ${datos.activaciones} activaciones. ` +
+        `Verificar que los umbrales estén correctamente configurados.`
+      );
+    }
+  }
+
+  return advertencias;
+}
+
+module.exports = {
+  recordActivation,
+  getMetrics,
+  formatearResumen,
+  diagnosticar,
+};

package/hooks/lib/hook-circuit-breaker.js

@@ -0,0 +1,206 @@
+'use strict';
+
+/**
+ * Hook Circuit Breaker — Previene cascadas de fallos en hooks SWL.
+ *
+ * Inspirado en el patrón de Claude Code (denialTracking.ts):
+ *   - Contador de fallos consecutivos por hook
+ *   - Después de N fallos consecutivos, degrada el hook a modo warn
+ *   - Un éxito resetea el contador consecutivo
+ *   - Contador total como métrica (no bloquea, solo registra)
+ *
+ * Estado persistido en /tmp/swl-cb-{hookName}.json por sesión.
+ * Zero-dependencies — solo fs, path, os nativos.
+ *
+ * Uso:
+ *   const cb = require('./hook-circuit-breaker');
+ *   if (cb.isTripped('mi-hook')) return;  // hook degradado, skip
+ *   try { ... } catch (e) { cb.recordFailure('mi-hook'); }
+ *   cb.recordSuccess('mi-hook');
+ *
+ * @module hooks/lib/hook-circuit-breaker
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+// ---------------------------------------------------------------------------
+// Configuración por defecto
+// ---------------------------------------------------------------------------
+
+/** Fallos consecutivos antes de trip (degradar). */
+const DEFAULT_MAX_CONSECUTIVE = 3;
+
+/** Fallos totales en sesión para registrar en audit (no bloquea). */
+const DEFAULT_AUDIT_THRESHOLD = 10;
+
+/** Tiempo en ms antes de intentar recovery automático (half-open). */
+const HALF_OPEN_COOLDOWN_MS = 5 * 60 * 1000; // 5 minutos
+
+// ---------------------------------------------------------------------------
+// Helpers de estado
+// ---------------------------------------------------------------------------
+
+/**
+ * Ruta del archivo de estado del circuit breaker para un hook.
+ * @param {string} hookName - Nombre del hook (sin extensión .js).
+ * @returns {string}
+ */
+function statePath(hookName) {
+  const sessionId = process.env.SWL_SESSION_ID || 'default';
+  return path.join(os.tmpdir(), `swl-cb-${hookName}-${sessionId}.json`);
+}
+
+/**
+ * Lee el estado actual del breaker.
+ * @param {string} hookName
+ * @returns {{ consecutive: number, total: number, trippedAt: number|null, lastFailure: number }}
+ */
+function readState(hookName) {
+  const defaults = { consecutive: 0, total: 0, trippedAt: null, lastFailure: 0 };
+  try {
+    const raw = fs.readFileSync(statePath(hookName), 'utf8');
+    return { ...defaults, ...JSON.parse(raw) };
+  } catch {
+    return defaults;
+  }
+}
+
+/**
+ * Escribe el estado del breaker.
+ * @param {string} hookName
+ * @param {object} state
+ */
+function writeState(hookName, state) {
+  try {
+    fs.writeFileSync(statePath(hookName), JSON.stringify(state), 'utf8');
+  } catch {
+    // Fallo silencioso — no bloquear por no poder escribir estado
+  }
+}
+
+// ---------------------------------------------------------------------------
+// API Pública
+// ---------------------------------------------------------------------------
+
+/**
+ * Verifica si el circuit breaker de un hook está "tripped" (abierto).
+ *
+ * Si está tripped pero pasó el cooldown, entra en half-open:
+ * permite un intento para verificar si el hook se recuperó.
+ *
+ * @param {string} hookName - Nombre del hook.
+ * @param {object} [opts]
+ * @param {number} [opts.maxConsecutive=3] - Fallos consecutivos para trip.
+ * @returns {boolean} true si el hook debe saltarse (degradado).
+ */
+function isTripped(hookName, opts = {}) {
+  const maxConsecutive = opts.maxConsecutive || DEFAULT_MAX_CONSECUTIVE;
+  const state = readState(hookName);
+
+  if (state.consecutive < maxConsecutive) {
+    return false;
+  }
+
+  // Está tripped — verificar half-open (cooldown pasado)
+  if (state.trippedAt && (Date.now() - state.trippedAt) >= HALF_OPEN_COOLDOWN_MS) {
+    // Half-open: permitir un intento
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Registra un fallo del hook.
+ *
+ * @param {string} hookName
+ * @param {object} [opts]
+ * @param {number} [opts.maxConsecutive=3]
+ * @returns {{ tripped: boolean, consecutive: number, total: number }}
+ */
+function recordFailure(hookName, opts = {}) {
+  const maxConsecutive = opts.maxConsecutive || DEFAULT_MAX_CONSECUTIVE;
+  const state = readState(hookName);
+
+  state.consecutive += 1;
+  state.total += 1;
+  state.lastFailure = Date.now();
+
+  if (state.consecutive >= maxConsecutive && !state.trippedAt) {
+    state.trippedAt = Date.now();
+  }
+
+  writeState(hookName, state);
+
+  return {
+    tripped: state.consecutive >= maxConsecutive,
+    consecutive: state.consecutive,
+    total: state.total,
+  };
+}
+
+/**
+ * Registra un éxito del hook. Resetea el contador consecutivo.
+ *
+ * @param {string} hookName
+ */
+function recordSuccess(hookName) {
+  const state = readState(hookName);
+  state.consecutive = 0;
+  state.trippedAt = null;
+  writeState(hookName, state);
+}
+
+/**
+ * Obtiene las métricas del breaker sin modificar estado.
+ *
+ * @param {string} hookName
+ * @returns {{ consecutive: number, total: number, trippedAt: number|null, isTripped: boolean }}
+ */
+function getMetrics(hookName, opts = {}) {
+  const maxConsecutive = opts.maxConsecutive || DEFAULT_MAX_CONSECUTIVE;
+  const state = readState(hookName);
+  return {
+    ...state,
+    isTripped: state.consecutive >= maxConsecutive,
+  };
+}
+
+/**
+ * Resetea completamente el estado de un hook.
+ *
+ * @param {string} hookName
+ */
+function reset(hookName) {
+  try {
+    fs.unlinkSync(statePath(hookName));
+  } catch {
+    // No existe o no se puede borrar — ok
+  }
+}
+
+/**
+ * Verifica si el total de fallos supera el umbral de audit.
+ *
+ * @param {string} hookName
+ * @param {number} [threshold=10]
+ * @returns {boolean}
+ */
+function shouldAudit(hookName, threshold = DEFAULT_AUDIT_THRESHOLD) {
+  const state = readState(hookName);
+  return state.total >= threshold;
+}
+
+module.exports = {
+  isTripped,
+  recordFailure,
+  recordSuccess,
+  getMetrics,
+  reset,
+  shouldAudit,
+  DEFAULT_MAX_CONSECUTIVE,
+  DEFAULT_AUDIT_THRESHOLD,
+  HALF_OPEN_COOLDOWN_MS,
+};

package/hooks/lib/loop-detector.js

@@ -0,0 +1,267 @@
+'use strict';
+
+/**
+ * Loop Detector — Detección de agentes atascados en loops repetitivos.
+ *
+ * Usa sliding window para rastrear tool calls y outputs de texto.
+ * Cuando detecta N repeticiones consecutivas identicas, emite alerta
+ * y opcionalmente termina la ejecucion.
+ *
+ * Inspirado en open-multi-agent (LoopDetector), adaptado a zero-dependencies
+ * y al protocolo de hooks de SWL-SES.
+ *
+ * Integración:
+ *   - risk-scoring.js puede consultar getStats() para factor de riesgo
+ *   - delegation-tracker.js puede usar isLooping() como condicion de abort
+ *
+ * @module hooks/lib/loop-detector
+ */
+
+// ---------------------------------------------------------------------------
+// Constantes por defecto
+// ---------------------------------------------------------------------------
+
+/** Repeticiones consecutivas antes de detectar loop. */
+const DEFAULT_MAX_REPETITIONS = 3;
+
+/** Tamaño de la ventana de observación (turnos). */
+const DEFAULT_WINDOW_SIZE = 6;
+
+// ---------------------------------------------------------------------------
+// Estado en memoria (por sesión, por agente)
+// ---------------------------------------------------------------------------
+
+/**
+ * Map<agentName, { toolSignatures: string[], textOutputs: string[], loopsDetected: number }>
+ */
+const _agentWindows = new Map();
+
+// ---------------------------------------------------------------------------
+// Helpers internos
+// ---------------------------------------------------------------------------
+
+/**
+ * Ordena keys recursivamente para que {b:1, a:2} y {a:2, b:1}
+ * produzcan el mismo JSON string.
+ * @param {*} value
+ * @returns {*}
+ */
+function sortKeys(value) {
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(sortKeys);
+  const sorted = {};
+  for (const key of Object.keys(value).sort()) {
+    sorted[key] = sortKeys(value[key]);
+  }
+  return sorted;
+}
+
+/**
+ * Genera una firma determinista para un conjunto de tool calls.
+ * @param {Array<{name: string, input: object}>} toolCalls
+ * @returns {string}
+ */
+function computeToolSignature(toolCalls) {
+  const items = toolCalls
+    .map(tc => ({ name: tc.name, input: sortKeys(tc.input) }))
+    .sort((a, b) => {
+      const cmp = a.name.localeCompare(b.name);
+      if (cmp !== 0) return cmp;
+      return JSON.stringify(a.input).localeCompare(JSON.stringify(b.input));
+    });
+  return JSON.stringify(items);
+}
+
+/**
+ * Cuenta repeticiones consecutivas identicas al final del buffer.
+ * @param {string[]} buffer
+ * @returns {number}
+ */
+function consecutiveRepeats(buffer) {
+  if (buffer.length === 0) return 0;
+  const last = buffer[buffer.length - 1];
+  let count = 0;
+  for (let i = buffer.length - 1; i >= 0; i--) {
+    if (buffer[i] === last) count++;
+    else break;
+  }
+  return count;
+}
+
+/**
+ * Agrega entrada al buffer y recorta al tamaño de ventana.
+ * @param {string[]} buffer
+ * @param {string} entry
+ * @param {number} windowSize
+ */
+function pushAndTrim(buffer, entry, windowSize) {
+  buffer.push(entry);
+  while (buffer.length > windowSize) {
+    buffer.shift();
+  }
+}
+
+/**
+ * Obtiene o crea el estado de ventana para un agente.
+ * @param {string} agentName
+ * @returns {{ toolSignatures: string[], textOutputs: string[], loopsDetected: number, lastAction: string|null }}
+ */
+function getWindow(agentName) {
+  if (!_agentWindows.has(agentName)) {
+    _agentWindows.set(agentName, {
+      toolSignatures: [],
+      textOutputs: [],
+      loopsDetected: 0,
+      lastAction: null,
+    });
+  }
+  return _agentWindows.get(agentName);
+}
+
+// ---------------------------------------------------------------------------
+// API pública
+// ---------------------------------------------------------------------------
+
+/**
+ * Registra tool calls de un turno y verifica si hay loop.
+ *
+ * @param {string} agentName - Nombre del agente.
+ * @param {Array<{name: string, input: object}>} toolCalls - Tool calls del turno.
+ * @param {object} [options]
+ * @param {number} [options.maxRepetitions=3] - Umbral de repeticiones.
+ * @param {number} [options.windowSize=6] - Tamaño de ventana.
+ * @returns {{ detected: boolean, kind?: string, repetitions?: number, detail?: string }}
+ */
+function recordToolCalls(agentName, toolCalls, options = {}) {
+  if (!toolCalls || toolCalls.length === 0) {
+    return { detected: false };
+  }
+
+  const maxReps = options.maxRepetitions || DEFAULT_MAX_REPETITIONS;
+  const winSize = Math.max(options.windowSize || DEFAULT_WINDOW_SIZE, maxReps);
+  const win = getWindow(agentName);
+
+  const signature = computeToolSignature(toolCalls);
+  pushAndTrim(win.toolSignatures, signature, winSize);
+
+  const count = consecutiveRepeats(win.toolSignatures);
+  if (count >= maxReps) {
+    win.loopsDetected++;
+    const names = toolCalls.map(tc => tc.name).join(', ');
+    win.lastAction = 'tool_loop';
+    return {
+      detected: true,
+      kind: 'tool_repetition',
+      repetitions: count,
+      detail: `Tool call "${names}" con argumentos identicos se repitio ${count} veces consecutivas. El agente parece atascado.`,
+    };
+  }
+
+  return { detected: false };
+}
+
+/**
+ * Registra output de texto de un turno y verifica si hay loop.
+ *
+ * @param {string} agentName - Nombre del agente.
+ * @param {string} text - Texto del output.
+ * @param {object} [options]
+ * @param {number} [options.maxRepetitions=3] - Umbral de repeticiones.
+ * @param {number} [options.windowSize=6] - Tamaño de ventana.
+ * @returns {{ detected: boolean, kind?: string, repetitions?: number, detail?: string }}
+ */
+function recordTextOutput(agentName, text, options = {}) {
+  const normalized = (text || '').trim().replace(/\s+/g, ' ');
+  if (normalized.length === 0) {
+    return { detected: false };
+  }
+
+  const maxReps = options.maxRepetitions || DEFAULT_MAX_REPETITIONS;
+  const winSize = Math.max(options.windowSize || DEFAULT_WINDOW_SIZE, maxReps);
+  const win = getWindow(agentName);
+
+  pushAndTrim(win.textOutputs, normalized, winSize);
+
+  const count = consecutiveRepeats(win.textOutputs);
+  if (count >= maxReps) {
+    win.loopsDetected++;
+    win.lastAction = 'text_loop';
+    return {
+      detected: true,
+      kind: 'text_repetition',
+      repetitions: count,
+      detail: `El agente produjo la misma respuesta de texto ${count} veces consecutivas. Parece atascado en un loop.`,
+    };
+  }
+
+  return { detected: false };
+}
+
+/**
+ * Verifica si un agente esta actualmente en un loop.
+ *
+ * @param {string} agentName
+ * @returns {boolean}
+ */
+function isLooping(agentName) {
+  const win = _agentWindows.get(agentName);
+  if (!win) return false;
+  return win.lastAction === 'tool_loop' || win.lastAction === 'text_loop';
+}
+
+/**
+ * Resetea el estado de detección para un agente.
+ *
+ * @param {string} agentName
+ */
+function resetAgent(agentName) {
+  _agentWindows.delete(agentName);
+}
+
+/**
+ * Obtiene estadísticas de loops detectados.
+ *
+ * @returns {{ totalAgentsTracked: number, totalLoopsDetected: number, agentDetails: Array<{name: string, loops: number, lastAction: string|null}> }}
+ */
+function getStats() {
+  const agentDetails = [];
+  let totalLoops = 0;
+
+  for (const [name, win] of _agentWindows) {
+    agentDetails.push({
+      name,
+      loops: win.loopsDetected,
+      lastAction: win.lastAction,
+    });
+    totalLoops += win.loopsDetected;
+  }
+
+  return {
+    totalAgentsTracked: _agentWindows.size,
+    totalLoopsDetected: totalLoops,
+    agentDetails,
+  };
+}
+
+/**
+ * Resetea todo el estado del detector.
+ */
+function resetAll() {
+  _agentWindows.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  recordToolCalls,
+  recordTextOutput,
+  isLooping,
+  resetAgent,
+  resetAll,
+  getStats,
+  // Constantes para configuración externa
+  DEFAULT_MAX_REPETITIONS,
+  DEFAULT_WINDOW_SIZE,
+};