@saulwade/swl-ses 1.5.1 → 1.6.0

package/hooks/lib/error-classifier.js

@@ -1,308 +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,
-};
+'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,
+};