@saulwade/swl-ses 1.0.0

package/hooks/lib/model-router.js

@@ -0,0 +1,222 @@
+'use strict';
+
+/**
+ * lib/model-router.js
+ * Model Router — Sugiere modelo optimo por complejidad de tarea.
+ *
+ * No fuerza el modelo (Claude Code lo decide), pero el orquestador
+ * puede usar esta sugerencia al delegar a subagentes.
+ *
+ * API publica:
+ *   sugerirModelo(descripcionTarea, contexto) → { modelo, complejidad, razon, costoRelativo }
+ *   MODELOS                                   → { HAIKU, SONNET, OPUS }
+ *   COMPLEJIDAD                               → { trivial, estandar, compleja }
+ */
+
+// ---------------------------------------------------------------------------
+// Constantes de modelos
+// ---------------------------------------------------------------------------
+
+/**
+ * Identificadores canonicos de modelo por tier de capacidad.
+ */
+const MODELOS = {
+  HAIKU:  'haiku',
+  SONNET: 'sonnet',
+  OPUS:   'opus',
+};
+
+// ---------------------------------------------------------------------------
+// Tabla de complejidad
+// ---------------------------------------------------------------------------
+
+/**
+ * Mapa de nivel de complejidad a modelo recomendado e indicadores de deteccion.
+ *
+ * El orden de evaluacion es: compleja → trivial → estandar (fallback).
+ * Se usa el primer indicador que coincida en la descripcion de la tarea.
+ */
+const COMPLEJIDAD = {
+  trivial: {
+    modelo: MODELOS.HAIKU,
+    indicadores: [
+      'formateo',
+      'typo',
+      'renombrar',
+      'import',
+      'lint fix',
+      'comment',
+    ],
+  },
+  estandar: {
+    modelo: MODELOS.SONNET,
+    indicadores: [
+      'implementar',
+      'test',
+      'review',
+      'refactor',
+      'endpoint',
+      'componente',
+      'fix bug',
+    ],
+  },
+  compleja: {
+    modelo: MODELOS.OPUS,
+    indicadores: [
+      'arquitectura',
+      'migracion',
+      'seguridad',
+      'performance',
+      'disenar',
+      'planificar',
+      'debugging profundo',
+      'sistema completo',
+    ],
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Logica de evaluacion
+// ---------------------------------------------------------------------------
+
+/**
+ * Busca el primer indicador de una lista que aparezca en la descripcion.
+ *
+ * @param {string}   descripcion - Texto en minusculas de la tarea.
+ * @param {string[]} indicadores - Lista de indicadores a buscar.
+ * @returns {string|null} El primer indicador encontrado, o null.
+ */
+function primerIndicadorCoincidente(descripcion, indicadores) {
+  for (const indicador of indicadores) {
+    if (descripcion.includes(indicador)) return indicador;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// API publica
+// ---------------------------------------------------------------------------
+
+/**
+ * Evalua la complejidad de una tarea y sugiere el modelo optimo.
+ *
+ * Criterios de evaluacion (en orden de prioridad):
+ *   1. Contexto estructural: archivos afectados > 20 o lenguajes > 2 → opus
+ *   2. Indicadores de complejidad alta en la descripcion → opus
+ *   3. Indicadores de complejidad trivial + archivos <= 3 → haiku
+ *   4. Fallback: complejidad estandar → sonnet
+ *
+ * @param {string} descripcionTarea - Descripcion en lenguaje natural de la tarea.
+ * @param {object} [contexto={}]    - Contexto adicional de la tarea.
+ * @param {number} [contexto.archivosAfectados=0]    - Numero de archivos que tocara la tarea.
+ * @param {number} [contexto.lenguajesInvolucrados=1] - Numero de lenguajes de programacion.
+ * @returns {{ modelo: string, complejidad: string, razon: string, costoRelativo: string }}
+ *   - modelo:        Identificador del modelo sugerido ('haiku' | 'sonnet' | 'opus').
+ *   - complejidad:   Nivel detectado ('trivial' | 'estandar' | 'compleja').
+ *   - razon:         Justificacion legible de la sugerencia.
+ *   - costoRelativo: Indicador visual de costo ('$' | '$$' | '$$$').
+ */
+function sugerirModelo(descripcionTarea, contexto = {}) {
+  const desc         = (descripcionTarea || '').toLowerCase();
+  const numArchivos  = contexto.archivosAfectados    || 0;
+  const numLenguajes = contexto.lenguajesInvolucrados || 1;
+
+  // Criterio 1 — Contexto estructural de alta complejidad
+  if (numArchivos > 20 || numLenguajes > 2) {
+    return {
+      modelo:        MODELOS.OPUS,
+      complejidad:   'compleja',
+      razon:         `${numArchivos} archivos afectados, ${numLenguajes} lenguajes involucrados`,
+      costoRelativo: '$$$',
+    };
+  }
+
+  // Criterio 2 — Indicadores de complejidad alta en la descripcion
+  const indicadorComplejo = primerIndicadorCoincidente(desc, COMPLEJIDAD.compleja.indicadores);
+  if (indicadorComplejo) {
+    return {
+      modelo:        MODELOS.OPUS,
+      complejidad:   'compleja',
+      razon:         `indicador de alta complejidad detectado: "${indicadorComplejo}"`,
+      costoRelativo: '$$$',
+    };
+  }
+
+  // Criterio 3 — Indicadores triviales con alcance reducido
+  const indicadorTrivial = primerIndicadorCoincidente(desc, COMPLEJIDAD.trivial.indicadores);
+  if (indicadorTrivial && numArchivos <= 3) {
+    return {
+      modelo:        MODELOS.HAIKU,
+      complejidad:   'trivial',
+      razon:         `tarea de bajo alcance: indicador "${indicadorTrivial}", ${numArchivos} archivos`,
+      costoRelativo: '$',
+    };
+  }
+
+  // Criterio 4 — Fallback: complejidad estandar
+  return {
+    modelo:        MODELOS.SONNET,
+    complejidad:   'estandar',
+    razon:         'complejidad estandar — ningun indicador de nivel trivial o complejo detectado',
+    costoRelativo: '$$',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Proveedores — estructura extensible para routing multi-proveedor
+// ---------------------------------------------------------------------------
+
+/**
+ * Registro de proveedores de LLM.
+ *
+ * Actualmente swl-ses es mono-proveedor (Anthropic). Esta estructura
+ * permite evolucionar a multi-proveedor sin cambiar la API publica.
+ *
+ * Patron inspirado en instructor.from_provider() — interfaz unificada
+ * que abstrae el proveedor detrás de un string "proveedor/modelo".
+ *
+ * Para activar: setear PROVIDER en el contexto de sugerirModelo.
+ * Sin PROVIDER, el comportamiento es idéntico al actual (Anthropic).
+ */
+const PROVEEDORES = {
+  anthropic: {
+    nombre: 'Anthropic',
+    modelos: {
+      opus:   'claude-opus-4-7',
+      sonnet: 'claude-sonnet-4-6',
+      haiku:  'claude-haiku-4-5-20251001',
+    },
+    costoPorMillon: { opus: 15.0, sonnet: 3.0, haiku: 0.25 },
+    default: true,
+  },
+  // Proveedores futuros — descomentar al necesitar:
+  // openai: {
+  //   nombre: 'OpenAI',
+  //   modelos: { alto: 'gpt-4o', medio: 'gpt-4o-mini', bajo: 'gpt-3.5-turbo' },
+  //   costoPorMillon: { alto: 5.0, medio: 0.15, bajo: 0.05 },
+  // },
+  // google: {
+  //   nombre: 'Google',
+  //   modelos: { alto: 'gemini-pro', medio: 'gemini-flash', bajo: 'gemini-flash-lite' },
+  //   costoPorMillon: { alto: 3.5, medio: 0.35, bajo: 0.075 },
+  // },
+};
+
+/**
+ * Resuelve el identificador completo del modelo para un proveedor dado.
+ *
+ * @param {string} tier     - Tier del modelo ('opus'|'sonnet'|'haiku' para Anthropic).
+ * @param {string} [proveedor='anthropic'] - Identificador del proveedor.
+ * @returns {string} Identificador completo del modelo (ej: 'claude-sonnet-4-6').
+ */
+function resolverModeloCompleto(tier, proveedor = 'anthropic') {
+  const prov = PROVEEDORES[proveedor];
+  if (!prov) return tier; // fallback: devolver tier tal cual
+  return prov.modelos[tier] || tier;
+}
+
+// ---------------------------------------------------------------------------
+// Exportaciones
+// ---------------------------------------------------------------------------
+
+module.exports = { sugerirModelo, resolverModeloCompleto, MODELOS, COMPLEJIDAD, PROVEEDORES };

package/hooks/lib/normalize-error.js

@@ -0,0 +1,324 @@
+'use strict';
+
+/**
+ * normalize-error.js — Normalización de errores cross-contexto.
+ *
+ * Inspirado en tools/error-extractors.ts de Sim Studio (simstudioai/sim).
+ * Convierte errores de distintos orígenes en una estructura uniforme que
+ * facilita el logging, reporting y decisiones de recuperación en hooks y agentes.
+ *
+ * Estructura de error normalizado (NormalizedError):
+ * {
+ *   codigo:      string  — clave semántica (RATE_LIMIT, NOT_FOUND, TIMEOUT, ...)
+ *   mensaje:     string  — descripción legible en español
+ *   categoria:   string  — 'api' | 'sistema' | 'hook' | 'agente' | 'herramienta' | 'desconocido'
+ *   severidad:   string  — 'warning' | 'error' | 'fatal'
+ *   recuperable: boolean — si se puede reintentar o hay workaround
+ *   fuente:      string  — dónde se originó (nombre de módulo/hook)
+ *   detalle:     string  — mensaje original del error
+ *   sugerencia:  string|null — acción recomendada al usuario
+ * }
+ *
+ * Uso:
+ *   const { normalizar, formatear } = require('./lib/normalize-error');
+ *   try { ... }
+ *   catch (e) {
+ *     const err = normalizar(e, { fuente: 'mi-hook' });
+ *     process.stderr.write(formatear(err) + '\n');
+ *   }
+ *
+ * Zero-dependencies: solo usa Node.js built-ins.
+ *
+ * @module hooks/lib/normalize-error
+ */
+
+// ---------------------------------------------------------------------------
+// Tabla de patrones conocidos
+// ---------------------------------------------------------------------------
+
+/**
+ * Patrones de mensajes de error → código normalizado.
+ * Se evalúan en orden; el primero que coincida gana.
+ *
+ * @type {Array<PatronError>}
+ *
+ * @typedef {object} PatronError
+ * @property {RegExp}      patron      — Expresión regular contra el mensaje de error
+ * @property {string}      codigo      — Código semántico del error
+ * @property {string}      categoria   — Categoría del error
+ * @property {string}      severidad   — Nivel de severidad
+ * @property {boolean}     recuperable — Si el error permite reintento
+ * @property {string|null} sugerencia  — Acción recomendada
+ */
+const PATRONES = [
+  // Claude API — rate limiting
+  {
+    patron:      /rate.?limit|429|too many requests/i,
+    codigo:      'RATE_LIMIT',
+    categoria:   'api',
+    severidad:   'warning',
+    recuperable: true,
+    sugerencia:  'Esperar 60 segundos y reintentar. Considerar reducir la concurrencia de agentes.',
+  },
+  // Claude API — sobrecargada
+  {
+    patron:      /overloaded|529|service.?unavailable/i,
+    codigo:      'API_OVERLOADED',
+    categoria:   'api',
+    severidad:   'warning',
+    recuperable: true,
+    sugerencia:  'La API de Anthropic está sobrecargada. Reintentar en 30-60 segundos.',
+  },
+  // Claude API — ventana de contexto
+  {
+    patron:      /context.?window|max.?token|too.?long|token.?limit|prompt.?too.?long/i,
+    codigo:      'CONTEXT_OVERFLOW',
+    categoria:   'api',
+    severidad:   'error',
+    recuperable: true,
+    sugerencia:  'Ejecutar /swl:compactar para reducir el contexto antes de continuar.',
+  },
+  // Claude API — autenticación
+  {
+    patron:      /401|unauthorized|invalid.?api.?key|authentication.?failed/i,
+    codigo:      'AUTH_FAILED',
+    categoria:   'api',
+    severidad:   'fatal',
+    recuperable: false,
+    sugerencia:  'Verificar ANTHROPIC_API_KEY en el entorno. Ejecutar `claude login` si es necesario.',
+  },
+  // Claude API — forbidden
+  {
+    patron:      /403|forbidden|access.?denied/i,
+    codigo:      'FORBIDDEN',
+    categoria:   'api',
+    severidad:   'fatal',
+    recuperable: false,
+    sugerencia:  'La cuenta no tiene acceso a este modelo o recurso. Verificar plan y permisos.',
+  },
+  // Red — conexión
+  {
+    patron:      /ECONNREFUSED|ECONNRESET|ENOTFOUND|socket.?hang.?up|network.?error/i,
+    codigo:      'NETWORK_ERROR',
+    categoria:   'sistema',
+    severidad:   'error',
+    recuperable: true,
+    sugerencia:  'Verificar conectividad de red y que la API de Anthropic es accesible.',
+  },
+  // Red — timeout
+  {
+    patron:      /ETIMEDOUT|timed.?out|timeout/i,
+    codigo:      'TIMEOUT',
+    categoria:   'sistema',
+    severidad:   'error',
+    recuperable: true,
+    sugerencia:  'La operación tardó demasiado. Reintentar con un timeout mayor o simplificar la tarea.',
+  },
+  // Sistema — archivo no encontrado
+  {
+    patron:      /ENOENT|no such file|cannot find.+module|MODULE_NOT_FOUND/i,
+    codigo:      'NOT_FOUND',
+    categoria:   'sistema',
+    severidad:   'error',
+    recuperable: false,
+    sugerencia:  'Verificar que el archivo o módulo existe en la ruta indicada.',
+  },
+  // Sistema — permisos
+  {
+    patron:      /EACCES|EPERM|permission.?denied/i,
+    codigo:      'PERMISSION_DENIED',
+    categoria:   'sistema',
+    severidad:   'error',
+    recuperable: false,
+    sugerencia:  'Verificar permisos del archivo o directorio. Puede requerir privilegios elevados.',
+  },
+  // JSON — parseo
+  {
+    patron:      /unexpected.?token|JSON.?parse|invalid.?json|not.?valid.?json/i,
+    codigo:      'PARSE_ERROR',
+    categoria:   'herramienta',
+    severidad:   'error',
+    recuperable: false,
+    sugerencia:  'El output recibido no es JSON válido. Verificar la fuente de datos.',
+  },
+  // Proceso — exit code no-cero
+  {
+    patron:      /exit.?code\s+[1-9]|non-?zero.?exit|exited.?with\s+[1-9]/i,
+    codigo:      'PROCESS_ERROR',
+    categoria:   'hook',
+    severidad:   'error',
+    recuperable: false,
+    sugerencia:  'El comando terminó con error. Ver el output de stderr para detalles.',
+  },
+  // Agente — fallo durante ejecución
+  {
+    patron:      /agent.+fail|subagent.+error|agent.+error/i,
+    codigo:      'AGENT_FAILED',
+    categoria:   'agente',
+    severidad:   'error',
+    recuperable: true,
+    sugerencia:  'El subagente falló. Revisar el prompt y los parámetros de invocación.',
+  },
+  // Seguridad — inyección detectada
+  {
+    patron:      /injection|prompt.?inject|malicious.?content/i,
+    codigo:      'SECURITY_BLOCKED',
+    categoria:   'hook',
+    severidad:   'fatal',
+    recuperable: false,
+    sugerencia:  'El sistema detectó un posible intento de inyección. Revisar el input antes de continuar.',
+  },
+  // Build — error de compilación
+  {
+    patron:      /SyntaxError|CompileError|build.?failed|compilation.?error/i,
+    codigo:      'BUILD_ERROR',
+    categoria:   'herramienta',
+    severidad:   'error',
+    recuperable: false,
+    sugerencia:  'Error de compilación. Revisar la sintaxis del archivo afectado.',
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Descripciones legibles
+// ---------------------------------------------------------------------------
+
+const DESCRIPCIONES = {
+  RATE_LIMIT:        'Límite de velocidad de la API alcanzado',
+  API_OVERLOADED:    'API temporalmente sobrecargada',
+  CONTEXT_OVERFLOW:  'Ventana de contexto saturada',
+  AUTH_FAILED:       'Autenticación fallida',
+  FORBIDDEN:         'Acceso prohibido al recurso',
+  NETWORK_ERROR:     'Error de red o conexión',
+  TIMEOUT:           'Tiempo de espera agotado',
+  NOT_FOUND:         'Recurso o módulo no encontrado',
+  PERMISSION_DENIED: 'Permiso denegado',
+  PARSE_ERROR:       'Error al parsear datos JSON',
+  PROCESS_ERROR:     'Proceso terminó con código de error',
+  AGENT_FAILED:      'El agente falló durante la ejecución',
+  SECURITY_BLOCKED:  'Operación bloqueada por seguridad',
+  BUILD_ERROR:       'Error de compilación o sintaxis',
+  UNKNOWN_ERROR:     'Error no reconocido',
+};
+
+// ---------------------------------------------------------------------------
+// API pública
+// ---------------------------------------------------------------------------
+
+/**
+ * Extrae el mensaje de texto de cualquier tipo de error.
+ *
+ * @param {unknown} error
+ * @returns {string}
+ */
+function extraerMensaje(error) {
+  if (error === null || error === undefined) return '(error sin mensaje)';
+  if (typeof error === 'string') return error;
+  if (error instanceof Error) return error.message;
+  if (typeof error === 'object') {
+    return String(error.message || error.msg || error.error || JSON.stringify(error).slice(0, 500));
+  }
+  return String(error);
+}
+
+/**
+ * Normaliza cualquier error en la estructura uniforme de swl-ses.
+ *
+ * @param {unknown} error      — El error a normalizar (Error, string, objeto, etc.)
+ * @param {object}  [opts]
+ * @param {string}  [opts.fuente='desconocida'] — Módulo o hook donde ocurrió
+ * @returns {NormalizedError}
+ *
+ * @typedef {object} NormalizedError
+ * @property {string}      codigo
+ * @property {string}      mensaje
+ * @property {string}      categoria
+ * @property {string}      severidad
+ * @property {boolean}     recuperable
+ * @property {string}      fuente
+ * @property {string}      detalle
+ * @property {string|null} sugerencia
+ */
+function normalizar(error, opts = {}) {
+  const fuente  = String(opts.fuente || 'desconocida');
+  const detalle = extraerMensaje(error);
+
+  // Buscar primer patrón coincidente
+  for (const p of PATRONES) {
+    if (p.patron.test(detalle)) {
+      return {
+        codigo:      p.codigo,
+        mensaje:     DESCRIPCIONES[p.codigo] || p.codigo,
+        categoria:   p.categoria,
+        severidad:   p.severidad,
+        recuperable: p.recuperable,
+        fuente,
+        detalle,
+        sugerencia:  p.sugerencia,
+      };
+    }
+  }
+
+  // Fallback — error desconocido
+  return {
+    codigo:      'UNKNOWN_ERROR',
+    mensaje:     DESCRIPCIONES.UNKNOWN_ERROR,
+    categoria:   'desconocido',
+    severidad:   'error',
+    recuperable: false,
+    fuente,
+    detalle,
+    sugerencia:  null,
+  };
+}
+
+/**
+ * Formatea un error normalizado como texto legible para logs o mensajes al usuario.
+ * Produce una línea principal + líneas de detalle y sugerencia si aplica.
+ *
+ * @param {NormalizedError} err
+ * @returns {string}
+ */
+function formatear(err) {
+  const iconos = { warning: '⚠', error: '✗', fatal: '✗✗' };
+  const icono      = iconos[err.severidad] || '?';
+  const recuperable = err.recuperable ? ' (recuperable)' : '';
+
+  let txt = `${icono} [${err.codigo}] ${err.mensaje}${recuperable}`;
+
+  if (err.fuente && err.fuente !== 'desconocida') {
+    txt += ` — ${err.fuente}`;
+  }
+  if (err.detalle && err.detalle !== err.mensaje && err.detalle !== '(error sin mensaje)') {
+    txt += `\n  Detalle: ${err.detalle.slice(0, 300)}`;
+  }
+  if (err.sugerencia) {
+    txt += `\n  Sugerencia: ${err.sugerencia}`;
+  }
+
+  return txt;
+}
+
+/**
+ * Convierte a JSON compacto para logging estructurado en JSONL.
+ *
+ * @param {NormalizedError} err
+ * @returns {string} Una línea JSON
+ */
+function formatearJSON(err) {
+  return JSON.stringify({
+    ts:          new Date().toISOString(),
+    codigo:      err.codigo,
+    categoria:   err.categoria,
+    severidad:   err.severidad,
+    recuperable: err.recuperable,
+    fuente:      err.fuente,
+    detalle:     err.detalle?.slice(0, 200),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { normalizar, extraerMensaje, formatear, formatearJSON };

package/hooks/lib/normalize-input.js

@@ -0,0 +1,65 @@
+'use strict';
+
+/**
+ * Normalize Input — Normalización anti-bypass para detección de seguridad.
+ *
+ * Previene evasión de patrones de detección mediante:
+ *   - Caracteres Unicode fullwidth (Ａ→A, ０→0)
+ *   - Secuencias ANSI escape (colores, movimiento de cursor)
+ *   - Null bytes (\x00)
+ *   - Caracteres de control (excepto \n y \t)
+ *
+ * Patrón adoptado de Hermes Agent (approval.py → _normalize_command_for_detection).
+ *
+ * @module hooks/lib/normalize-input
+ */
+
+/**
+ * Regex para secuencias ANSI escape.
+ *
+ * Cubre:
+ *   - CSI (Control Sequence Introducer): \x1B[ ... letra
+ *   - OSC (Operating System Command): \x1B] ... (BEL o ST)
+ *   - DCS (Device Control String): \x1BP ... ST
+ *   - 8-bit C1 control codes: \x80-\x9F
+ */
+const ANSI_ESCAPE_RE = /\x1B\[[0-9;]*[a-zA-Z]|\x1B\][^\x07\x1B]*(?:\x07|\x1B\\)|\x1BP[^\x1B]*\x1B\\|[\x80-\x9F]/g;
+
+/**
+ * Regex para caracteres de control (excepto newline \x0A y tab \x09).
+ */
+const CONTROL_CHARS_RE = /[\x01-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+
+/**
+ * Normaliza texto para detección de patrones de seguridad.
+ *
+ * Debe aplicarse ANTES de evaluar cualquier regex de detección
+ * (secretos, credenciales, comandos peligrosos, inyecciones de prompt).
+ *
+ * @param {string} text - Texto a normalizar.
+ * @returns {string} Texto normalizado.
+ */
+function normalizeForDetection(text) {
+  if (!text || typeof text !== 'string') return '';
+
+  let normalized = text;
+
+  // 1. Strip null bytes (técnica de bypass clásica)
+  normalized = normalized.replace(/\x00/g, '');
+
+  // 2. Strip ANSI escape sequences (ocultan contenido en terminales)
+  normalized = normalized.replace(ANSI_ESCAPE_RE, '');
+
+  // 3. Unicode NFKC normalization
+  //    - Fullwidth Latin → ASCII (Ａ→A, ０→0, ｒｍ→rm)
+  //    - Halfwidth Katakana → regular
+  //    - Compatibility decomposition + canonical composition
+  normalized = normalized.normalize('NFKC');
+
+  // 4. Strip caracteres de control (excepto newline y tab)
+  normalized = normalized.replace(CONTROL_CHARS_RE, '');
+
+  return normalized;
+}
+
+module.exports = { normalizeForDetection };