@saulwade/swl-ses 1.0.0

package/hooks/lib/convergence-detector.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Módulo: convergence-detector.js
+ * Detector de loops de agente mediante análisis de convergencia de herramientas.
+ *
+ * Un agente entra en loop cuando invoca muchas herramientas pero con poca
+ * variedad: el ratio totalCalls / uniqueTools supera el umbral 3.0.
+ *
+ * Fuente original: mission-control-main/src/lib/agent-evals.ts L.112-123 (MIT)
+ * Portado 2026-04-19 a JavaScript zero-deps para swl-ses.
+ *
+ * Invocación automática: `hooks/auto-evolucion.js` llama a `detectarLoop` en
+ * cada `SubagentStop` cuando el agente tiene ≥6 invocaciones en las trazas del
+ * día (archivo `.planning/traces/YYYY-MM-DD.jsonl`). No requiere invocación manual.
+ *
+ * Zero dependencias externas. Compatible con Node.js 18+.
+ *
+ * @module convergence-detector
+ */
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+/** Umbral de ratio totalCalls/uniqueTools que indica comportamiento en loop. */
+const UMBRAL_LOOP_DEFAULT = 3.0;
+
+// ---------------------------------------------------------------------------
+// Función principal
+// ---------------------------------------------------------------------------
+
+/**
+ * Calcula el score de convergencia de una secuencia de invocaciones de herramienta.
+ *
+ * El score varía de 0.0 a 1.0:
+ *   - 1.0 = perfecta diversidad (una herramienta distinta por cada llamada)
+ *   - → 0 = alto ratio de repetición (señal de loop)
+ *
+ * @param {Array<{ tool: string }>} invocaciones - Array de eventos con campo `tool`.
+ * @returns {{
+ *   totalCalls: number,
+ *   uniqueTools: number,
+ *   ratio: number,
+ *   score: number,
+ *   estaEnLoop: boolean
+ * }}
+ */
+function calcularScoreConvergencia(invocaciones) {
+  if (!Array.isArray(invocaciones) || invocaciones.length === 0) {
+    return { totalCalls: 0, uniqueTools: 0, ratio: 0, score: 1.0, estaEnLoop: false };
+  }
+
+  const totalCalls = invocaciones.length;
+  const herramientas = new Set(
+    invocaciones
+      .filter(inv => inv && typeof inv.tool === 'string' && inv.tool.trim())
+      .map(inv => inv.tool.trim())
+  );
+  const uniqueTools = herramientas.size;
+
+  if (uniqueTools === 0) {
+    return { totalCalls, uniqueTools: 0, ratio: 0, score: 1.0, estaEnLoop: false };
+  }
+
+  const ratio = totalCalls / uniqueTools;
+  // Score = min(1.0, UMBRAL / ratio) — a menor ratio, mayor score
+  const score = Math.round(Math.min(1.0, UMBRAL_LOOP_DEFAULT / ratio) * 100) / 100;
+  const estaEnLoop = ratio > UMBRAL_LOOP_DEFAULT;
+
+  return { totalCalls, uniqueTools, ratio, score, estaEnLoop };
+}
+
+/**
+ * Conveniencia: detecta si un agente está en loop dado un array de invocaciones
+ * y un umbral configurable.
+ *
+ * @param {object} opciones
+ * @param {Array<{ tool: string }>} opciones.invocaciones - Invocaciones del agente.
+ * @param {number} [opciones.umbral=3.0] - Ratio totalCalls/uniqueTools que activa la alerta.
+ * @returns {{
+ *   estaEnLoop: boolean,
+ *   totalCalls: number,
+ *   uniqueTools: number,
+ *   ratio: number,
+ *   score: number,
+ *   umbralUsado: number
+ * }}
+ */
+function detectarLoop({ invocaciones, umbral = UMBRAL_LOOP_DEFAULT } = {}) {
+  const resultado = calcularScoreConvergencia(invocaciones || []);
+  const estaEnLoop = resultado.totalCalls > 0 && resultado.ratio > umbral;
+  return { ...resultado, estaEnLoop, umbralUsado: umbral };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  calcularScoreConvergencia,
+  detectarLoop,
+  UMBRAL_LOOP_DEFAULT,
+};

package/hooks/lib/delegation-tracker.js

@@ -0,0 +1,198 @@
+'use strict';
+
+/**
+ * Delegation Tracker — Rastreo de profundidad y límites de delegación.
+ *
+ * Previene recursión infinita de subagentes y limita concurrencia.
+ * Patrón adoptado de Hermes Agent (delegate_tool.py):
+ *   - MAX_DEPTH = 2 (parent → child → grandchild rechazado)
+ *   - MAX_CONCURRENT = 3 (ThreadPoolExecutor)
+ *   - Blocked toolsets (sin delegación recursiva, sin memoria compartida)
+ *   - Reporte estructurado con duración y métricas
+ *
+ * Estado: en memoria por sesión (se resetea al reiniciar Claude Code).
+ * Integración: risk-scoring.js consulta profundidad, tracking-costos.js
+ * captura métricas por subagente.
+ *
+ * @module hooks/lib/delegation-tracker
+ */
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+/** Profundidad máxima de delegación. Parent=0, child=1, grandchild=rechazado. */
+const MAX_DELEGATION_DEPTH = 2;
+
+/** Máximo de subagentes ejecutándose en paralelo. */
+const MAX_CONCURRENT_CHILDREN = 3;
+
+// ---------------------------------------------------------------------------
+// Estado en memoria (por sesión)
+// ---------------------------------------------------------------------------
+
+/** Stack de delegaciones activas. */
+const _delegationStack = [];
+
+/** Contador de hijos activos. */
+let _activeChildren = 0;
+
+/** Historial de delegaciones completadas (para métricas). */
+const _completedDelegations = [];
+
+// ---------------------------------------------------------------------------
+// API pública
+// ---------------------------------------------------------------------------
+
+/**
+ * Verifica si una delegación es permitida.
+ *
+ * @param {string} agentName - Nombre del agente que solicita delegar.
+ * @returns {{ allowed: boolean, reason?: string, depth?: number }}
+ */
+function canDelegate(agentName) {
+  const currentDepth = _delegationStack.length;
+
+  if (currentDepth >= MAX_DELEGATION_DEPTH) {
+    return {
+      allowed: false,
+      reason: `Profundidad máxima de delegación alcanzada (${MAX_DELEGATION_DEPTH}). ` +
+              `Stack actual: ${_delegationStack.map(d => d.agentName).join(' → ')}. ` +
+              `No se permite delegación adicional para prevenir recursión.`,
+    };
+  }
+
+  if (_activeChildren >= MAX_CONCURRENT_CHILDREN) {
+    return {
+      allowed: false,
+      reason: `Máximo de subagentes concurrentes alcanzado (${MAX_CONCURRENT_CHILDREN}). ` +
+              `Activos: ${_delegationStack.filter(d => d.active).map(d => d.agentName).join(', ')}. ` +
+              `Esperar a que terminen antes de delegar.`,
+    };
+  }
+
+  return { allowed: true, depth: currentDepth + 1 };
+}
+
+/**
+ * Registra el inicio de una delegación.
+ *
+ * @param {string} agentName - Nombre del agente delegado.
+ * @param {string} [taskId]  - ID de la tarea (para correlación).
+ * @returns {string} ID único de la delegación (para trackDelegationComplete).
+ */
+function trackDelegationStart(agentName, taskId) {
+  const delegationId = `del-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+
+  _delegationStack.push({
+    delegationId,
+    agentName,
+    taskId: taskId || delegationId,
+    depth: _delegationStack.length,
+    startTime: Date.now(),
+    active: true,
+  });
+
+  _activeChildren++;
+  return delegationId;
+}
+
+/**
+ * Registra la finalización de una delegación.
+ *
+ * @param {string} delegationId - ID retornado por trackDelegationStart.
+ * @param {object} [result={}]  - Resultado de la delegación.
+ * @param {string} [result.status='completed'] - Estado final.
+ * @param {number} [result.tokensUsed]         - Tokens consumidos.
+ * @param {number} [result.toolCalls]          - Herramientas invocadas.
+ * @returns {object|null} Métricas de la delegación, o null si no se encontró.
+ */
+function trackDelegationComplete(delegationId, result = {}) {
+  const idx = _delegationStack.findIndex(d => d.delegationId === delegationId);
+  if (idx < 0) return null;
+
+  const entry = _delegationStack[idx];
+  entry.active = false;
+  _activeChildren = Math.max(0, _activeChildren - 1);
+
+  // Remover del stack
+  _delegationStack.splice(idx, 1);
+
+  const completed = {
+    delegationId,
+    agentName: entry.agentName,
+    taskId: entry.taskId,
+    depth: entry.depth,
+    durationMs: Date.now() - entry.startTime,
+    status: result.status || 'completed',
+    tokensUsed: result.tokensUsed || 0,
+    toolCalls: result.toolCalls || 0,
+  };
+
+  _completedDelegations.push(completed);
+
+  // Mantener solo las últimas 50 delegaciones completadas
+  if (_completedDelegations.length > 50) {
+    _completedDelegations.shift();
+  }
+
+  return completed;
+}
+
+/**
+ * Obtiene el estado actual de delegación.
+ *
+ * @returns {{
+ *   currentDepth: number,
+ *   activeChildren: number,
+ *   maxDepth: number,
+ *   maxConcurrent: number,
+ *   stack: object[],
+ *   recentCompleted: object[]
+ * }}
+ */
+function getDelegationState() {
+  return {
+    currentDepth: _delegationStack.length,
+    activeChildren: _activeChildren,
+    maxDepth: MAX_DELEGATION_DEPTH,
+    maxConcurrent: MAX_CONCURRENT_CHILDREN,
+    stack: _delegationStack.map(d => ({
+      agent: d.agentName,
+      depth: d.depth,
+      elapsedMs: Date.now() - d.startTime,
+      active: d.active,
+    })),
+    recentCompleted: _completedDelegations.slice(-10),
+  };
+}
+
+/**
+ * Calcula el factor de riesgo adicional por profundidad de delegación.
+ * Diseñado para integrarse con risk-scoring.js.
+ *
+ * @returns {number} Factor entre 0.0 y 0.30 (0.15 por nivel de profundidad).
+ */
+function getDelegationRiskFactor() {
+  return Math.min(_delegationStack.length * 0.15, 0.30);
+}
+
+/**
+ * Resetea el estado de delegación (para tests o nueva sesión).
+ */
+function reset() {
+  _delegationStack.length = 0;
+  _activeChildren = 0;
+  _completedDelegations.length = 0;
+}
+
+module.exports = {
+  canDelegate,
+  trackDelegationStart,
+  trackDelegationComplete,
+  getDelegationState,
+  getDelegationRiskFactor,
+  reset,
+  MAX_DELEGATION_DEPTH,
+  MAX_CONCURRENT_CHILDREN,
+};