@saulwade/swl-ses 1.4.1 → 1.5.0

package/hooks/lib/resource-quota.js

@@ -1,122 +1,122 @@
-'use strict';
-
-/**
- * Resource Quota — Control de consumo por ventana temporal.
- *
- * Adoptado de OpenFang (crates/openfang-kernel/src/metering.rs).
- * Implementa quotas rolling por hora, dia y mes para tokens y costo USD.
- *
- * Zero dependencias externas.
- *
- * Uso:
- *   const { quota } = require('./lib/resource-quota');
- *   quota.registrar({ tokens: 1500, costoUsd: 0.005, agente: 'implementador-swl' });
- *   const check = quota.verificar();
- *   if (check.excedido) console.log(check.mensaje);
- *
- * @module hooks/lib/resource-quota
- */
-
-const DEFAULTS = {
-  maxTokensPorHora:   200000,
-  maxCostoPorHoraUsd: 2.00,
-  maxCostoPorDiaUsd:  10.00,
-  maxCostoPorMesUsd:  100.00,
-  alertAt:            0.80,
-};
-
-const _registros = [];
-const MAX_REGISTROS = 10000;
-
-function _ahora() { return Date.now(); }
-function _haceUnaHora() { return _ahora() - 3600000; }
-function _haceUnDia() { return _ahora() - 86400000; }
-function _haceUnMes() { return _ahora() - 2592000000; }
-
-const quota = {
-  configurar(opciones) {
-    Object.assign(DEFAULTS, opciones);
-  },
-
-  registrar(datos) {
-    _registros.push({
-      tokens: datos.tokens || 0,
-      costoUsd: datos.costoUsd || 0,
-      agente: datos.agente || 'desconocido',
-      timestamp: _ahora(),
-    });
-    if (_registros.length > MAX_REGISTROS) {
-      _registros.splice(0, _registros.length - MAX_REGISTROS);
-    }
-  },
-
-  _sumarVentana(desdeMs) {
-    let tokens = 0, costo = 0;
-    for (let i = _registros.length - 1; i >= 0; i--) {
-      const r = _registros[i];
-      if (r.timestamp < desdeMs) break;
-      tokens += r.tokens;
-      costo += r.costoUsd;
-    }
-    return { tokens, costo };
-  },
-
-  verificar() {
-    const hora = this._sumarVentana(_haceUnaHora());
-    const dia  = this._sumarVentana(_haceUnDia());
-    const mes  = this._sumarVentana(_haceUnMes());
-
-    const violations = [];
-
-    if (hora.tokens >= DEFAULTS.maxTokensPorHora) {
-      violations.push({ tipo: 'tokens_hora', valor: hora.tokens, limite: DEFAULTS.maxTokensPorHora });
-    }
-    if (hora.costo >= DEFAULTS.maxCostoPorHoraUsd) {
-      violations.push({ tipo: 'costo_hora', valor: hora.costo, limite: DEFAULTS.maxCostoPorHoraUsd });
-    }
-    if (dia.costo >= DEFAULTS.maxCostoPorDiaUsd) {
-      violations.push({ tipo: 'costo_dia', valor: dia.costo, limite: DEFAULTS.maxCostoPorDiaUsd });
-    }
-    if (mes.costo >= DEFAULTS.maxCostoPorMesUsd) {
-      violations.push({ tipo: 'costo_mes', valor: mes.costo, limite: DEFAULTS.maxCostoPorMesUsd });
-    }
-
-    const warnings = [];
-    const alertThreshold = DEFAULTS.alertAt;
-
-    if (hora.costo >= DEFAULTS.maxCostoPorHoraUsd * alertThreshold && !violations.find(v => v.tipo === 'costo_hora')) {
-      warnings.push({ tipo: 'costo_hora', valor: hora.costo, limite: DEFAULTS.maxCostoPorHoraUsd, pct: Math.round(hora.costo / DEFAULTS.maxCostoPorHoraUsd * 100) });
-    }
-    if (dia.costo >= DEFAULTS.maxCostoPorDiaUsd * alertThreshold && !violations.find(v => v.tipo === 'costo_dia')) {
-      warnings.push({ tipo: 'costo_dia', valor: dia.costo, limite: DEFAULTS.maxCostoPorDiaUsd, pct: Math.round(dia.costo / DEFAULTS.maxCostoPorDiaUsd * 100) });
-    }
-
-    return {
-      excedido: violations.length > 0,
-      violations,
-      warnings,
-      consumo: { hora, dia, mes },
-      mensaje: violations.length > 0
-        ? 'Quota excedida: ' + violations.map(v => v.tipo + ' (' + v.valor.toFixed(2) + '/' + v.limite + ')').join(', ')
-        : warnings.length > 0
-          ? 'Alerta: ' + warnings.map(w => w.tipo + ' al ' + w.pct + '%').join(', ')
-          : 'Dentro de quota',
-    };
-  },
-
-  resumen() {
-    const hora = this._sumarVentana(_haceUnaHora());
-    const dia  = this._sumarVentana(_haceUnDia());
-    const mes  = this._sumarVentana(_haceUnMes());
-    return {
-      hora: { tokens: hora.tokens, costoUsd: Math.round(hora.costo * 10000) / 10000 },
-      dia:  { tokens: dia.tokens,  costoUsd: Math.round(dia.costo * 10000) / 10000 },
-      mes:  { tokens: mes.tokens,  costoUsd: Math.round(mes.costo * 10000) / 10000 },
-      registros: _registros.length,
-    };
-  },
-
-  reset() { _registros.length = 0; },
-};
-
-module.exports = { quota, DEFAULTS };
+'use strict';
+
+/**
+ * Resource Quota — Control de consumo por ventana temporal.
+ *
+ * Adoptado de OpenFang (crates/openfang-kernel/src/metering.rs).
+ * Implementa quotas rolling por hora, dia y mes para tokens y costo USD.
+ *
+ * Zero dependencias externas.
+ *
+ * Uso:
+ *   const { quota } = require('./lib/resource-quota');
+ *   quota.registrar({ tokens: 1500, costoUsd: 0.005, agente: 'implementador-swl' });
+ *   const check = quota.verificar();
+ *   if (check.excedido) console.log(check.mensaje);
+ *
+ * @module hooks/lib/resource-quota
+ */
+
+const DEFAULTS = {
+  maxTokensPorHora:   200000,
+  maxCostoPorHoraUsd: 2.00,
+  maxCostoPorDiaUsd:  10.00,
+  maxCostoPorMesUsd:  100.00,
+  alertAt:            0.80,
+};
+
+const _registros = [];
+const MAX_REGISTROS = 10000;
+
+function _ahora() { return Date.now(); }
+function _haceUnaHora() { return _ahora() - 3600000; }
+function _haceUnDia() { return _ahora() - 86400000; }
+function _haceUnMes() { return _ahora() - 2592000000; }
+
+const quota = {
+  configurar(opciones) {
+    Object.assign(DEFAULTS, opciones);
+  },
+
+  registrar(datos) {
+    _registros.push({
+      tokens: datos.tokens || 0,
+      costoUsd: datos.costoUsd || 0,
+      agente: datos.agente || 'desconocido',
+      timestamp: _ahora(),
+    });
+    if (_registros.length > MAX_REGISTROS) {
+      _registros.splice(0, _registros.length - MAX_REGISTROS);
+    }
+  },
+
+  _sumarVentana(desdeMs) {
+    let tokens = 0, costo = 0;
+    for (let i = _registros.length - 1; i >= 0; i--) {
+      const r = _registros[i];
+      if (r.timestamp < desdeMs) break;
+      tokens += r.tokens;
+      costo += r.costoUsd;
+    }
+    return { tokens, costo };
+  },
+
+  verificar() {
+    const hora = this._sumarVentana(_haceUnaHora());
+    const dia  = this._sumarVentana(_haceUnDia());
+    const mes  = this._sumarVentana(_haceUnMes());
+
+    const violations = [];
+
+    if (hora.tokens >= DEFAULTS.maxTokensPorHora) {
+      violations.push({ tipo: 'tokens_hora', valor: hora.tokens, limite: DEFAULTS.maxTokensPorHora });
+    }
+    if (hora.costo >= DEFAULTS.maxCostoPorHoraUsd) {
+      violations.push({ tipo: 'costo_hora', valor: hora.costo, limite: DEFAULTS.maxCostoPorHoraUsd });
+    }
+    if (dia.costo >= DEFAULTS.maxCostoPorDiaUsd) {
+      violations.push({ tipo: 'costo_dia', valor: dia.costo, limite: DEFAULTS.maxCostoPorDiaUsd });
+    }
+    if (mes.costo >= DEFAULTS.maxCostoPorMesUsd) {
+      violations.push({ tipo: 'costo_mes', valor: mes.costo, limite: DEFAULTS.maxCostoPorMesUsd });
+    }
+
+    const warnings = [];
+    const alertThreshold = DEFAULTS.alertAt;
+
+    if (hora.costo >= DEFAULTS.maxCostoPorHoraUsd * alertThreshold && !violations.find(v => v.tipo === 'costo_hora')) {
+      warnings.push({ tipo: 'costo_hora', valor: hora.costo, limite: DEFAULTS.maxCostoPorHoraUsd, pct: Math.round(hora.costo / DEFAULTS.maxCostoPorHoraUsd * 100) });
+    }
+    if (dia.costo >= DEFAULTS.maxCostoPorDiaUsd * alertThreshold && !violations.find(v => v.tipo === 'costo_dia')) {
+      warnings.push({ tipo: 'costo_dia', valor: dia.costo, limite: DEFAULTS.maxCostoPorDiaUsd, pct: Math.round(dia.costo / DEFAULTS.maxCostoPorDiaUsd * 100) });
+    }
+
+    return {
+      excedido: violations.length > 0,
+      violations,
+      warnings,
+      consumo: { hora, dia, mes },
+      mensaje: violations.length > 0
+        ? 'Quota excedida: ' + violations.map(v => v.tipo + ' (' + v.valor.toFixed(2) + '/' + v.limite + ')').join(', ')
+        : warnings.length > 0
+          ? 'Alerta: ' + warnings.map(w => w.tipo + ' al ' + w.pct + '%').join(', ')
+          : 'Dentro de quota',
+    };
+  },
+
+  resumen() {
+    const hora = this._sumarVentana(_haceUnaHora());
+    const dia  = this._sumarVentana(_haceUnDia());
+    const mes  = this._sumarVentana(_haceUnMes());
+    return {
+      hora: { tokens: hora.tokens, costoUsd: Math.round(hora.costo * 10000) / 10000 },
+      dia:  { tokens: dia.tokens,  costoUsd: Math.round(dia.costo * 10000) / 10000 },
+      mes:  { tokens: mes.tokens,  costoUsd: Math.round(mes.costo * 10000) / 10000 },
+      registros: _registros.length,
+    };
+  },
+
+  reset() { _registros.length = 0; },
+};
+
+module.exports = { quota, DEFAULTS };

package/hooks/lib/retry-jitter.js

@@ -1,165 +1,165 @@
-'use strict';
-
-/**
- * Retry con Jitter Decorrelado — Backoff exponencial con decorrelación.
- *
- * Patrón adoptado de Hermes Agent (agent/retry_utils.py).
- * Usa seed basado en time + counter con golden ratio para decorrelación
- * entre sesiones concurrentes — evita thundering herd.
- *
- * Zero dependencias externas — usa crypto nativo de Node.js.
- *
- * Uso:
- *   const { jitteredBackoff, crearRetrier } = require('./lib/retry-jitter');
- *
- *   // Calcular delay para un intento específico
- *   const delay = jitteredBackoff(2, { baseDelay: 5, maxDelay: 120 });
- *
- *   // Usar retrier completo
- *   const retrier = crearRetrier({ maxIntentos: 3, baseDelay: 5 });
- *   const resultado = await retrier.ejecutar(async () => {
- *     return await llamadaAPI();
- *   });
- *
- * @module hooks/lib/retry-jitter
- */
-
-const crypto = require('crypto');
-
-// ---------------------------------------------------------------------------
-// Constantes
-// ---------------------------------------------------------------------------
-
-/** Golden ratio × 2^32 — constante de dispersión de Fibonacci hashing. */
-const GOLDEN_RATIO_32 = 0x9E3779B9;
-
-/** Contador global para decorrelación entre llamadas concurrentes. */
-let _jitterCounter = 0;
-
-// ---------------------------------------------------------------------------
-// Funciones core
-// ---------------------------------------------------------------------------
-
-/**
- * Calcula delay con backoff exponencial + jitter decorrelado.
- *
- * Delay = min(base × 2^(intento-1), maxDelay) + jitter
- * Jitter = random(0, jitterRatio × delay)
- *
- * El seed para el random combina timestamp con un contador global
- * multiplicado por la constante golden ratio, lo que garantiza
- * que llamadas concurrentes desde diferentes hilos/procesos
- * NO coincidan en el mismo delay.
- *
- * @param {number} intento      - Número de intento (1-indexed)
- * @param {object} [opciones]
- * @param {number} [opciones.baseDelay=5]     - Delay base en segundos
- * @param {number} [opciones.maxDelay=120]    - Delay máximo en segundos
- * @param {number} [opciones.jitterRatio=0.5] - Proporción de jitter (0-1)
- * @returns {number} Delay en segundos (con decimales)
- */
-function jitteredBackoff(intento, opciones = {}) {
-  const {
-    baseDelay = 5,
-    maxDelay = 120,
-    jitterRatio = 0.5,
-  } = opciones;
-
-  _jitterCounter += 1;
-  const tick = _jitterCounter;
-
-  // Backoff exponencial acotado
-  const exponente = Math.max(0, intento - 1);
-  const delay = Math.min(baseDelay * Math.pow(2, exponente), maxDelay);
-
-  // Seed decorrelado: timestamp XOR (counter × golden_ratio)
-  const nowNs = BigInt(Date.now()) * 1_000_000n; // ms → pseudo-ns
-  const seed = Number((nowNs ^ BigInt(tick * GOLDEN_RATIO_32)) & 0xFFFFFFFFn);
-
-  // PRNG determinista basado en seed (sin crypto para velocidad)
-  const hash = crypto.createHash('md5').update(String(seed)).digest();
-  const pseudoRandom = hash.readUInt32LE(0) / 0xFFFFFFFF;
-
-  const jitter = pseudoRandom * jitterRatio * delay;
-
-  return delay + jitter;
-}
-
-/**
- * Espera un número de segundos (para uso con async/await).
- *
- * @param {number} segundos
- * @returns {Promise<void>}
- */
-function esperar(segundos) {
-  return new Promise(resolve => setTimeout(resolve, Math.round(segundos * 1000)));
-}
-
-/**
- * Crea un retrier configurable con jitter decorrelado.
- *
- * @param {object} [opciones]
- * @param {number} [opciones.maxIntentos=3]    - Máximo de intentos
- * @param {number} [opciones.baseDelay=5]      - Delay base en segundos
- * @param {number} [opciones.maxDelay=120]     - Delay máximo en segundos
- * @param {number} [opciones.jitterRatio=0.5]  - Proporción de jitter
- * @param {Function} [opciones.esRetryable]    - Función que determina si un error es retryable
- * @param {Function} [opciones.onReintento]    - Callback antes de cada reintento
- * @returns {object} Retrier con método ejecutar()
- */
-function crearRetrier(opciones = {}) {
-  const {
-    maxIntentos = 3,
-    baseDelay = 5,
-    maxDelay = 120,
-    jitterRatio = 0.5,
-    esRetryable = () => true,
-    onReintento = null,
-  } = opciones;
-
-  return {
-    /**
-     * Ejecuta una función con reintentos automáticos.
-     *
-     * @template T
-     * @param {() => Promise<T>} fn - Función async a ejecutar
-     * @returns {Promise<T>} Resultado de la función
-     * @throws {Error} Error del último intento si todos fallan
-     */
-    async ejecutar(fn) {
-      let ultimoError;
-
-      for (let intento = 1; intento <= maxIntentos; intento++) {
-        try {
-          return await fn();
-        } catch (error) {
-          ultimoError = error;
-
-          if (intento >= maxIntentos || !esRetryable(error)) {
-            throw error;
-          }
-
-          const delay = jitteredBackoff(intento, { baseDelay, maxDelay, jitterRatio });
-
-          if (onReintento) {
-            onReintento({ intento, maxIntentos, delay, error });
-          }
-
-          await esperar(delay);
-        }
-      }
-
-      throw ultimoError;
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Exports
-// ---------------------------------------------------------------------------
-
-module.exports = {
-  jitteredBackoff,
-  esperar,
-  crearRetrier,
-};
+'use strict';
+
+/**
+ * Retry con Jitter Decorrelado — Backoff exponencial con decorrelación.
+ *
+ * Patrón adoptado de Hermes Agent (agent/retry_utils.py).
+ * Usa seed basado en time + counter con golden ratio para decorrelación
+ * entre sesiones concurrentes — evita thundering herd.
+ *
+ * Zero dependencias externas — usa crypto nativo de Node.js.
+ *
+ * Uso:
+ *   const { jitteredBackoff, crearRetrier } = require('./lib/retry-jitter');
+ *
+ *   // Calcular delay para un intento específico
+ *   const delay = jitteredBackoff(2, { baseDelay: 5, maxDelay: 120 });
+ *
+ *   // Usar retrier completo
+ *   const retrier = crearRetrier({ maxIntentos: 3, baseDelay: 5 });
+ *   const resultado = await retrier.ejecutar(async () => {
+ *     return await llamadaAPI();
+ *   });
+ *
+ * @module hooks/lib/retry-jitter
+ */
+
+const crypto = require('crypto');
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+/** Golden ratio × 2^32 — constante de dispersión de Fibonacci hashing. */
+const GOLDEN_RATIO_32 = 0x9E3779B9;
+
+/** Contador global para decorrelación entre llamadas concurrentes. */
+let _jitterCounter = 0;
+
+// ---------------------------------------------------------------------------
+// Funciones core
+// ---------------------------------------------------------------------------
+
+/**
+ * Calcula delay con backoff exponencial + jitter decorrelado.
+ *
+ * Delay = min(base × 2^(intento-1), maxDelay) + jitter
+ * Jitter = random(0, jitterRatio × delay)
+ *
+ * El seed para el random combina timestamp con un contador global
+ * multiplicado por la constante golden ratio, lo que garantiza
+ * que llamadas concurrentes desde diferentes hilos/procesos
+ * NO coincidan en el mismo delay.
+ *
+ * @param {number} intento      - Número de intento (1-indexed)
+ * @param {object} [opciones]
+ * @param {number} [opciones.baseDelay=5]     - Delay base en segundos
+ * @param {number} [opciones.maxDelay=120]    - Delay máximo en segundos
+ * @param {number} [opciones.jitterRatio=0.5] - Proporción de jitter (0-1)
+ * @returns {number} Delay en segundos (con decimales)
+ */
+function jitteredBackoff(intento, opciones = {}) {
+  const {
+    baseDelay = 5,
+    maxDelay = 120,
+    jitterRatio = 0.5,
+  } = opciones;
+
+  _jitterCounter += 1;
+  const tick = _jitterCounter;
+
+  // Backoff exponencial acotado
+  const exponente = Math.max(0, intento - 1);
+  const delay = Math.min(baseDelay * Math.pow(2, exponente), maxDelay);
+
+  // Seed decorrelado: timestamp XOR (counter × golden_ratio)
+  const nowNs = BigInt(Date.now()) * 1_000_000n; // ms → pseudo-ns
+  const seed = Number((nowNs ^ BigInt(tick * GOLDEN_RATIO_32)) & 0xFFFFFFFFn);
+
+  // PRNG determinista basado en seed (sin crypto para velocidad)
+  const hash = crypto.createHash('md5').update(String(seed)).digest();
+  const pseudoRandom = hash.readUInt32LE(0) / 0xFFFFFFFF;
+
+  const jitter = pseudoRandom * jitterRatio * delay;
+
+  return delay + jitter;
+}
+
+/**
+ * Espera un número de segundos (para uso con async/await).
+ *
+ * @param {number} segundos
+ * @returns {Promise<void>}
+ */
+function esperar(segundos) {
+  return new Promise(resolve => setTimeout(resolve, Math.round(segundos * 1000)));
+}
+
+/**
+ * Crea un retrier configurable con jitter decorrelado.
+ *
+ * @param {object} [opciones]
+ * @param {number} [opciones.maxIntentos=3]    - Máximo de intentos
+ * @param {number} [opciones.baseDelay=5]      - Delay base en segundos
+ * @param {number} [opciones.maxDelay=120]     - Delay máximo en segundos
+ * @param {number} [opciones.jitterRatio=0.5]  - Proporción de jitter
+ * @param {Function} [opciones.esRetryable]    - Función que determina si un error es retryable
+ * @param {Function} [opciones.onReintento]    - Callback antes de cada reintento
+ * @returns {object} Retrier con método ejecutar()
+ */
+function crearRetrier(opciones = {}) {
+  const {
+    maxIntentos = 3,
+    baseDelay = 5,
+    maxDelay = 120,
+    jitterRatio = 0.5,
+    esRetryable = () => true,
+    onReintento = null,
+  } = opciones;
+
+  return {
+    /**
+     * Ejecuta una función con reintentos automáticos.
+     *
+     * @template T
+     * @param {() => Promise<T>} fn - Función async a ejecutar
+     * @returns {Promise<T>} Resultado de la función
+     * @throws {Error} Error del último intento si todos fallan
+     */
+    async ejecutar(fn) {
+      let ultimoError;
+
+      for (let intento = 1; intento <= maxIntentos; intento++) {
+        try {
+          return await fn();
+        } catch (error) {
+          ultimoError = error;
+
+          if (intento >= maxIntentos || !esRetryable(error)) {
+            throw error;
+          }
+
+          const delay = jitteredBackoff(intento, { baseDelay, maxDelay, jitterRatio });
+
+          if (onReintento) {
+            onReintento({ intento, maxIntentos, delay, error });
+          }
+
+          await esperar(delay);
+        }
+      }
+
+      throw ultimoError;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  jitteredBackoff,
+  esperar,
+  crearRetrier,
+};