@saulwade/swl-ses 1.0.0

package/scripts/lib/budget-enforcer.js

@@ -0,0 +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,
+};

package/scripts/lib/claude-sessions.js

@@ -0,0 +1,285 @@
+/**
+ * @file claude-sessions.js
+ * @description Parser robusto de sesiones de Claude Code desde ~/.claude/projects/.
+ *
+ * Portado de mission-control-main/src/lib/claude-sessions.ts (líneas 1-266)
+ * Licencia original: MIT © 2026 Builderz Labs (https://github.com/builderz-labs/mission-control)
+ *
+ * Diferencias respecto al parser de claude-usage:
+ * - Parsea cache tokens (cacheRead, cacheWrite) para costo real (no solo estimado)
+ * - Extrae tool_uses por conteo de bloques content[].type === 'tool_use'
+ * - Detecta gitBranch del campo gitBranch en entradas JSONL
+ * - Flag estaActiva con threshold configurable (default 90 min)
+ * - Skip de archivos > tamanoMaxMB (default 50 MB) con registro en stderr
+ * - Tolerancia a líneas JSONL mal formadas (try/catch por línea)
+ *
+ * Zero dependencias — solo Node.js stdlib (fs, path, os).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Tolerancia para timestamps en el futuro (1 minuto)
+const TOLERANCIA_FUTURO_MS = 60 * 1000;
+
+// Tabla de precios por modelo (USD por token)
+const PRECIOS_MODELO = {
+  'claude-opus-4-7': { entrada: 15 / 1_000_000, salida: 75 / 1_000_000 },
+  'claude-opus-4-6': { entrada: 15 / 1_000_000, salida: 75 / 1_000_000 },
+  'claude-sonnet-4-6': { entrada: 3 / 1_000_000, salida: 15 / 1_000_000 },
+  'claude-sonnet-4-5': { entrada: 3 / 1_000_000, salida: 15 / 1_000_000 },
+  'claude-haiku-4-5': { entrada: 0.8 / 1_000_000, salida: 4 / 1_000_000 },
+  'claude-haiku-4-5-20251001': { entrada: 0.8 / 1_000_000, salida: 4 / 1_000_000 },
+};
+
+const PRECIO_DEFAULT = { entrada: 3 / 1_000_000, salida: 15 / 1_000_000 };
+
+/**
+ * Clampea un timestamp en ms: descarta valores negativos, cero o muy en el futuro.
+ *
+ * @param {number} ms - Timestamp en milisegundos
+ * @returns {number} Timestamp saneado (0 si es inválido)
+ */
+function clampearTimestamp(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return 0;
+  const ahora = Date.now();
+  if (ms > ahora + TOLERANCIA_FUTURO_MS) return ahora;
+  return ms;
+}
+
+/**
+ * Parsea un archivo JSONL de sesión de Claude Code y extrae métricas.
+ * Cada línea del archivo es un objeto JSON independiente.
+ *
+ * @param {string} ruta         - Ruta absoluta al archivo .jsonl
+ * @param {string} slugProyecto - Identificador del directorio de proyecto
+ * @param {number} mtimeMs      - Fecha de modificación del archivo en ms
+ * @param {number} tamanoBytes  - Tamaño del archivo en bytes
+ * @param {number} [tamanoMaxMB=50] - Tamaño máximo permitido en MB
+ * @returns {Object|null} Objeto de sesión o null si el archivo es inválido/omitido
+ */
+function parsearArchivoSesion(ruta, slugProyecto, mtimeMs, tamanoBytes, tamanoMaxMB = 50) {
+  const limiteBytes = tamanoMaxMB * 1024 * 1024;
+
+  if (tamanoBytes > limiteBytes) {
+    process.stderr.write(
+      `[claude-sessions] Omitiendo archivo grande: ${ruta} (${(tamanoBytes / 1024 / 1024).toFixed(1)} MB > ${tamanoMaxMB} MB)\n`
+    );
+    return null;
+  }
+
+  try {
+    const contenido = fs.readFileSync(ruta, 'utf-8');
+    const lineas = contenido.split('\n');
+
+    let sessionId = null;
+    let modelo = null;
+    let gitBranch = null;
+    let rutaProyecto = null;
+    let mensajesUsuario = 0;
+    let mensajesAsistente = 0;
+    let toolUses = 0;
+    let tokensEntrada = 0;
+    let tokensSalida = 0;
+    let tokensCacheRead = 0;
+    let tokensCacheWrite = 0;
+    let primeraFecha = null;
+    let ultimaFecha = null;
+    let tieneLineas = false;
+
+    for (const linea of lineas) {
+      if (!linea.trim()) continue;
+      tieneLineas = true;
+
+      let entrada;
+      try {
+        entrada = JSON.parse(linea);
+      } catch {
+        // Línea malformada — saltar sin abortar
+        continue;
+      }
+
+      if (!sessionId && entrada.sessionId) {
+        sessionId = entrada.sessionId;
+      }
+
+      if (!gitBranch && entrada.gitBranch) {
+        gitBranch = entrada.gitBranch;
+      }
+
+      if (!rutaProyecto && entrada.cwd) {
+        rutaProyecto = entrada.cwd;
+      }
+
+      if (entrada.timestamp) {
+        if (!primeraFecha) primeraFecha = entrada.timestamp;
+        ultimaFecha = entrada.timestamp;
+      }
+
+      // Saltar entradas de sidechain (sub-agentes internos de Claude)
+      if (entrada.isSidechain) continue;
+
+      if (entrada.type === 'user' && entrada.message) {
+        mensajesUsuario++;
+      }
+
+      if (entrada.type === 'assistant' && entrada.message) {
+        mensajesAsistente++;
+
+        if (entrada.message.model) {
+          modelo = entrada.message.model;
+        }
+
+        const uso = entrada.message.usage;
+        if (uso) {
+          tokensEntrada += (uso.input_tokens || 0);
+          tokensCacheRead += (uso.cache_read_input_tokens || 0);
+          tokensCacheWrite += (uso.cache_creation_input_tokens || 0);
+          tokensSalida += (uso.output_tokens || 0);
+        }
+
+        if (Array.isArray(entrada.message.content)) {
+          for (const bloque of entrada.message.content) {
+            if (bloque.type === 'tool_use') toolUses++;
+          }
+        }
+      }
+    }
+
+    if (!tieneLineas || !sessionId || (mensajesUsuario === 0 && mensajesAsistente === 0)) {
+      return null;
+    }
+
+    const precios = (modelo && PRECIOS_MODELO[modelo]) || PRECIO_DEFAULT;
+
+    // Los cache_read_tokens cuestan 10% del precio de entrada
+    // Los cache_creation_tokens cuestan 125% del precio de entrada
+    const costoEstimado =
+      tokensEntrada * precios.entrada +
+      tokensCacheRead * precios.entrada * 0.1 +
+      tokensCacheWrite * precios.entrada * 1.25 +
+      tokensSalida * precios.salida;
+
+    const primeraMs = primeraFecha ? clampearTimestamp(new Date(primeraFecha).getTime()) : 0;
+    const ultimaMs = ultimaFecha ? clampearTimestamp(new Date(ultimaFecha).getTime()) : 0;
+    const mtimeSaneado = clampearTimestamp(mtimeMs);
+
+    // Usar el más reciente entre la última entrada JSONL y el mtime del archivo
+    const efectivaUltimaMs = Math.max(ultimaMs, mtimeSaneado);
+    const efectivaPrimeraMs = primeraMs || mtimeSaneado;
+
+    return {
+      id: sessionId,
+      proyecto: slugProyecto,
+      rutaArchivo: ruta,
+      rutaProyecto,
+      primeraFecha: efectivaPrimeraMs ? new Date(efectivaPrimeraMs).toISOString() : null,
+      ultimaFecha: efectivaUltimaMs ? new Date(efectivaUltimaMs).toISOString() : null,
+      mensajes: mensajesUsuario + mensajesAsistente,
+      tokens: {
+        entrada: tokensEntrada + tokensCacheRead + tokensCacheWrite,
+        salida: tokensSalida,
+        cacheRead: tokensCacheRead,
+        cacheWrite: tokensCacheWrite,
+        total: tokensEntrada + tokensCacheRead + tokensCacheWrite + tokensSalida,
+      },
+      costoEstimado: Math.round(costoEstimado * 10000) / 10000,
+      toolUses,
+      modelo,
+      gitBranch,
+      duracionMs: (efectivaPrimeraMs && efectivaUltimaMs)
+        ? Math.max(0, efectivaUltimaMs - efectivaPrimeraMs)
+        : 0,
+      // estaActiva se calcula con el threshold pasado desde escanearSesiones
+      _ultimaMs: efectivaUltimaMs,
+    };
+  } catch (err) {
+    process.stderr.write(
+      `[claude-sessions] Error al parsear ${ruta}: ${err.message}\n`
+    );
+    return null;
+  }
+}
+
+/**
+ * Escanea todos los proyectos de Claude Code y devuelve las sesiones encontradas.
+ * Lee desde ~/.claude/projects/ por defecto.
+ *
+ * @param {Object} [opciones={}]
+ * @param {string} [opciones.rutaBase]                    - Directorio raíz de proyectos (default: ~/.claude/projects/)
+ * @param {number} [opciones.thresholdMinutosActiva=90]   - Minutos de inactividad para considerar sesión activa
+ * @param {number} [opciones.tamanoMaxMB=50]              - Tamaño máximo de archivo JSONL en MB
+ * @returns {Object[]} Array de objetos de sesión (puede ser vacío si no hay proyectos)
+ */
+function escanearSesiones({ rutaBase, thresholdMinutosActiva = 90, tamanoMaxMB = 50 } = {}) {
+  const directorioProyectos = rutaBase || path.join(os.homedir(), '.claude', 'projects');
+  const umbralActivoMs = thresholdMinutosActiva * 60 * 1000;
+  const ahora = Date.now();
+
+  let slugsProyecto;
+  try {
+    slugsProyecto = fs.readdirSync(directorioProyectos);
+  } catch {
+    // Directorio no existe o no es accesible — Claude Code no instalado o sin sesiones
+    return [];
+  }
+
+  const sesiones = [];
+
+  for (const slug of slugsProyecto) {
+    const dirProyecto = path.join(directorioProyectos, slug);
+
+    let stat;
+    try {
+      stat = fs.statSync(dirProyecto);
+    } catch {
+      continue;
+    }
+    if (!stat.isDirectory()) continue;
+
+    let archivos;
+    try {
+      archivos = fs.readdirSync(dirProyecto).filter(f => f.endsWith('.jsonl'));
+    } catch {
+      continue;
+    }
+
+    for (const archivo of archivos) {
+      const rutaArchivo = path.join(dirProyecto, archivo);
+
+      let statArchivo;
+      try {
+        statArchivo = fs.statSync(rutaArchivo);
+      } catch {
+        continue; // El archivo desapareció entre readdir y stat
+      }
+
+      const sesion = parsearArchivoSesion(
+        rutaArchivo,
+        slug,
+        statArchivo.mtimeMs,
+        statArchivo.size,
+        tamanoMaxMB
+      );
+
+      if (!sesion) continue;
+
+      // Calcular estaActiva con el threshold configurado
+      const estaActiva = sesion._ultimaMs > 0 && (ahora - sesion._ultimaMs) < umbralActivoMs;
+
+      // Eliminar campo interno antes de exponer
+      const { _ultimaMs, ...sesionPublica } = sesion;
+      sesiones.push({ ...sesionPublica, estaActiva });
+    }
+  }
+
+  return sesiones;
+}
+
+module.exports = {
+  escanearSesiones,
+  parsearArchivoSesion,
+};