@saulwade/swl-ses 1.4.1 → 1.5.0

package/scripts/lib/budget-enforcer.js

@@ -1,252 +1,252 @@
-'use strict';
-
-/**
- * budget-enforcer.js
- *
- * Control de presupuesto con thresholds escalonados, backpressure y
- * idempotency keys. Patrón adaptado del BudgetManager de Shannon
- * (`temp/Shannon-main/go/orchestrator/internal/budget/manager.go`),
- * portado a Node.js zero-deps.
- *
- * Diferencias con `hooks/tracking-costos.js`:
- *   - tracking-costos: registra consumo y emite warnings simples (80%, 100%).
- *   - budget-enforcer: 4 niveles (warning/approval/hard/backpressure),
- *     idempotency keys para reintentos, decisiones puras (no I/O).
- *
- * El módulo es PURO. No escribe a disco. El consumidor decide qué hacer
- * con el resultado (alertar, pausar, bloquear, retrasar).
- *
- * Modelo de niveles:
- *   - PASS         : por debajo de warning. Continúa sin restricción.
- *   - WARNING      : ≥ warning_pct. Emite alerta, continúa.
- *   - APPROVAL     : ≥ approval_pct. Requiere confirmación humana antes de seguir.
- *   - BACKPRESSURE : ≥ backpressure_pct. Continúa pero con delay configurable.
- *   - HARD_LIMIT   : ≥ hard_pct. Detiene la operación; sin override.
- *
- * Defaults razonables (modificables vía opts):
- *   warning_pct = 0.70  (70%)
- *   approval_pct = 0.85 (85%)
- *   backpressure_pct = 0.90 (90%)
- *   hard_pct = 1.00 (100%)
- *   backpressure_delay_ms = 2000
- *
- * Idempotency:
- *   recordUsage acepta una idempotency_key. Si ya se contabilizó esa key,
- *   devuelve el estado SIN re-incrementar. Permite reintentos seguros.
- *
- * @module scripts/lib/budget-enforcer
- */
-
-// ── constantes ────────────────────────────────────────────────────────────────
-
-const DEFAULTS = Object.freeze({
-  warning_pct:           0.70,
-  approval_pct:          0.85,
-  backpressure_pct:      0.90,
-  hard_pct:              1.00,
-  backpressure_delay_ms: 2000,
-});
-
-const LEVEL = Object.freeze({
-  PASS:         'pass',
-  WARNING:      'warning',
-  APPROVAL:     'approval',
-  BACKPRESSURE: 'backpressure',
-  HARD_LIMIT:   'hard_limit',
-});
-
-// ── helpers ───────────────────────────────────────────────────────────────────
-
-function clamp(n, min, max) {
-  if (Number.isNaN(n)) return min;
-  return Math.max(min, Math.min(max, n));
-}
-
-function mergeOpts(opts) {
-  return { ...DEFAULTS, ...(opts || {}) };
-}
-
-// ── API pública ───────────────────────────────────────────────────────────────
-
-/**
- * Crea un nuevo estado de presupuesto.
- *
- * @param {object} params
- * @param {number} params.maxUsd     - Presupuesto máximo en USD
- * @param {number} params.maxTokens  - Presupuesto máximo en tokens
- * @returns {object} estado inicial
- */
-function createBudget({ maxUsd = 10.0, maxTokens = 500_000 } = {}) {
-  return {
-    maxUsd,
-    maxTokens,
-    usedUsd: 0,
-    usedTokens: 0,
-    requestCount: 0,
-    idempotency: {},  // key → { usd, tokens, recordedAt }
-    createdAt: new Date().toISOString(),
-  };
-}
-
-/**
- * Registra consumo de presupuesto. Pure: devuelve nuevo estado.
- *
- * @param {object} budget         - estado actual
- * @param {object} usage          - consumo a registrar
- * @param {number} usage.usd
- * @param {number} usage.tokens
- * @param {string} [usage.idempotencyKey] - si presente, evita doble-conteo
- * @returns {{ budget: object, deduplicated: boolean }}
- */
-function recordUsage(budget, usage) {
-  const next = { ...budget, idempotency: { ...budget.idempotency } };
-  const usd = Number(usage.usd) || 0;
-  const tokens = Number(usage.tokens) || 0;
-  const key = usage.idempotencyKey;
-
-  if (key && next.idempotency[key]) {
-    // Ya contabilizado, retornar sin cambios
-    return { budget: next, deduplicated: true };
-  }
-
-  next.usedUsd = next.usedUsd + usd;
-  next.usedTokens = next.usedTokens + tokens;
-  next.requestCount = next.requestCount + 1;
-
-  if (key) {
-    next.idempotency[key] = {
-      usd,
-      tokens,
-      recordedAt: new Date().toISOString(),
-    };
-  }
-
-  return { budget: next, deduplicated: false };
-}
-
-/**
- * Calcula la fracción del presupuesto consumida.
- * Devuelve max(usd_pct, tokens_pct) — el más cercano al límite manda.
- *
- * @param {object} budget
- * @returns {number} en [0, ∞) — sí puede pasar 1.0 si hay overshoot
- */
-function consumptionRatio(budget) {
-  const usdPct = budget.maxUsd > 0 ? budget.usedUsd / budget.maxUsd : 0;
-  const tokensPct = budget.maxTokens > 0 ? budget.usedTokens / budget.maxTokens : 0;
-  return Math.max(usdPct, tokensPct);
-}
-
-/**
- * Determina el nivel de threshold actual.
- *
- * @param {object} budget
- * @param {object} [opts] - thresholds custom
- * @returns {string} LEVEL.*
- */
-function currentLevel(budget, opts) {
-  const cfg = mergeOpts(opts);
-  const ratio = consumptionRatio(budget);
-
-  if (ratio >= cfg.hard_pct)         return LEVEL.HARD_LIMIT;
-  if (ratio >= cfg.backpressure_pct) return LEVEL.BACKPRESSURE;
-  if (ratio >= cfg.approval_pct)     return LEVEL.APPROVAL;
-  if (ratio >= cfg.warning_pct)      return LEVEL.WARNING;
-  return LEVEL.PASS;
-}
-
-/**
- * Decisión combinada: nivel + acción recomendada + delay si aplica.
- *
- * @param {object} budget
- * @param {object} [opts]
- * @returns {object} {
- *   level, ratio, allow, requiresApproval, delayMs, reason
- * }
- */
-function decide(budget, opts) {
-  const cfg = mergeOpts(opts);
-  const ratio = consumptionRatio(budget);
-  const level = currentLevel(budget, cfg);
-
-  const decision = {
-    level,
-    ratio: Math.round(ratio * 1000) / 1000,
-    allow: true,
-    requiresApproval: false,
-    delayMs: 0,
-    reason: null,
-  };
-
-  switch (level) {
-    case LEVEL.HARD_LIMIT:
-      decision.allow = false;
-      decision.reason = `Presupuesto agotado (${(ratio * 100).toFixed(1)}% del máximo). Hard limit alcanzado.`;
-      break;
-    case LEVEL.BACKPRESSURE:
-      decision.delayMs = cfg.backpressure_delay_ms;
-      decision.reason = `Cerca del límite (${(ratio * 100).toFixed(1)}%). Aplicando backpressure de ${cfg.backpressure_delay_ms}ms.`;
-      break;
-    case LEVEL.APPROVAL:
-      decision.requiresApproval = true;
-      decision.reason = `Presupuesto al ${(ratio * 100).toFixed(1)}%. Requiere confirmación humana antes de continuar.`;
-      break;
-    case LEVEL.WARNING:
-      decision.reason = `Aviso: presupuesto al ${(ratio * 100).toFixed(1)}% del máximo.`;
-      break;
-    case LEVEL.PASS:
-    default:
-      break;
-  }
-
-  return decision;
-}
-
-/**
- * Estima si una operación futura cabe en el presupuesto.
- * Útil para decidir antes de invocar un agente costoso.
- *
- * @param {object} budget
- * @param {object} estimate
- * @param {number} estimate.usd
- * @param {number} estimate.tokens
- * @param {object} [opts]
- * @returns {object} mismo formato que decide() — proyecta el estado post-operación
- */
-function projectDecision(budget, estimate, opts) {
-  const projected = {
-    ...budget,
-    usedUsd: budget.usedUsd + (Number(estimate.usd) || 0),
-    usedTokens: budget.usedTokens + (Number(estimate.tokens) || 0),
-  };
-  return decide(projected, opts);
-}
-
-/**
- * Resetea el contador de uso manteniendo límites e idempotency cache.
- * Útil para nuevos ciclos de facturación.
- */
-function resetUsage(budget) {
-  return {
-    ...budget,
-    usedUsd: 0,
-    usedTokens: 0,
-    requestCount: 0,
-    idempotency: {},
-    resetAt: new Date().toISOString(),
-  };
-}
-
-// ── exports ───────────────────────────────────────────────────────────────────
-
-module.exports = {
-  createBudget,
-  recordUsage,
-  consumptionRatio,
-  currentLevel,
-  decide,
-  projectDecision,
-  resetUsage,
-  LEVEL,
-  DEFAULTS,
-};
+'use strict';
+
+/**
+ * budget-enforcer.js
+ *
+ * Control de presupuesto con thresholds escalonados, backpressure y
+ * idempotency keys. Patrón adaptado del BudgetManager de Shannon
+ * (`temp/Shannon-main/go/orchestrator/internal/budget/manager.go`),
+ * portado a Node.js zero-deps.
+ *
+ * Diferencias con `hooks/tracking-costos.js`:
+ *   - tracking-costos: registra consumo y emite warnings simples (80%, 100%).
+ *   - budget-enforcer: 4 niveles (warning/approval/hard/backpressure),
+ *     idempotency keys para reintentos, decisiones puras (no I/O).
+ *
+ * El módulo es PURO. No escribe a disco. El consumidor decide qué hacer
+ * con el resultado (alertar, pausar, bloquear, retrasar).
+ *
+ * Modelo de niveles:
+ *   - PASS         : por debajo de warning. Continúa sin restricción.
+ *   - WARNING      : ≥ warning_pct. Emite alerta, continúa.
+ *   - APPROVAL     : ≥ approval_pct. Requiere confirmación humana antes de seguir.
+ *   - BACKPRESSURE : ≥ backpressure_pct. Continúa pero con delay configurable.
+ *   - HARD_LIMIT   : ≥ hard_pct. Detiene la operación; sin override.
+ *
+ * Defaults razonables (modificables vía opts):
+ *   warning_pct = 0.70  (70%)
+ *   approval_pct = 0.85 (85%)
+ *   backpressure_pct = 0.90 (90%)
+ *   hard_pct = 1.00 (100%)
+ *   backpressure_delay_ms = 2000
+ *
+ * Idempotency:
+ *   recordUsage acepta una idempotency_key. Si ya se contabilizó esa key,
+ *   devuelve el estado SIN re-incrementar. Permite reintentos seguros.
+ *
+ * @module scripts/lib/budget-enforcer
+ */
+
+// ── constantes ────────────────────────────────────────────────────────────────
+
+const DEFAULTS = Object.freeze({
+  warning_pct:           0.70,
+  approval_pct:          0.85,
+  backpressure_pct:      0.90,
+  hard_pct:              1.00,
+  backpressure_delay_ms: 2000,
+});
+
+const LEVEL = Object.freeze({
+  PASS:         'pass',
+  WARNING:      'warning',
+  APPROVAL:     'approval',
+  BACKPRESSURE: 'backpressure',
+  HARD_LIMIT:   'hard_limit',
+});
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function clamp(n, min, max) {
+  if (Number.isNaN(n)) return min;
+  return Math.max(min, Math.min(max, n));
+}
+
+function mergeOpts(opts) {
+  return { ...DEFAULTS, ...(opts || {}) };
+}
+
+// ── API pública ───────────────────────────────────────────────────────────────
+
+/**
+ * Crea un nuevo estado de presupuesto.
+ *
+ * @param {object} params
+ * @param {number} params.maxUsd     - Presupuesto máximo en USD
+ * @param {number} params.maxTokens  - Presupuesto máximo en tokens
+ * @returns {object} estado inicial
+ */
+function createBudget({ maxUsd = 10.0, maxTokens = 500_000 } = {}) {
+  return {
+    maxUsd,
+    maxTokens,
+    usedUsd: 0,
+    usedTokens: 0,
+    requestCount: 0,
+    idempotency: {},  // key → { usd, tokens, recordedAt }
+    createdAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Registra consumo de presupuesto. Pure: devuelve nuevo estado.
+ *
+ * @param {object} budget         - estado actual
+ * @param {object} usage          - consumo a registrar
+ * @param {number} usage.usd
+ * @param {number} usage.tokens
+ * @param {string} [usage.idempotencyKey] - si presente, evita doble-conteo
+ * @returns {{ budget: object, deduplicated: boolean }}
+ */
+function recordUsage(budget, usage) {
+  const next = { ...budget, idempotency: { ...budget.idempotency } };
+  const usd = Number(usage.usd) || 0;
+  const tokens = Number(usage.tokens) || 0;
+  const key = usage.idempotencyKey;
+
+  if (key && next.idempotency[key]) {
+    // Ya contabilizado, retornar sin cambios
+    return { budget: next, deduplicated: true };
+  }
+
+  next.usedUsd = next.usedUsd + usd;
+  next.usedTokens = next.usedTokens + tokens;
+  next.requestCount = next.requestCount + 1;
+
+  if (key) {
+    next.idempotency[key] = {
+      usd,
+      tokens,
+      recordedAt: new Date().toISOString(),
+    };
+  }
+
+  return { budget: next, deduplicated: false };
+}
+
+/**
+ * Calcula la fracción del presupuesto consumida.
+ * Devuelve max(usd_pct, tokens_pct) — el más cercano al límite manda.
+ *
+ * @param {object} budget
+ * @returns {number} en [0, ∞) — sí puede pasar 1.0 si hay overshoot
+ */
+function consumptionRatio(budget) {
+  const usdPct = budget.maxUsd > 0 ? budget.usedUsd / budget.maxUsd : 0;
+  const tokensPct = budget.maxTokens > 0 ? budget.usedTokens / budget.maxTokens : 0;
+  return Math.max(usdPct, tokensPct);
+}
+
+/**
+ * Determina el nivel de threshold actual.
+ *
+ * @param {object} budget
+ * @param {object} [opts] - thresholds custom
+ * @returns {string} LEVEL.*
+ */
+function currentLevel(budget, opts) {
+  const cfg = mergeOpts(opts);
+  const ratio = consumptionRatio(budget);
+
+  if (ratio >= cfg.hard_pct)         return LEVEL.HARD_LIMIT;
+  if (ratio >= cfg.backpressure_pct) return LEVEL.BACKPRESSURE;
+  if (ratio >= cfg.approval_pct)     return LEVEL.APPROVAL;
+  if (ratio >= cfg.warning_pct)      return LEVEL.WARNING;
+  return LEVEL.PASS;
+}
+
+/**
+ * Decisión combinada: nivel + acción recomendada + delay si aplica.
+ *
+ * @param {object} budget
+ * @param {object} [opts]
+ * @returns {object} {
+ *   level, ratio, allow, requiresApproval, delayMs, reason
+ * }
+ */
+function decide(budget, opts) {
+  const cfg = mergeOpts(opts);
+  const ratio = consumptionRatio(budget);
+  const level = currentLevel(budget, cfg);
+
+  const decision = {
+    level,
+    ratio: Math.round(ratio * 1000) / 1000,
+    allow: true,
+    requiresApproval: false,
+    delayMs: 0,
+    reason: null,
+  };
+
+  switch (level) {
+    case LEVEL.HARD_LIMIT:
+      decision.allow = false;
+      decision.reason = `Presupuesto agotado (${(ratio * 100).toFixed(1)}% del máximo). Hard limit alcanzado.`;
+      break;
+    case LEVEL.BACKPRESSURE:
+      decision.delayMs = cfg.backpressure_delay_ms;
+      decision.reason = `Cerca del límite (${(ratio * 100).toFixed(1)}%). Aplicando backpressure de ${cfg.backpressure_delay_ms}ms.`;
+      break;
+    case LEVEL.APPROVAL:
+      decision.requiresApproval = true;
+      decision.reason = `Presupuesto al ${(ratio * 100).toFixed(1)}%. Requiere confirmación humana antes de continuar.`;
+      break;
+    case LEVEL.WARNING:
+      decision.reason = `Aviso: presupuesto al ${(ratio * 100).toFixed(1)}% del máximo.`;
+      break;
+    case LEVEL.PASS:
+    default:
+      break;
+  }
+
+  return decision;
+}
+
+/**
+ * Estima si una operación futura cabe en el presupuesto.
+ * Útil para decidir antes de invocar un agente costoso.
+ *
+ * @param {object} budget
+ * @param {object} estimate
+ * @param {number} estimate.usd
+ * @param {number} estimate.tokens
+ * @param {object} [opts]
+ * @returns {object} mismo formato que decide() — proyecta el estado post-operación
+ */
+function projectDecision(budget, estimate, opts) {
+  const projected = {
+    ...budget,
+    usedUsd: budget.usedUsd + (Number(estimate.usd) || 0),
+    usedTokens: budget.usedTokens + (Number(estimate.tokens) || 0),
+  };
+  return decide(projected, opts);
+}
+
+/**
+ * Resetea el contador de uso manteniendo límites e idempotency cache.
+ * Útil para nuevos ciclos de facturación.
+ */
+function resetUsage(budget) {
+  return {
+    ...budget,
+    usedUsd: 0,
+    usedTokens: 0,
+    requestCount: 0,
+    idempotency: {},
+    resetAt: new Date().toISOString(),
+  };
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  createBudget,
+  recordUsage,
+  consumptionRatio,
+  currentLevel,
+  decide,
+  projectDecision,
+  resetUsage,
+  LEVEL,
+  DEFAULTS,
+};