@saulwade/swl-ses 1.0.0

package/hooks/lib/error-classifier.js

@@ -0,0 +1,308 @@
+'use strict';
+
+/**
+ * Error Classifier — Clasificación tipada de errores de API con hints de recuperación.
+ *
+ * Patrón adoptado de Hermes Agent (agent/error_classifier.py).
+ * Clasifica errores HTTP y de red en categorías con hints de acción:
+ *   - retryable: ¿vale la pena reintentar?
+ *   - shouldCompress: ¿hay que comprimir contexto?
+ *   - shouldFallback: ¿cambiar de modelo?
+ *   - shouldRotateCredential: ¿rotar API key?
+ *
+ * Zero dependencias externas.
+ *
+ * Uso:
+ *   const { clasificarError, RAZON } = require('./lib/error-classifier');
+ *
+ *   try {
+ *     await llamadaAPI();
+ *   } catch (error) {
+ *     const clasificado = clasificarError(error);
+ *     if (clasificado.retryable) {
+ *       // reintentar con jitteredBackoff
+ *     } else if (clasificado.shouldCompress) {
+ *       // comprimir contexto y reintentar
+ *     } else if (clasificado.shouldFallback) {
+ *       // cambiar a modelo alternativo
+ *     }
+ *   }
+ *
+ * @module hooks/lib/error-classifier
+ */
+
+// ---------------------------------------------------------------------------
+// Razones de error (enum-like)
+// ---------------------------------------------------------------------------
+
+/**
+ * Razones de error clasificadas.
+ * Cada razón tiene un significado semántico y sugiere una acción de recuperación.
+ *
+ * @readonly
+ * @enum {string}
+ */
+const RAZON = Object.freeze({
+  // Autenticación
+  AUTH:               'auth',               // 401/403 transitorio — rotar credential
+  AUTH_PERMANENTE:    'auth_permanente',    // 401/403 persistente — abortar
+
+  // Facturación / cuota
+  BILLING:            'billing',            // 402 o créditos agotados — rotar inmediato
+  RATE_LIMIT:         'rate_limit',         // 429 o throttling — backoff + rotar
+
+  // Servidor
+  SOBRECARGADO:       'sobrecargado',       // 503/529 — backoff largo
+  ERROR_SERVIDOR:     'error_servidor',     // 500/502 — retry corto
+
+  // Transporte
+  TIMEOUT:            'timeout',            // Timeout de conexión/lectura
+
+  // Contexto / payload
+  CONTEXTO_EXCEDIDO:  'contexto_excedido',  // Context length exceeded — comprimir
+  PAYLOAD_GRANDE:     'payload_grande',     // 413 — comprimir
+
+  // Modelo
+  MODELO_NO_ENCONTRADO: 'modelo_no_encontrado', // 404/invalid model — fallback
+
+  // Formato de request
+  ERROR_FORMATO:      'error_formato',      // 400 — revisar request
+
+  // Catch-all
+  DESCONOCIDO:        'desconocido',        // No clasificable — retry con backoff
+});
+
+// ---------------------------------------------------------------------------
+// Patrones de detección por mensaje de error
+// ---------------------------------------------------------------------------
+
+/** @type {Array<{ patron: RegExp, razon: string }>} */
+const PATRONES_BILLING = [
+  { patron: /insufficient\s+credits?/i, razon: RAZON.BILLING },
+  { patron: /credit\s+balance/i, razon: RAZON.BILLING },
+  { patron: /billing\s+hard\s+limit/i, razon: RAZON.BILLING },
+  { patron: /payment\s+required/i, razon: RAZON.BILLING },
+  { patron: /quota\s+exceeded/i, razon: RAZON.BILLING },
+];
+
+const PATRONES_RATE_LIMIT = [
+  { patron: /rate\s+limit/i, razon: RAZON.RATE_LIMIT },
+  { patron: /too\s+many\s+requests/i, razon: RAZON.RATE_LIMIT },
+  { patron: /throttl/i, razon: RAZON.RATE_LIMIT },
+  { patron: /requests?\s+per\s+(minute|second|hour)/i, razon: RAZON.RATE_LIMIT },
+];
+
+const PATRONES_CONTEXTO = [
+  { patron: /context\s+length/i, razon: RAZON.CONTEXTO_EXCEDIDO },
+  { patron: /context\s+size/i, razon: RAZON.CONTEXTO_EXCEDIDO },
+  { patron: /maximum\s+context/i, razon: RAZON.CONTEXTO_EXCEDIDO },
+  { patron: /token\s+limit/i, razon: RAZON.CONTEXTO_EXCEDIDO },
+  { patron: /max_tokens/i, razon: RAZON.CONTEXTO_EXCEDIDO },
+  { patron: /too\s+long/i, razon: RAZON.CONTEXTO_EXCEDIDO },
+];
+
+const PATRONES_PAYLOAD = [
+  { patron: /request\s+entity\s+too\s+large/i, razon: RAZON.PAYLOAD_GRANDE },
+  { patron: /error\s+code:\s*413/i, razon: RAZON.PAYLOAD_GRANDE },
+  { patron: /payload\s+too\s+large/i, razon: RAZON.PAYLOAD_GRANDE },
+];
+
+const PATRONES_TIMEOUT = [
+  { patron: /timed?\s*out/i, razon: RAZON.TIMEOUT },
+  { patron: /ETIMEDOUT/i, razon: RAZON.TIMEOUT },
+  { patron: /ECONNRESET/i, razon: RAZON.TIMEOUT },
+  { patron: /ECONNREFUSED/i, razon: RAZON.TIMEOUT },
+  { patron: /socket\s+hang\s+up/i, razon: RAZON.TIMEOUT },
+  { patron: /network\s+error/i, razon: RAZON.TIMEOUT },
+];
+
+const PATRONES_MODELO = [
+  { patron: /model\s+not\s+found/i, razon: RAZON.MODELO_NO_ENCONTRADO },
+  { patron: /invalid\s+model/i, razon: RAZON.MODELO_NO_ENCONTRADO },
+  { patron: /does\s+not\s+exist/i, razon: RAZON.MODELO_NO_ENCONTRADO },
+];
+
+const PATRONES_SOBRECARGA = [
+  { patron: /overloaded/i, razon: RAZON.SOBRECARGADO },
+  { patron: /service\s+unavailable/i, razon: RAZON.SOBRECARGADO },
+  { patron: /capacity/i, razon: RAZON.SOBRECARGADO },
+];
+
+const TODOS_LOS_PATRONES = [
+  ...PATRONES_BILLING,
+  ...PATRONES_RATE_LIMIT,
+  ...PATRONES_CONTEXTO,
+  ...PATRONES_PAYLOAD,
+  ...PATRONES_TIMEOUT,
+  ...PATRONES_MODELO,
+  ...PATRONES_SOBRECARGA,
+];
+
+// ---------------------------------------------------------------------------
+// Clasificación por status code
+// ---------------------------------------------------------------------------
+
+/**
+ * Clasifica un error basándose en el status code HTTP.
+ *
+ * @param {number} statusCode
+ * @returns {string|null} Razón o null si no hay match directo
+ */
+function _clasificarPorStatus(statusCode) {
+  switch (statusCode) {
+    case 400: return RAZON.ERROR_FORMATO;
+    case 401: return RAZON.AUTH;
+    case 402: return RAZON.BILLING;
+    case 403: return RAZON.AUTH;
+    case 404: return RAZON.MODELO_NO_ENCONTRADO;
+    case 408: return RAZON.TIMEOUT;
+    case 413: return RAZON.PAYLOAD_GRANDE;
+    case 429: return RAZON.RATE_LIMIT;
+    case 500: return RAZON.ERROR_SERVIDOR;
+    case 502: return RAZON.ERROR_SERVIDOR;
+    case 503: return RAZON.SOBRECARGADO;
+    case 504: return RAZON.TIMEOUT;
+    case 529: return RAZON.SOBRECARGADO;
+    default:  return null;
+  }
+}
+
+/**
+ * Clasifica un error basándose en el mensaje.
+ *
+ * @param {string} mensaje
+ * @returns {string|null} Razón o null
+ */
+function _clasificarPorMensaje(mensaje) {
+  if (!mensaje) return null;
+  for (const { patron, razon } of TODOS_LOS_PATRONES) {
+    if (patron.test(mensaje)) return razon;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Hints de recuperación por razón
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} HintsRecuperacion
+ * @property {boolean} retryable           - ¿Reintentar?
+ * @property {boolean} shouldCompress      - ¿Comprimir contexto?
+ * @property {boolean} shouldFallback      - ¿Cambiar de modelo?
+ * @property {boolean} shouldRotateCredential - ¿Rotar API key?
+ */
+
+/** @type {Object.<string, HintsRecuperacion>} */
+const HINTS_POR_RAZON = {
+  [RAZON.AUTH]:               { retryable: true,  shouldCompress: false, shouldFallback: false, shouldRotateCredential: true  },
+  [RAZON.AUTH_PERMANENTE]:    { retryable: false, shouldCompress: false, shouldFallback: false, shouldRotateCredential: false },
+  [RAZON.BILLING]:            { retryable: false, shouldCompress: false, shouldFallback: true,  shouldRotateCredential: true  },
+  [RAZON.RATE_LIMIT]:         { retryable: true,  shouldCompress: false, shouldFallback: false, shouldRotateCredential: false },
+  [RAZON.SOBRECARGADO]:       { retryable: true,  shouldCompress: false, shouldFallback: false, shouldRotateCredential: false },
+  [RAZON.ERROR_SERVIDOR]:     { retryable: true,  shouldCompress: false, shouldFallback: false, shouldRotateCredential: false },
+  [RAZON.TIMEOUT]:            { retryable: true,  shouldCompress: false, shouldFallback: false, shouldRotateCredential: false },
+  [RAZON.CONTEXTO_EXCEDIDO]:  { retryable: false, shouldCompress: true,  shouldFallback: false, shouldRotateCredential: false },
+  [RAZON.PAYLOAD_GRANDE]:     { retryable: false, shouldCompress: true,  shouldFallback: false, shouldRotateCredential: false },
+  [RAZON.MODELO_NO_ENCONTRADO]: { retryable: false, shouldCompress: false, shouldFallback: true,  shouldRotateCredential: false },
+  [RAZON.ERROR_FORMATO]:      { retryable: false, shouldCompress: false, shouldFallback: false, shouldRotateCredential: false },
+  [RAZON.DESCONOCIDO]:        { retryable: true,  shouldCompress: false, shouldFallback: false, shouldRotateCredential: false },
+};
+
+// ---------------------------------------------------------------------------
+// API pública
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} ErrorClasificado
+ * @property {string} razon             - Razón del error (valor de RAZON)
+ * @property {number|null} statusCode   - Status code HTTP (si disponible)
+ * @property {string} mensaje           - Mensaje del error original
+ * @property {boolean} retryable        - ¿Reintentar?
+ * @property {boolean} shouldCompress   - ¿Comprimir contexto?
+ * @property {boolean} shouldFallback   - ¿Cambiar de modelo?
+ * @property {boolean} shouldRotateCredential - ¿Rotar API key?
+ * @property {string} descripcion       - Descripción legible de la clasificación
+ */
+
+/**
+ * Clasifica un error de API y retorna hints de recuperación.
+ *
+ * Acepta objetos Error nativos, respuestas HTTP, o strings.
+ * La clasificación combina status code + análisis de mensaje.
+ *
+ * @param {Error|object|string} error - Error a clasificar
+ * @param {object} [contexto]
+ * @param {string} [contexto.provider] - Provider que originó el error
+ * @param {string} [contexto.modelo]   - Modelo usado
+ * @returns {ErrorClasificado}
+ */
+function clasificarError(error, contexto = {}) {
+  // Extraer statusCode y mensaje del error
+  let statusCode = null;
+  let mensaje = '';
+
+  if (typeof error === 'string') {
+    mensaje = error;
+  } else if (error instanceof Error) {
+    mensaje = error.message || '';
+    statusCode = error.status || error.statusCode || error.code || null;
+    if (typeof statusCode === 'string') {
+      const parsed = parseInt(statusCode, 10);
+      statusCode = isNaN(parsed) ? null : parsed;
+    }
+  } else if (error && typeof error === 'object') {
+    mensaje = error.message || error.error || JSON.stringify(error);
+    statusCode = error.status || error.statusCode || null;
+  }
+
+  // Clasificar: primero por status, luego por mensaje
+  let razon = null;
+  if (statusCode) {
+    razon = _clasificarPorStatus(statusCode);
+  }
+  if (!razon) {
+    razon = _clasificarPorMensaje(mensaje);
+  }
+  if (!razon) {
+    razon = RAZON.DESCONOCIDO;
+  }
+
+  const hints = HINTS_POR_RAZON[razon] || HINTS_POR_RAZON[RAZON.DESCONOCIDO];
+
+  // Descripción legible
+  const descripciones = {
+    [RAZON.AUTH]:               'Error de autenticación — verificar o rotar credencial',
+    [RAZON.AUTH_PERMANENTE]:    'Autenticación rechazada permanentemente — abortar',
+    [RAZON.BILLING]:            'Créditos agotados o límite de facturación — cambiar provider/cuenta',
+    [RAZON.RATE_LIMIT]:         'Límite de tasa excedido — aplicar backoff',
+    [RAZON.SOBRECARGADO]:       'Servidor sobrecargado — esperar y reintentar',
+    [RAZON.ERROR_SERVIDOR]:     'Error interno del servidor — reintentar',
+    [RAZON.TIMEOUT]:            'Timeout de conexión/lectura — reintentar con timeout mayor',
+    [RAZON.CONTEXTO_EXCEDIDO]:  'Contexto excede el límite del modelo — comprimir',
+    [RAZON.PAYLOAD_GRANDE]:     'Payload demasiado grande — comprimir o dividir',
+    [RAZON.MODELO_NO_ENCONTRADO]: 'Modelo no encontrado — usar modelo alternativo',
+    [RAZON.ERROR_FORMATO]:      'Error de formato en request — revisar parámetros',
+    [RAZON.DESCONOCIDO]:        'Error no clasificado — reintentar con backoff conservador',
+  };
+
+  return {
+    razon,
+    statusCode,
+    mensaje,
+    provider: contexto.provider || null,
+    modelo: contexto.modelo || null,
+    ...hints,
+    descripcion: descripciones[razon] || descripciones[RAZON.DESCONOCIDO],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  clasificarError,
+  RAZON,
+  HINTS_POR_RAZON,
+};

package/hooks/lib/event-bus.js

@@ -0,0 +1,112 @@
+'use strict';
+
+/**
+ * event-bus.js
+ *
+ * Bus de eventos pub/sub en memoria para comunicación desacoplada entre
+ * componentes del sistema SWL. Portado del patrón InMemoryBus de rowboat.
+ *
+ * Características:
+ *   - Suscriptores por runId específico o wildcard '*' (todos los runs)
+ *   - Publicación síncrona (invoca callbacks en orden de registro)
+ *   - Retorna función de unsubscribe al suscribirse
+ *   - Zero-dependencies (solo módulos nativos de Node.js)
+ *
+ * Tipos de eventos emitidos por el sistema SWL:
+ *   tool-call      — PostToolUse: herramienta invocada (toolName, input parcial)
+ *   tool-result    — PostToolUse: resultado de herramienta (toolName, éxito/error)
+ *   session-start  — Inicio de sesión (sessionId, cwd)
+ *   session-stop   — Fin de sesión (sessionId, resumen de costo)
+ *   agent-invoked  — Un agente SWL fue lanzado (agentName, subagentType)
+ *   skill-loaded   — Un skill fue cargado (skillName)
+ *   budget-alert   — Se superó el umbral de presupuesto (pct, tipo)
+ *
+ * Uso típico:
+ *   const bus = require('./event-bus');
+ *   const unsub = bus.subscribe('session-123', (event) => { ... });
+ *   bus.publish({ type: 'tool-call', runId: 'session-123', toolName: 'Bash' });
+ *   unsub(); // desregistrar
+ */
+
+// ---------------------------------------------------------------------------
+// Estado del bus (singleton por proceso)
+// ---------------------------------------------------------------------------
+
+/** @type {Map<string, Array<(event: object) => void>>} */
+const subscribers = new Map();
+
+// ---------------------------------------------------------------------------
+// API pública
+// ---------------------------------------------------------------------------
+
+/**
+ * Suscribirse a eventos de un runId específico o a todos los eventos ('*').
+ *
+ * @param {string} runId - ID del run a escuchar, o '*' para todos.
+ * @param {(event: object) => void} handler - Función invocada con cada evento.
+ * @returns {() => void} Función para cancelar la suscripción.
+ */
+function subscribe(runId, handler) {
+  if (!subscribers.has(runId)) {
+    subscribers.set(runId, []);
+  }
+  subscribers.get(runId).push(handler);
+
+  // Retornar función de unsubscribe
+  return function unsubscribe() {
+    const lista = subscribers.get(runId);
+    if (!lista) return;
+    const idx = lista.indexOf(handler);
+    if (idx !== -1) lista.splice(idx, 1);
+    if (lista.length === 0) subscribers.delete(runId);
+  };
+}
+
+/**
+ * Publicar un evento a todos los suscriptores del runId y a los wildcards.
+ * Los errores en handlers individuales no detienen la cadena.
+ *
+ * @param {object} event - Objeto de evento. Debe tener al menos: { type, runId }.
+ */
+function publish(event) {
+  if (!event || typeof event.type !== 'string') return;
+
+  const runId = String(event.runId || 'default');
+
+  // Suscriptores específicos del runId
+  const porRun = subscribers.get(runId) || [];
+  for (const handler of porRun) {
+    try { handler(event); } catch (_) { /* nunca propagar errores de handlers */ }
+  }
+
+  // Suscriptores wildcard (escuchan todos los runs)
+  if (runId !== '*') {
+    const wildcards = subscribers.get('*') || [];
+    for (const handler of wildcards) {
+      try { handler(event); } catch (_) { /* nunca propagar errores de handlers */ }
+    }
+  }
+}
+
+/**
+ * Eliminar todos los suscriptores de un runId (limpieza post-sesión).
+ *
+ * @param {string} runId
+ */
+function cleanup(runId) {
+  subscribers.delete(runId);
+}
+
+/**
+ * Estado del bus (para diagnóstico).
+ *
+ * @returns {{ subscriptions: number, runs: string[] }}
+ */
+function stats() {
+  return {
+    subscriptions: Array.from(subscribers.values()).reduce((acc, v) => acc + v.length, 0),
+    runs: Array.from(subscribers.keys()),
+  };
+}
+
+module.exports = { subscribe, publish, cleanup, stats };