@saulwade/swl-ses 1.0.0

package/hooks/lib/context-builder.js

@@ -0,0 +1,430 @@
+'use strict';
+
+/**
+ * Context Builder — Ensambla contexto inteligente con presupuesto de tokens.
+ *
+ * Genera un bloque de contexto optimizado para inyectar al inicio de sesion.
+ * Respeta un presupuesto de tokens configurable y prioriza por relevancia.
+ *
+ * Secciones (en orden de prioridad):
+ *   1. Header: proyecto, modo activo, metricas
+ *   2. Instintos: patrones con alta confianza
+ *   3. Sesion anterior: resumen y archivos
+ *   4. Aprendizajes recientes: ultimos N aprendizajes
+ *   5. Footer: advertencias si se trunco contenido
+ *
+ * Token budget: default 2000 tokens (~8000 caracteres en espanol)
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const DEFAULT_TOKEN_BUDGET = 2500; // Recalibrado para Opus 4.7 (tokenizer 1.0-1.35x vs 4.6)
+const CHARS_POR_TOKEN      = 4; // Heuristica para espanol
+
+// ---------------------------------------------------------------------------
+// Snapshot congelado — Prefix Cache Optimization
+// ---------------------------------------------------------------------------
+// Patrón adoptado de Hermes Agent: el contexto se congela como snapshot al
+// inicio de sesión. Escrituras mid-session actualizan disco pero NO mutan
+// el contexto inyectado. Esto preserva el prefix cache de Anthropic (~10x ahorro).
+
+let _frozenSnapshot  = null;
+let _frozenSessionId = null;
+
+// ---------------------------------------------------------------------------
+// Utilidades
+// ---------------------------------------------------------------------------
+
+/**
+ * Estima tokens de un texto usando la heuristica de 4 chars/token para espanol.
+ *
+ * @param {string} texto
+ * @returns {number}
+ */
+function estimarTokens(texto) {
+  return Math.ceil((texto || '').length / CHARS_POR_TOKEN);
+}
+
+// ---------------------------------------------------------------------------
+// Constructores de secciones
+// ---------------------------------------------------------------------------
+
+/**
+ * Seccion 1 — Header con nombre del proyecto y modo activo.
+ *
+ * Lee el modo desde .planning/CONTEXTO.md si existe.
+ * Fallback a 'dev' si el archivo no existe o no tiene el campo.
+ *
+ * @param {string} baseDir
+ * @returns {string}
+ */
+function buildHeader(baseDir) {
+  const ctxPath = path.join(baseDir, '.planning', 'CONTEXTO.md');
+  let modo = 'dev';
+  try {
+    const contenido = fs.readFileSync(ctxPath, 'utf8');
+    const match = contenido.match(/\*\*Modo\*\*:\s*(\w+)/);
+    if (match) modo = match[1];
+  } catch (_) {}
+
+  const projectName = path.basename(baseDir);
+  return `[SWL Context] Proyecto: ${projectName} | Modo: ${modo}`;
+}
+
+/**
+ * Seccion 2 — Instintos activos con confianza >= 0.7.
+ *
+ * Lee instintos/proyecto.yaml con un regex simple (sin dependencia de yaml parser).
+ * Solo incluye instintos con status 'active'. Ordena por confianza descendente.
+ *
+ * @param {string} baseDir
+ * @param {number} max - Numero maximo de instintos a incluir.
+ * @returns {string} Bloque de texto, o cadena vacia si no hay instintos.
+ */
+function buildInstintos(baseDir, max) {
+  const instPath = path.join(baseDir, 'instintos', 'proyecto.yaml');
+  if (!fs.existsSync(instPath)) return '';
+
+  try {
+    const contenido = fs.readFileSync(instPath, 'utf8');
+    const instintos  = [];
+
+    // Regex que captura pattern, confidence y status en un bloque YAML de instinto
+    const regex = /pattern:\s*"([^"]+)"[\s\S]*?confidence:\s*([\d.]+)[\s\S]*?status:\s*(\w+)/g;
+    let match;
+    while ((match = regex.exec(contenido)) !== null) {
+      const confidence = parseFloat(match[2]);
+      const status     = match[3];
+      if (status === 'active' && confidence >= 0.7) {
+        instintos.push({ pattern: match[1], confidence });
+      }
+    }
+
+    if (instintos.length === 0) return '';
+
+    // Ordenar por confianza descendente y limitar
+    const seleccionados = instintos
+      .sort((a, b) => b.confidence - a.confidence)
+      .slice(0, max);
+
+    const lineas = ['Instintos activos:'];
+    for (const inst of seleccionados) {
+      lineas.push(`  - ${inst.pattern} (${(inst.confidence * 100).toFixed(0)}%)`);
+    }
+    return lineas.join('\n');
+  } catch (_) {
+    return '';
+  }
+}
+
+/**
+ * Seccion 3 — Resumen de la sesion anterior.
+ *
+ * Lee .planning/sessions/latest.json para obtener la ruta al JSON de sesion.
+ * No incluye sesiones activas ni sesiones con menos de 3 tool calls (muy cortas).
+ *
+ * @param {string} baseDir
+ * @returns {string} Bloque de texto, o cadena vacia si no hay sesion util.
+ */
+function buildSesionAnterior(baseDir) {
+  const latestPath = path.join(baseDir, '.planning', 'sessions', 'latest.json');
+  if (!fs.existsSync(latestPath)) return '';
+
+  try {
+    const { path: sessionPath } = JSON.parse(fs.readFileSync(latestPath, 'utf8'));
+    if (!sessionPath || !fs.existsSync(sessionPath)) return '';
+
+    const sesion = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));
+
+    // Filtrar sesiones activas o demasiado cortas para aportar contexto util
+    if (sesion.status === 'active' || sesion.toolCalls < 3) return '';
+
+    const lineas = [`Sesion anterior (${sesion.id}):`];
+    if (sesion.summary) {
+      lineas.push(`  Resumen: ${sesion.summary.slice(0, 200)}`);
+    }
+    if (sesion.filesChanged && sesion.filesChanged.length > 0) {
+      lineas.push(`  Archivos: ${sesion.filesChanged.slice(0, 5).join(', ')}`);
+    }
+    return lineas.join('\n');
+  } catch (_) {
+    return '';
+  }
+}
+
+/**
+ * Seccion 4 — Aprendizajes recientes desde .planning/APRENDIZAJES.md.
+ *
+ * Toma los ultimos `max` bloques H2 del archivo y los incluye como titulos.
+ * Respeta el presupuesto restante: deja de agregar si se agotaria.
+ *
+ * @param {string} baseDir
+ * @param {number} max           - Numero maximo de aprendizajes a incluir.
+ * @param {number} budgetRestante - Tokens disponibles para esta seccion.
+ * @returns {string} Bloque de texto, o cadena vacia si no hay aprendizajes.
+ */
+function buildAprendizajes(baseDir, max, budgetRestante) {
+  const aprendizajesPath = path.join(baseDir, '.planning', 'APRENDIZAJES.md');
+  if (!fs.existsSync(aprendizajesPath)) return '';
+
+  try {
+    const contenido = fs.readFileSync(aprendizajesPath, 'utf8');
+
+    // Dividir por secciones H2 y filtrar el encabezado del documento
+    const bloques = contenido.split(/^## /m).filter(Boolean);
+    if (bloques.length === 0) return '';
+
+    // Tomar los ultimos N bloques (mas recientes) en orden descendente
+    const recientes          = bloques.slice(-max).reverse();
+    const lineas             = ['Aprendizajes recientes:'];
+    let tokensAcumulados     = estimarTokens(lineas[0]);
+
+    for (const bloque of recientes) {
+      const titulo    = bloque.split('\n')[0].trim();
+      const linea     = `  - ${titulo.slice(0, 100)}`;
+      const lineaToks = estimarTokens(linea);
+
+      // Respetar el budget restante de forma estricta
+      if (tokensAcumulados + lineaToks > budgetRestante) break;
+
+      lineas.push(linea);
+      tokensAcumulados += lineaToks;
+    }
+
+    return lineas.length > 1 ? lineas.join('\n') : '';
+  } catch (_) {
+    return '';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// API publica
+// ---------------------------------------------------------------------------
+
+/**
+ * Construye el bloque de contexto respetando el presupuesto de tokens.
+ *
+ * Las secciones se ensamblan en orden de prioridad decreciente. Si al agregar
+ * una seccion el presupuesto se agotaria, esa seccion se omite y se registra
+ * en `seccionesTruncadas`.
+ *
+ * @param {string} baseDir - Directorio raiz del proyecto.
+ * @param {object} [opciones]
+ * @param {number} [opciones.tokenBudget=2500]    - Presupuesto de tokens (default 2500 — recalibrado para Opus 4.7).
+ * @param {number} [opciones.maxAprendizajes=5]   - Max aprendizajes a incluir.
+ * @param {number} [opciones.maxInstintos=5]       - Max instintos a incluir.
+ * @returns {{ contexto: string, tokensUsados: number, seccionesTruncadas: string[] }}
+ */
+/**
+ * Construye un resumen de metadatos de cada sección sin incluir el contenido
+ * completo. Patrón inspirado en Zhang et al. 2026 ("Recursive Language Models",
+ * arXiv:2512.24601v2, §4.1 + Algoritmo 1) donde la raíz del REPL solo recibe
+ * metadata de la información disponible (cómo accederla), no la información
+ * en sí. El subagente decide si cargar el contenido completo según la tarea.
+ *
+ * Útil para tareas donde el agente padre/orquestador solo necesita saber
+ * "qué información hay disponible" antes de delegar, no leerla toda.
+ *
+ * @param {string} baseDir
+ * @param {object} opciones
+ * @returns {string}
+ */
+function buildMetadataResumen(baseDir, opciones = {}) {
+  const partes = [];
+  const path = require('path');
+  const fs = require('fs');
+
+  partes.push('## Contexto disponible (metadata-first)');
+  partes.push('');
+  partes.push('Información del proyecto disponible para consulta bajo demanda:');
+  partes.push('');
+
+  // Header siempre como metadata, no contenido
+  const claudeMd = path.join(baseDir, 'CLAUDE.md');
+  if (fs.existsSync(claudeMd)) {
+    try {
+      const lineas = fs.readFileSync(claudeMd, 'utf8').split('\n').length;
+      partes.push(`- **CLAUDE.md** (${lineas} líneas) — reglas y convenciones del proyecto. Leer si la tarea toca arquitectura, convenciones o decisiones globales.`);
+    } catch { /* ignore */ }
+  }
+
+  // Instintos: contar sin cargar
+  const instintosDir = path.join(baseDir, 'instintos');
+  if (fs.existsSync(instintosDir)) {
+    try {
+      const archivos = fs.readdirSync(instintosDir).filter(f => f.endsWith('.yaml'));
+      if (archivos.length > 0) {
+        partes.push(`- **instintos/** (${archivos.length} archivos YAML) — patrones aprendidos. Cargar con \`Skill("perfil-usuario")\` o lectura directa.`);
+      }
+    } catch { /* ignore */ }
+  }
+
+  // APRENDIZAJES.md: contar entradas sin cargar contenido
+  const aprendizajes = path.join(baseDir, '.planning', 'APRENDIZAJES.md');
+  if (fs.existsSync(aprendizajes)) {
+    try {
+      const contenido = fs.readFileSync(aprendizajes, 'utf8');
+      const numEntradas = (contenido.match(/^## \[\d{4}/gm) || []).length;
+      partes.push(`- **.planning/APRENDIZAJES.md** (${numEntradas} entradas) — historial curado. Buscar con \`Skill("memoria-busqueda")\` por keyword.`);
+    } catch { /* ignore */ }
+  }
+
+  // Sesión anterior
+  const compactacion = path.join(baseDir, '.planning', 'COMPACTACION.md');
+  if (fs.existsSync(compactacion)) {
+    try {
+      const lineas = fs.readFileSync(compactacion, 'utf8').split('\n').length;
+      partes.push(`- **.planning/COMPACTACION.md** (${lineas} líneas) — snapshot de la sesión previa. Leer si se retoma trabajo en curso.`);
+    } catch { /* ignore */ }
+  }
+
+  // Estado actual
+  const estado = path.join(baseDir, '.planning', 'ESTADO.md');
+  if (fs.existsSync(estado)) {
+    partes.push(`- **.planning/ESTADO.md** — estado operativo del sistema. Leer si la tarea requiere conocer la versión actual o última actividad.`);
+  }
+
+  partes.push('');
+  partes.push('**Estrategia recomendada**: cargar solo los archivos relevantes a la tarea. La información completa NO está pre-inyectada para preservar tokens.');
+
+  return partes.join('\n');
+}
+
+function buildContext(baseDir, opciones = {}) {
+  const budget         = opciones.tokenBudget    || DEFAULT_TOKEN_BUDGET;
+  const maxAprendizajes = opciones.maxAprendizajes || 5;
+  const maxInstintos    = opciones.maxInstintos    || 5;
+  const metadataOnly    = opciones.metadataOnly === true;
+
+  // ── Modo metadata-first (Zhang et al. 2026, §4.1) ─────────────────────────
+  // Inyecta SOLO metadata sobre el contexto disponible, no su contenido.
+  // El agente padre decide qué cargar según la tarea. Útil para tareas de
+  // exploración/orquestación en codebases grandes donde el contenido
+  // completo saturaría el contexto sin aportar información necesaria.
+  if (metadataOnly) {
+    const resumen = buildMetadataResumen(baseDir, opciones);
+    return {
+      contexto:           resumen,
+      tokensUsados:       estimarTokens(resumen),
+      seccionesTruncadas: [],
+      modo:               'metadata-only',
+    };
+  }
+
+  let tokensUsados      = 0;
+  const secciones       = [];
+  const truncadas       = [];
+
+  // --- Seccion 1: Header (siempre incluido si cabe) ---
+  const header       = buildHeader(baseDir);
+  const headerTokens = estimarTokens(header);
+  if (tokensUsados + headerTokens <= budget) {
+    secciones.push(header);
+    tokensUsados += headerTokens;
+  }
+
+  // --- Seccion 2: Instintos activos ---
+  const instintos       = buildInstintos(baseDir, maxInstintos);
+  const instintosTokens = estimarTokens(instintos);
+  if (instintos && tokensUsados + instintosTokens <= budget) {
+    secciones.push(instintos);
+    tokensUsados += instintosTokens;
+  } else if (instintos) {
+    truncadas.push('instintos');
+  }
+
+  // --- Seccion 3: Sesion anterior ---
+  const sesion       = buildSesionAnterior(baseDir);
+  const sesionTokens = estimarTokens(sesion);
+  if (sesion && tokensUsados + sesionTokens <= budget) {
+    secciones.push(sesion);
+    tokensUsados += sesionTokens;
+  } else if (sesion) {
+    truncadas.push('sesion anterior');
+  }
+
+  // --- Seccion 4: Aprendizajes recientes ---
+  // Pasa el budget restante para que buildAprendizajes pueda truncar internamente
+  const budgetRestante    = budget - tokensUsados;
+  const aprendizajes      = buildAprendizajes(baseDir, maxAprendizajes, budgetRestante);
+  const aprendizajesTokens = estimarTokens(aprendizajes);
+  if (aprendizajes && tokensUsados + aprendizajesTokens <= budget) {
+    secciones.push(aprendizajes);
+    tokensUsados += aprendizajesTokens;
+  } else if (aprendizajes) {
+    truncadas.push('aprendizajes');
+  }
+
+  // --- Seccion 5: Footer (solo si se trunco algo) ---
+  if (truncadas.length > 0) {
+    const footer = `\n[Contexto truncado — secciones omitidas: ${truncadas.join(', ')}. Budget: ${budget} tokens]`;
+    secciones.push(footer);
+    tokensUsados += estimarTokens(footer);
+  }
+
+  return {
+    contexto:           secciones.join('\n'),
+    tokensUsados,
+    seccionesTruncadas: truncadas,
+    modo:               'completo',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Snapshot congelado — API pública
+// ---------------------------------------------------------------------------
+
+/**
+ * Obtiene o construye un snapshot congelado de contexto para la sesión.
+ *
+ * Si ya existe un snapshot para el sessionId dado, lo retorna sin recalcular.
+ * Esto maximiza el hit rate del prefix cache de Anthropic.
+ *
+ * @param {string} baseDir   - Directorio raíz del proyecto.
+ * @param {string} sessionId - ID de la sesión activa.
+ * @param {object} [opciones] - Mismas opciones que buildContext().
+ * @returns {{ contexto: string, tokensUsados: number, seccionesTruncadas: string[], frozen: boolean }}
+ */
+function getOrBuildSnapshot(baseDir, sessionId, opciones = {}) {
+  if (_frozenSnapshot && _frozenSessionId === sessionId) {
+    return { ..._frozenSnapshot, frozen: true };
+  }
+
+  const contexto = buildContext(baseDir, opciones);
+  _frozenSnapshot  = Object.freeze({ ...contexto });
+  _frozenSessionId = sessionId;
+
+  return { ...contexto, frozen: false };
+}
+
+/**
+ * Invalida el snapshot congelado.
+ *
+ * Usar solo cuando se necesita recalcular el contexto explícitamente:
+ *   - Cambio de modo con /swl:contexto
+ *   - Compresión de contexto manual
+ *   - Nueva sesión
+ */
+function invalidateSnapshot() {
+  _frozenSnapshot  = null;
+  _frozenSessionId = null;
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  buildContext,
+  getOrBuildSnapshot,
+  invalidateSnapshot,
+  estimarTokens,
+  DEFAULT_TOKEN_BUDGET,
+  // Exportar constructores de secciones para tests unitarios
+  buildHeader,
+  buildInstintos,
+  buildSesionAnterior,
+  buildAprendizajes,
+  buildMetadataResumen,
+};