@saulwade/swl-ses 1.0.0

package/hooks/lib/provenance-tracker.js

@@ -0,0 +1,183 @@
+'use strict';
+
+/**
+ * Provenance Tracker — Rastreo de proveniencia de skills y componentes.
+ *
+ * Registra de dónde viene cada skill/agente instalado: si es del core SWL,
+ * de un repo externo, de auto-evolución, o de la comunidad. Genera y lee
+ * archivos meta.json por componente.
+ *
+ * Patrón adoptado de skillshare (internal/install/meta.go).
+ *
+ * Zero dependencias externas.
+ *
+ * Uso:
+ *   const { registrarProveniencia, leerProveniencia, listarProveniencias } = require('./lib/provenance-tracker');
+ *
+ *   registrarProveniencia('/ruta/skill', {
+ *     origin: 'core',
+ *     repoUrl: 'https://github.com/saulwadeleon/swl-ses',
+ *     version: '5.6.3',
+ *   });
+ *
+ *   const meta = leerProveniencia('/ruta/skill');
+ *   // { origin: 'core', repoUrl: '...', version: '5.6.3', installedAt: '...' }
+ *
+ * @module hooks/lib/provenance-tracker
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+const META_FILENAME = 'meta.json';
+
+/**
+ * Orígenes válidos de un componente.
+ * @readonly
+ */
+const ORIGENES = Object.freeze({
+  CORE:           'core',           // Del paquete swl-ses
+  AUTO_EVOLUTION: 'auto-evolution', // Generado por /swl:evolucionar
+  IMPORTED:       'imported',       // Importado de repo externo
+  COMMUNITY:      'community',     // De skills.sh o similares
+  USERLAND:       'userland',       // Del usuario (_userland/)
+  ANTHROPIC:      'anthropic',      // De anthropics/skills
+});
+
+// ---------------------------------------------------------------------------
+// API pública
+// ---------------------------------------------------------------------------
+
+/**
+ * Registra la proveniencia de un componente instalado.
+ *
+ * Crea o actualiza meta.json en el directorio del componente.
+ *
+ * @param {string} componentDir - Ruta al directorio del componente
+ * @param {object} datos
+ * @param {string} datos.origin     - Origen (ver ORIGENES)
+ * @param {string} [datos.repoUrl]  - URL del repo de origen
+ * @param {string} [datos.commit]   - Commit hash del origen
+ * @param {string} [datos.version]  - Versión del sistema al instalar
+ * @param {string} [datos.author]   - Autor o equipo
+ * @param {string} [datos.note]     - Nota libre
+ */
+function registrarProveniencia(componentDir, datos) {
+  const metaPath = path.join(componentDir, META_FILENAME);
+
+  const meta = {
+    origin: datos.origin || ORIGENES.CORE,
+    repoUrl: datos.repoUrl || null,
+    commit: datos.commit || null,
+    version: datos.version || null,
+    author: datos.author || null,
+    note: datos.note || null,
+    installedAt: new Date().toISOString(),
+    installedBy: `swl-ses v${datos.version || 'unknown'}`,
+  };
+
+  // Si ya existe, preservar datos anteriores y agregar historial
+  if (fs.existsSync(metaPath)) {
+    try {
+      const existing = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+      // Mover datos anteriores a historial
+      if (!existing.history) existing.history = [];
+      const { history, ...prevData } = existing;
+      existing.history.push({ ...prevData, replacedAt: meta.installedAt });
+
+      // Actualizar con nuevos datos
+      Object.assign(existing, meta);
+      existing.history = existing.history.slice(-5); // Máximo 5 entradas de historial
+
+      fs.writeFileSync(metaPath, JSON.stringify(existing, null, 2), 'utf8');
+    } catch {
+      // Error leyendo existente — sobrescribir
+      fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), 'utf8');
+    }
+  } else {
+    fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), 'utf8');
+  }
+}
+
+/**
+ * Lee la proveniencia de un componente.
+ *
+ * @param {string} componentDir - Ruta al directorio del componente
+ * @returns {object|null} Datos de proveniencia o null si no existe
+ */
+function leerProveniencia(componentDir) {
+  const metaPath = path.join(componentDir, META_FILENAME);
+  if (!fs.existsSync(metaPath)) return null;
+
+  try {
+    return JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Lista la proveniencia de todos los componentes en un directorio.
+ *
+ * @param {string} parentDir - Directorio padre (ej: habilidades/)
+ * @returns {Array<{ name: string, origin: string, version: string, installedAt: string }>}
+ */
+function listarProveniencias(parentDir) {
+  if (!fs.existsSync(parentDir)) return [];
+
+  const resultado = [];
+  const entries = fs.readdirSync(parentDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const meta = leerProveniencia(path.join(parentDir, entry.name));
+    resultado.push({
+      name: entry.name,
+      origin: meta ? meta.origin : 'unknown',
+      version: meta ? meta.version : null,
+      installedAt: meta ? meta.installedAt : null,
+      repoUrl: meta ? meta.repoUrl : null,
+    });
+  }
+
+  return resultado;
+}
+
+/**
+ * Genera un resumen de proveniencia por origen.
+ *
+ * @param {string} parentDir - Directorio padre
+ * @returns {{ total: number, byOrigin: Object<string, number>, unknown: number }}
+ */
+function resumenProveniencia(parentDir) {
+  const lista = listarProveniencias(parentDir);
+  const byOrigin = {};
+  let unknown = 0;
+
+  for (const item of lista) {
+    if (item.origin === 'unknown') {
+      unknown++;
+    } else {
+      byOrigin[item.origin] = (byOrigin[item.origin] || 0) + 1;
+    }
+  }
+
+  return { total: lista.length, byOrigin, unknown };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  registrarProveniencia,
+  leerProveniencia,
+  listarProveniencias,
+  resumenProveniencia,
+  ORIGENES,
+  META_FILENAME,
+};

package/hooks/lib/rate-limit-tracker.js

@@ -0,0 +1,253 @@
+'use strict';
+
+/**
+ * Rate Limit Tracker — Awareness de límites de tasa per-provider.
+ *
+ * Patrón adoptado de Hermes Agent (agent/rate_limit_tracker.py).
+ * Registra respuestas 429 y headers de rate limit para ajustar
+ * timing de llamadas y prevenir cascadas de error.
+ *
+ * Zero dependencias externas.
+ *
+ * Uso:
+ *   const { tracker } = require('./lib/rate-limit-tracker');
+ *
+ *   // Registrar un 429
+ *   tracker.registrar429('anthropic', { retryAfter: 30, modelo: 'claude-sonnet-4-6' });
+ *
+ *   // Consultar antes de llamar
+ *   if (tracker.estaThrottled('anthropic')) {
+ *     const espera = tracker.tiempoEspera('anthropic');
+ *     console.log(`Provider throttled, esperar ${espera}s`);
+ *   }
+ *
+ *   // Registrar éxito (resetea contadores)
+ *   tracker.registrarExito('anthropic');
+ *
+ * @module hooks/lib/rate-limit-tracker
+ */
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+/** Máximo de 429s consecutivos antes de marcar provider como BLOQUEADO. */
+const MAX_429_CONSECUTIVOS = 5;
+
+/** Tiempo base de backoff en ms tras un 429 (si no hay Retry-After). */
+const BACKOFF_BASE_MS = 10_000;
+
+/** Multiplicador de backoff exponencial por 429 consecutivo. */
+const BACKOFF_MULTIPLICADOR = 2;
+
+/** Tiempo máximo de backoff en ms (5 minutos). */
+const BACKOFF_MAX_MS = 300_000;
+
+/** Tiempo de recuperación half-open en ms (1 minuto). */
+const HALF_OPEN_MS = 60_000;
+
+/** Tiempo para considerar un registro como stale y limpiar (30 minutos). */
+const STALE_MS = 1_800_000;
+
+// ---------------------------------------------------------------------------
+// Estado del tracker (en memoria, por sesión)
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} ProviderState
+ * @property {number} consecutivos429   - Conteo de 429s consecutivos
+ * @property {number} ultimoTimestamp    - Timestamp del último 429
+ * @property {number} esperaHastaMs     - Timestamp hasta el cual esperar
+ * @property {string} estado            - 'ok' | 'throttled' | 'bloqueado' | 'half-open'
+ * @property {string|null} modelo       - Último modelo que causó 429
+ * @property {number} totalHistorico    - Total de 429s en la sesión
+ */
+
+/** @type {Map<string, ProviderState>} */
+const _providers = new Map();
+
+// ---------------------------------------------------------------------------
+// Funciones internas
+// ---------------------------------------------------------------------------
+
+/**
+ * Obtiene o crea el estado de un provider.
+ * @param {string} provider
+ * @returns {ProviderState}
+ */
+function _obtenerEstado(provider) {
+  if (!_providers.has(provider)) {
+    _providers.set(provider, {
+      consecutivos429: 0,
+      ultimoTimestamp: 0,
+      esperaHastaMs: 0,
+      estado: 'ok',
+      modelo: null,
+      totalHistorico: 0,
+    });
+  }
+  return _providers.get(provider);
+}
+
+/**
+ * Calcula el delay de backoff para un número de 429s consecutivos.
+ * @param {number} consecutivos
+ * @param {number|null} retryAfterSeg - Valor de Retry-After del header (en segundos)
+ * @returns {number} Delay en milisegundos
+ */
+function _calcularBackoff(consecutivos, retryAfterSeg) {
+  if (retryAfterSeg && retryAfterSeg > 0) {
+    return retryAfterSeg * 1000;
+  }
+  const delay = BACKOFF_BASE_MS * Math.pow(BACKOFF_MULTIPLICADOR, consecutivos - 1);
+  return Math.min(delay, BACKOFF_MAX_MS);
+}
+
+// ---------------------------------------------------------------------------
+// API pública
+// ---------------------------------------------------------------------------
+
+const tracker = {
+  /**
+   * Registra una respuesta 429 de un provider.
+   *
+   * @param {string} provider - Nombre del provider ('anthropic', 'openai', etc.)
+   * @param {object} [info]
+   * @param {number} [info.retryAfter]  - Valor del header Retry-After en segundos
+   * @param {string} [info.modelo]      - Modelo que causó el 429
+   */
+  registrar429(provider, info = {}) {
+    const estado = _obtenerEstado(provider);
+    const ahora = Date.now();
+
+    estado.consecutivos429 += 1;
+    estado.ultimoTimestamp = ahora;
+    estado.totalHistorico += 1;
+    estado.modelo = info.modelo || estado.modelo;
+
+    const backoff = _calcularBackoff(estado.consecutivos429, info.retryAfter);
+    estado.esperaHastaMs = ahora + backoff;
+
+    if (estado.consecutivos429 >= MAX_429_CONSECUTIVOS) {
+      estado.estado = 'bloqueado';
+    } else {
+      estado.estado = 'throttled';
+    }
+  },
+
+  /**
+   * Registra una llamada exitosa — resetea contadores del provider.
+   *
+   * @param {string} provider
+   */
+  registrarExito(provider) {
+    const estado = _obtenerEstado(provider);
+    estado.consecutivos429 = 0;
+    estado.esperaHastaMs = 0;
+    estado.estado = 'ok';
+  },
+
+  /**
+   * Verifica si un provider está throttled o bloqueado.
+   *
+   * @param {string} provider
+   * @returns {boolean}
+   */
+  estaThrottled(provider) {
+    const estado = _obtenerEstado(provider);
+    const ahora = Date.now();
+
+    if (estado.estado === 'ok') return false;
+
+    // Verificar si ya pasó el tiempo de espera
+    if (ahora >= estado.esperaHastaMs) {
+      if (estado.estado === 'bloqueado') {
+        // Transición a half-open para permitir un intento de prueba
+        estado.estado = 'half-open';
+        estado.esperaHastaMs = ahora + HALF_OPEN_MS;
+        return false; // permitir un intento
+      }
+      // Throttled normal — ya pasó el backoff
+      estado.estado = 'ok';
+      estado.consecutivos429 = 0;
+      return false;
+    }
+
+    return true;
+  },
+
+  /**
+   * Retorna el tiempo de espera restante en segundos.
+   *
+   * @param {string} provider
+   * @returns {number} Segundos restantes (0 si no está throttled)
+   */
+  tiempoEspera(provider) {
+    const estado = _obtenerEstado(provider);
+    const restante = estado.esperaHastaMs - Date.now();
+    return restante > 0 ? Math.ceil(restante / 1000) : 0;
+  },
+
+  /**
+   * Retorna el estado completo de un provider.
+   *
+   * @param {string} provider
+   * @returns {ProviderState}
+   */
+  estado(provider) {
+    return { ..._obtenerEstado(provider) };
+  },
+
+  /**
+   * Retorna resumen de todos los providers trackeados.
+   *
+   * @returns {Array<{ provider: string, estado: string, consecutivos429: number, totalHistorico: number, tiempoEspera: number }>}
+   */
+  resumen() {
+    const resultado = [];
+    for (const [provider, estado] of _providers) {
+      resultado.push({
+        provider,
+        estado: estado.estado,
+        consecutivos429: estado.consecutivos429,
+        totalHistorico: estado.totalHistorico,
+        tiempoEspera: tracker.tiempoEspera(provider),
+        modelo: estado.modelo,
+      });
+    }
+    return resultado;
+  },
+
+  /**
+   * Limpia registros stale (sin actividad reciente).
+   * Llamar periódicamente para evitar memory leak en sesiones largas.
+   */
+  limpiarStale() {
+    const ahora = Date.now();
+    for (const [provider, estado] of _providers) {
+      if (estado.estado === 'ok' && (ahora - estado.ultimoTimestamp) > STALE_MS) {
+        _providers.delete(provider);
+      }
+    }
+  },
+
+  /**
+   * Resetea todo el tracker (útil para tests).
+   */
+  reset() {
+    _providers.clear();
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  tracker,
+  // Exponer constantes para tests
+  MAX_429_CONSECUTIVOS,
+  BACKOFF_BASE_MS,
+  BACKOFF_MAX_MS,
+  HALF_OPEN_MS,
+};

package/hooks/lib/reflect-classifier.js

@@ -0,0 +1,164 @@
+'use strict';
+
+/**
+ * reflect-classifier.js
+ *
+ * Operador Reflect del protocolo AGP (Zhang 2026 §3.2.2) — transforma la
+ * traza del payload del subagente en una hipotesis estructurada de fallo.
+ *
+ * Sin LLM: heuristicas regex sobre mensajes de error y output. Idempotente.
+ *
+ * Categorias estables (cerradas):
+ *   - bad_output_format
+ *   - tool_error
+ *   - timeout
+ *   - schema_violation
+ *   - task_incomplete
+ *   - unknown
+ *
+ * Zero-deps. Reutilizable por hooks de observabilidad y tests unitarios.
+ *
+ * @module hooks/lib/reflect-classifier
+ */
+
+const TIPOS = Object.freeze([
+  'bad_output_format',
+  'tool_error',
+  'timeout',
+  'schema_violation',
+  'task_incomplete',
+  'unknown',
+]);
+
+/**
+ * Clasifica el fallo de un subagente en una de las 6 categorias estables.
+ *
+ * @param {object} data      payload de SubagentStop
+ * @param {object} response  data.tool_response o data.tool_result
+ * @returns {string}         tipo_fallo
+ */
+function clasificarTipoFallo(data, response) {
+  data = data || {};
+  response = response || {};
+  const textoError = String(
+    response.error ||
+    response.error_message ||
+    response.message ||
+    data.error ||
+    ''
+  ).toLowerCase();
+  const rawOutput = String(response.output || response.content || '').slice(0, 4000).toLowerCase();
+
+  if (textoError.includes('timeout') || textoError.includes('timed out') ||
+      textoError.includes('exceeded max turns') || textoError.includes('maxturnos')) {
+    return 'timeout';
+  }
+
+  if (textoError.includes('schema') && (textoError.includes('invalid') || textoError.includes('violat'))) {
+    return 'schema_violation';
+  }
+  if (rawOutput.includes('does not match schema') || rawOutput.includes('schema validation failed')) {
+    return 'schema_violation';
+  }
+
+  if (textoError.includes('permission denied') || textoError.includes('enoent') ||
+      textoError.includes('command failed') || textoError.includes('exit code') ||
+      textoError.includes('tool execution') || textoError.includes('network') ||
+      textoError.includes('econnrefused') || textoError.includes('etimedout')) {
+    return 'tool_error';
+  }
+
+  if (textoError.includes('json') && (textoError.includes('parse') || textoError.includes('invalid'))) {
+    return 'bad_output_format';
+  }
+  if (textoError.includes('section') && textoError.includes('missing')) {
+    return 'bad_output_format';
+  }
+
+  if (rawOutput.includes('estado: parcial') || rawOutput.includes('estado: bloqueado') ||
+      rawOutput.includes('incomplete') || rawOutput.includes('pendiente:')) {
+    return 'task_incomplete';
+  }
+
+  if (textoError.length > 0) return 'tool_error';
+  return 'unknown';
+}
+
+/**
+ * Devuelve un hint accionable para el tipo de fallo dado.
+ * Lo consume el agente `auto-evolucion-swl` como anchor inicial de hipotesis.
+ */
+function hintMejoraParaTipo(tipo) {
+  switch (tipo) {
+    case 'bad_output_format':
+      return 'revisar seccion OUTPUT del agente — contrato de formato probablemente ambiguo';
+    case 'tool_error':
+      return 'revisar manejo de errores y precondiciones antes de tool calls';
+    case 'timeout':
+      return 'revisar toolBudget.complex y maxTurnos en frontmatter';
+    case 'schema_violation':
+      return 'revisar schemas/agent-output-*.schema.json y output del agente';
+    case 'task_incomplete':
+      return 'revisar protocolo de cierre: agente termina sin completar scope';
+    default:
+      return 'analizar trazas recientes para identificar causa raiz';
+  }
+}
+
+/**
+ * A partir de un resumen de fallos por tipo, construye el diagnosis que
+ * se propaga al nudge y al agente auto-evolucion-swl.
+ *
+ * @param {object} resumenAgente  { fallos, fallos_por_tipo }
+ * @returns {object|null}         null si no hay fallos clasificables
+ */
+function construirDiagnosis(resumenAgente) {
+  if (!resumenAgente || !resumenAgente.fallos) return null;
+  const distribucion = resumenAgente.fallos_por_tipo || {};
+  const tipos = Object.entries(distribucion).sort((a, b) => b[1] - a[1]);
+  if (tipos.length === 0) return null;
+  const [tipoDominante, conteo] = tipos[0];
+  return {
+    tipo_fallo:       tipoDominante,
+    conteo_dominante: conteo,
+    total_fallos:     resumenAgente.fallos,
+    distribucion:     Object.fromEntries(tipos),
+    hint_mejora:      hintMejoraParaTipo(tipoDominante),
+  };
+}
+
+/**
+ * Ejecuta detección de drift para un agente sobre el JSONL de trazas.
+ *
+ * Integración con scripts/lib/drift-detector.js (REC-D07).
+ * Si el módulo no está disponible, retorna null sin error.
+ *
+ * El módulo drift-detector vive en scripts/lib/ (no en hooks/lib/) porque
+ * lee JSONL de trazas de proyecto — no es lógica de hook en tiempo de ejecución.
+ * Se invoca aquí como punto de extensión del operador Reflect del ciclo AGP.
+ *
+ * @param {string} rutaJsonl - Ruta al JSONL de trazas del agente.
+ * @param {string} [nombreAgente] - Nombre del agente/skill para nudges.
+ * @returns {object|null} Resultado de detectarDrift o null si no disponible.
+ */
+function ejecutarDriftReflect(rutaJsonl, nombreAgente) {
+  let detectarDrift;
+  try {
+    ({ detectarDrift } = require('../../scripts/lib/drift-detector'));
+  } catch (_) {
+    return null;
+  }
+  try {
+    return detectarDrift({ rutaJsonl, agente: nombreAgente });
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = {
+  TIPOS,
+  clasificarTipoFallo,
+  hintMejoraParaTipo,
+  construirDiagnosis,
+  ejecutarDriftReflect,
+};