@saulwade/swl-ses 1.0.0

package/hooks/sugerir-regenerar-inventario.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: sugerir-regenerar-inventario.js
+ * Tipo: PostToolUse  (aplica a: Write, Edit, MultiEdit)
+ *
+ * Cuando el agente edita o crea un componente registrado en INVENTARIO.md
+ * (agentes, habilidades, comandos, hooks o reglas), sugiere — sin bloquear —
+ * regenerar el inventario antes del próximo commit.
+ *
+ * Motivado por el drift recurrente detectado el 2026-04-29: tras agregar el
+ * skill `harness-claude-code` el inventario quedó stale en 5 archivos canónicos
+ * porque nadie regeneró `INVENTARIO.md` después de la edición. La regeneración
+ * es 1 comando (`node scripts/generar-inventario.js`) pero es fácil olvidarla.
+ *
+ * Cooldown: una vez por sesión por carpeta afectada para no spammear cuando
+ * el agente edita docenas de archivos seguidos. Estado persistente en
+ * `.planning/inventario-aviso-state.json`.
+ *
+ * Resultado:
+ *   - Edición sobre carpeta inventariada y sin cooldown → sugerencia en stdout (exit 0)
+ *   - Edición sobre carpeta no inventariada            → sin output (exit 0)
+ *   - Error interno                                    → sin output (nunca bloquear)
+ *
+ * Activo por defecto. Para silenciar: SWL_SUGERIR_REGEN_INVENTARIO=0.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Carpetas cuyo cambio invalida los contadores de INVENTARIO.md
+const CARPETAS_INVENTARIADAS = [
+  { ruta: 'agentes/',      etiqueta: 'agentes' },
+  { ruta: 'habilidades/',  etiqueta: 'habilidades' },
+  { ruta: 'comandos/swl/', etiqueta: 'comandos' },
+  { ruta: 'hooks/',        etiqueta: 'hooks',  excluir: ['hooks/lib/'] },
+  { ruta: 'reglas/',       etiqueta: 'reglas' },
+];
+
+const STATE_FILE = path.join(process.cwd(), '.planning', 'inventario-aviso-state.json');
+const COOLDOWN_MS = 30 * 60 * 1000; // 30 min
+
+function normalizarSeparadores(p) {
+  return String(p).replace(/\\/g, '/');
+}
+
+function detectarCarpeta(rutaRaw) {
+  if (!rutaRaw) return null;
+  let normalizada = normalizarSeparadores(rutaRaw);
+
+  // Solo nos interesan rutas relativas al proyecto. Si es absoluta, intentamos
+  // hacerla relativa al CWD actual.
+  if (path.isAbsolute(normalizada)) {
+    const cwd = normalizarSeparadores(process.cwd());
+    if (normalizada.toLowerCase().startsWith(cwd.toLowerCase())) {
+      normalizada = normalizada.slice(cwd.length).replace(/^\/+/, '');
+    } else {
+      return null;
+    }
+  } else {
+    normalizada = normalizada.replace(/^\.\//, '');
+  }
+
+  for (const c of CARPETAS_INVENTARIADAS) {
+    if (normalizada.startsWith(c.ruta)) {
+      if (c.excluir && c.excluir.some(ex => normalizada.startsWith(ex))) continue;
+      return c.etiqueta;
+    }
+  }
+  return null;
+}
+
+function leerEstado() {
+  try {
+    return JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function escribirEstado(estado) {
+  try {
+    fs.mkdirSync(path.dirname(STATE_FILE), { recursive: true });
+    const tmp = STATE_FILE + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(estado, null, 2), 'utf8');
+    fs.renameSync(tmp, STATE_FILE);
+  } catch {
+    // Falla silenciosa — el cooldown no es crítico
+  }
+}
+
+function dentroDeCooldown(estado, etiqueta) {
+  const ultima = estado[etiqueta];
+  if (!ultima) return false;
+  return Date.now() - ultima < COOLDOWN_MS;
+}
+
+function marcarAviso(estado, etiqueta) {
+  estado[etiqueta] = Date.now();
+  escribirEstado(estado);
+}
+
+function construirMensaje(etiqueta) {
+  return (
+    '\n[swl-ses] Tocaste un archivo en `' + etiqueta + '/` — los contadores ' +
+    'de INVENTARIO.md pueden quedar stale.\n' +
+    '   Antes del próximo commit, ejecuta:\n' +
+    '     node scripts/generar-inventario.js\n' +
+    '   y verifica con:\n' +
+    '     node scripts/verificar-release.js\n' +
+    '   (silenciar con SWL_SUGERIR_REGEN_INVENTARIO=0)\n'
+  );
+}
+
+function extraerRuta(toolInput) {
+  if (!toolInput || typeof toolInput !== 'object') return null;
+  return (
+    toolInput.file_path ||
+    toolInput.path ||
+    toolInput.notebook_path ||
+    null
+  );
+}
+
+function ejecutarComoHook() {
+  let inputRaw = '';
+
+  process.stdin.on('data', chunk => { inputRaw += chunk; });
+
+  process.stdin.on('end', () => {
+    try {
+      if (process.env.SWL_SUGERIR_REGEN_INVENTARIO === '0') return;
+
+      const data = JSON.parse(inputRaw || '{}');
+      const toolName = String(data.tool_name || data.tool?.name || '');
+      const toolInput = data.tool_input || data.tool?.input || {};
+
+      if (!['Write', 'Edit', 'MultiEdit'].includes(toolName)) return;
+
+      const ruta = extraerRuta(toolInput);
+      if (!ruta) return;
+
+      const etiqueta = detectarCarpeta(ruta);
+      if (!etiqueta) return;
+
+      const estado = leerEstado();
+      if (dentroDeCooldown(estado, etiqueta)) return;
+
+      process.stdout.write(construirMensaje(etiqueta));
+      marcarAviso(estado, etiqueta);
+    } catch {
+      // Errores internos nunca bloquean
+    }
+  });
+}
+
+// Solo escuchar stdin cuando se ejecuta como entrypoint (no al importar para tests)
+if (require.main === module) {
+  ejecutarComoHook();
+}
+
+// Para tests unitarios
+module.exports = {
+  CARPETAS_INVENTARIADAS,
+  detectarCarpeta,
+  construirMensaje,
+  dentroDeCooldown,
+  COOLDOWN_MS,
+};

package/hooks/telemetria-agentes.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: telemetria-agentes.js
+ * Tipo: PostToolUse + PostToolUseFailure (aplica a: Agent, Skill)
+ *
+ * Registra una traza OTLP-lite por cada invocación de agente SWL o skill.
+ * Captura: nombre del agente/skill, tipo, longitud de prompt, modelo, estado (OK/ERROR).
+ * En PostToolUseFailure, registra el error con estado FAILURE y el mensaje de fallo.
+ *
+ * Almacena en .planning/traces/YYYY-MM-DD.jsonl via otlp-exporter.js.
+ * Exporta a OTLP_ENDPOINT si la variable de entorno está definida.
+ *
+ * El hook nunca bloquea (siempre exit 0).
+ * Async: true — corre en background sin afectar la respuesta del modelo.
+ */
+
+const { registrar } = require('./lib/otlp-exporter');
+
+// Importar esquema de spans con guard de robustez — el hook no debe fallar
+// si el módulo aún no existe en instalaciones anteriores del sistema.
+let spanSchema = null;
+try {
+  spanSchema = require('../scripts/lib/span-schema');
+} catch (_) {
+  // Módulo no disponible — continuar sin tipado de span
+}
+
+const CWD = process.cwd();
+
+// ---------------------------------------------------------------------------
+// Mapping de eventos a tipos de span
+// ---------------------------------------------------------------------------
+
+/**
+ * Determina el tipo de span correspondiente al evento registrado.
+ * Utiliza la taxonomía de SPAN_TYPES cuando el módulo span-schema está disponible.
+ *
+ * @param {string} toolName   - Nombre de la herramienta ('Agent' | 'Skill').
+ * @param {object} input      - Payload de entrada de la herramienta.
+ * @param {string} [override] - Tipo explícito (para casos especiales).
+ * @returns {string|null} Tipo de span o null si span-schema no está cargado.
+ */
+function resolverTipoSpan(toolName, input, override) {
+  if (!spanSchema) return null;
+
+  const { SPAN_TYPES } = spanSchema;
+
+  if (override && spanSchema.esTipoSpanValido(override)) return override;
+
+  if (toolName === 'Skill') return SPAN_TYPES.FUNCTION;
+
+  if (toolName === 'Agent') {
+    const tipo = String(input.subagent_type || '').toLowerCase();
+    // Detectar handoff explícito en la descripción o tipo del subagente
+    if (/handoff|delegac|traspaso/.test(tipo)) return SPAN_TYPES.HANDOFF;
+    // Detectar llamadas LLM directas
+    if (/generation|llm|model/.test(tipo))      return SPAN_TYPES.GENERATION;
+    // Por defecto, un subagente es un span de tipo agent
+    return SPAN_TYPES.AGENT;
+  }
+
+  return SPAN_TYPES.CUSTOM;
+}
+
+// ---------------------------------------------------------------------------
+// Extracción de atributos de la invocación de agente
+// ---------------------------------------------------------------------------
+
+/**
+ * Determina si el resultado del agente indica un error.
+ * Busca keywords de fallo en la representación string del resultado.
+ *
+ * @param {any} result
+ * @returns {boolean}
+ */
+function detectarError(result) {
+  const str = typeof result === 'string' ? result : JSON.stringify(result || '');
+  return /\berror\b|\bfailed\b|\bexception\b|\btraceback\b|\baborte?d?\b/i.test(str);
+}
+
+/**
+ * Trunca un string a maxLen caracteres con elipsis.
+ * @param {string} str
+ * @param {number} maxLen
+ * @returns {string}
+ */
+function truncar(str, maxLen) {
+  const s = String(str || '');
+  return s.length > maxLen ? s.slice(0, maxLen) + '…' : s;
+}
+
+// ---------------------------------------------------------------------------
+// Entrypoint
+// ---------------------------------------------------------------------------
+
+let inputRaw = '';
+
+process.stdin.on('data', chunk => { inputRaw += chunk; });
+
+process.stdin.on('end', () => {
+  try {
+    const data     = JSON.parse(inputRaw);
+    const toolName = String(data.tool_name || data.tool?.name || '');
+
+    // Solo procesar invocaciones de agentes y skills
+    if (toolName !== 'Agent' && toolName !== 'Skill') return;
+
+    const input     = data.tool_input  || {};
+    const result    = data.tool_result || {};
+    const sessionId = String(data.session_id || '');
+    // PostToolUseFailure incluye error_message en el payload
+    const esFailure = Boolean(data.error_message || data.error);
+
+    if (toolName === 'Agent') {
+      const subagentType = String(input.subagent_type || 'general-purpose');
+      const descripcion  = truncar(input.description  || '', 120);
+      const promptLen    = String(input.prompt        || '').length;
+      const modelo       = String(input.model         || data.model || '');
+      const estado       = esFailure ? 'FAILURE'
+                         : detectarError(result) ? 'ERROR' : 'OK';
+
+      const tipoSpan = resolverTipoSpan('Agent', input);
+
+      const attrs = {
+        subagent_type: subagentType,
+        descripcion,
+        prompt_length: promptLen,
+        modelo,
+        session_id:    sessionId,
+      };
+      // Agregar span_type si el módulo está disponible (campo nuevo, no rompe formato)
+      if (tipoSpan) attrs.span_type = tipoSpan;
+      if (esFailure) {
+        attrs.error_message = truncar(data.error_message || data.error || '', 200);
+      }
+
+      registrar(CWD, `agent:${subagentType}`, attrs, estado);
+    }
+
+    if (toolName === 'Skill') {
+      const skillName = String(input.skill || input.name || 'unknown');
+      const skillArgs = truncar(input.args || '', 80);
+      const estado    = esFailure ? 'FAILURE'
+                       : detectarError(result) ? 'ERROR' : 'OK';
+
+      const tipoSpanSkill = resolverTipoSpan('Skill', input);
+
+      const attrs = {
+        skill_name: skillName,
+        args:       skillArgs,
+        session_id: sessionId,
+      };
+      // Agregar span_type si el módulo está disponible (campo nuevo, no rompe formato)
+      if (tipoSpanSkill) attrs.span_type = tipoSpanSkill;
+      if (esFailure) {
+        attrs.error_message = truncar(data.error_message || data.error || '', 200);
+      }
+
+      registrar(CWD, `skill:${skillName}`, attrs, estado);
+    }
+
+  } catch (_) {
+    // Silencioso — nunca interrumpir la sesión por fallos del hook
+  }
+});