@saulwade/swl-ses 1.0.0

package/hooks/lib/usage-model.js

@@ -0,0 +1,183 @@
+'use strict';
+
+/**
+ * Modelo de uso (Usage) con tracking per-request.
+ *
+ * Portado desde openai-agents-python / src/agents/usage.py (MIT).
+ * Traducción a JS puro sin dependencias externas.
+ *
+ * Permite acumular tokens reales expuestos por Claude Code en PostToolUse
+ * y llevar un historial por llamada en `request_usage_entries`, lo que
+ * mejora la precisión del ciclo de auto-evolución respecto a la estimación
+ * heurística actual de tracking-costos.js.
+ *
+ * @module hooks/lib/usage-model
+ */
+
+// ---------------------------------------------------------------------------
+// Factory principal
+// ---------------------------------------------------------------------------
+
+/**
+ * Crea una nueva instancia de Usage con contadores en cero.
+ *
+ * Campos del objeto retornado:
+ *   - requests           {number} Total de solicitudes al LLM.
+ *   - input_tokens       {number} Total de tokens de entrada acumulados.
+ *   - output_tokens      {number} Total de tokens de salida acumulados.
+ *   - total_tokens       {number} Suma de input + output acumulados.
+ *   - cached_tokens      {number} Tokens servidos desde caché (sub-campo de input).
+ *   - reasoning_tokens   {number} Tokens de razonamiento interno (sub-campo de output).
+ *   - request_usage_entries {Array} Historial por solicitud individual.
+ *
+ * @returns {UsageInstance} Instancia de Usage con métodos add, addEntrada y serialize.
+ *
+ * @example
+ * const uso = crearUsage();
+ * uso.addEntrada({ inputTokens: 100, outputTokens: 50, modelo: 'claude-sonnet-4-6' });
+ * uso.serialize(); // → { requests: 1, input_tokens: 100, ... }
+ */
+function crearUsage() {
+  const instancia = {
+    requests:               0,
+    input_tokens:           0,
+    output_tokens:          0,
+    total_tokens:           0,
+    cached_tokens:          0,
+    reasoning_tokens:       0,
+    request_usage_entries:  [],
+
+    /**
+     * Acumula otro objeto Usage en este, sumando todos sus campos.
+     * También combina los request_usage_entries del otro.
+     *
+     * @param {object} otro - Objeto Usage (creado con crearUsage o fromJSON).
+     * @returns {void}
+     */
+    add(otro) {
+      if (!otro || typeof otro !== 'object') return;
+
+      this.requests         += (typeof otro.requests         === 'number' ? otro.requests         : 0);
+      this.input_tokens     += (typeof otro.input_tokens     === 'number' ? otro.input_tokens     : 0);
+      this.output_tokens    += (typeof otro.output_tokens    === 'number' ? otro.output_tokens    : 0);
+      this.total_tokens     += (typeof otro.total_tokens     === 'number' ? otro.total_tokens     : 0);
+      this.cached_tokens    += (typeof otro.cached_tokens    === 'number' ? otro.cached_tokens    : 0);
+      this.reasoning_tokens += (typeof otro.reasoning_tokens === 'number' ? otro.reasoning_tokens : 0);
+
+      // Combinar historial de entradas
+      if (Array.isArray(otro.request_usage_entries)) {
+        this.request_usage_entries.push(...otro.request_usage_entries);
+      }
+    },
+
+    /**
+     * Registra una entrada individual de uso y actualiza los totales acumulados.
+     * Si los datos de tokens son positivos, se cuenta como una nueva solicitud.
+     *
+     * @param {object} entrada - Datos de la solicitud individual.
+     * @param {number} [entrada.inputTokens=0]     - Tokens de entrada de esta solicitud.
+     * @param {number} [entrada.outputTokens=0]    - Tokens de salida de esta solicitud.
+     * @param {number} [entrada.cachedTokens=0]    - Tokens de entrada servidos desde caché.
+     * @param {number} [entrada.reasoningTokens=0] - Tokens de razonamiento interno.
+     * @param {string} [entrada.modelo]            - Identificador del modelo usado.
+     * @param {string} [entrada.timestamp]         - ISO timestamp de la solicitud.
+     * @returns {void}
+     */
+    addEntrada({
+      inputTokens     = 0,
+      outputTokens    = 0,
+      cachedTokens    = 0,
+      reasoningTokens = 0,
+      modelo          = '',
+      timestamp,
+    } = {}) {
+      const input    = Math.max(0, Number(inputTokens)     || 0);
+      const output   = Math.max(0, Number(outputTokens)    || 0);
+      const cached   = Math.max(0, Number(cachedTokens)    || 0);
+      const reason   = Math.max(0, Number(reasoningTokens) || 0);
+      const total    = input + output;
+
+      // Solo registrar si hay actividad real
+      if (total <= 0 && cached <= 0 && reason <= 0) return;
+
+      this.requests         += 1;
+      this.input_tokens     += input;
+      this.output_tokens    += output;
+      this.total_tokens     += total;
+      this.cached_tokens    += cached;
+      this.reasoning_tokens += reason;
+
+      this.request_usage_entries.push({
+        input_tokens:     input,
+        output_tokens:    output,
+        total_tokens:     total,
+        cached_tokens:    cached,
+        reasoning_tokens: reason,
+        modelo:           String(modelo || ''),
+        timestamp:        timestamp || new Date().toISOString(),
+      });
+    },
+
+    /**
+     * Serializa el Usage como objeto plano JSON-seguro.
+     *
+     * @returns {{ requests: number, input_tokens: number, output_tokens: number,
+     *             total_tokens: number, cached_tokens: number, reasoning_tokens: number,
+     *             request_usage_entries: Array }}
+     */
+    serialize() {
+      return {
+        requests:               this.requests,
+        input_tokens:           this.input_tokens,
+        output_tokens:          this.output_tokens,
+        total_tokens:           this.total_tokens,
+        cached_tokens:          this.cached_tokens,
+        reasoning_tokens:       this.reasoning_tokens,
+        request_usage_entries:  this.request_usage_entries.map(e => ({ ...e })),
+      };
+    },
+  };
+
+  return instancia;
+}
+
+// ---------------------------------------------------------------------------
+// Función estática de deserialización
+// ---------------------------------------------------------------------------
+
+/**
+ * Reconstruye un Usage desde un objeto plano (ej. leído de JSON).
+ * Los campos faltantes se inicializan en cero.
+ * Las entradas en request_usage_entries se copian sin mutación.
+ *
+ * @param {object} obj - Objeto plano previamente serializado con serialize().
+ * @returns {UsageInstance} Instancia de Usage reconstruida.
+ *
+ * @example
+ * const raw = JSON.parse(fs.readFileSync('usage.json'));
+ * const uso = fromJSON(raw);
+ * uso.addEntrada({ inputTokens: 200, outputTokens: 80 });
+ */
+function fromJSON(obj) {
+  const uso = crearUsage();
+  if (!obj || typeof obj !== 'object') return uso;
+
+  uso.requests         = typeof obj.requests         === 'number' ? obj.requests         : 0;
+  uso.input_tokens     = typeof obj.input_tokens     === 'number' ? obj.input_tokens     : 0;
+  uso.output_tokens    = typeof obj.output_tokens    === 'number' ? obj.output_tokens    : 0;
+  uso.total_tokens     = typeof obj.total_tokens     === 'number' ? obj.total_tokens     : 0;
+  uso.cached_tokens    = typeof obj.cached_tokens    === 'number' ? obj.cached_tokens    : 0;
+  uso.reasoning_tokens = typeof obj.reasoning_tokens === 'number' ? obj.reasoning_tokens : 0;
+
+  if (Array.isArray(obj.request_usage_entries)) {
+    uso.request_usage_entries = obj.request_usage_entries.map(e => ({ ...e }));
+  }
+
+  return uso;
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { crearUsage, fromJSON };

package/hooks/lib/variable-resolver.js

@@ -0,0 +1,230 @@
+'use strict';
+
+/**
+ * variable-resolver.js — Resolución de referencias dinámicas en prompts y planes.
+ *
+ * Inspirado en el Variable Resolution Engine de Sim Studio (simstudioai/sim).
+ * Resuelve referencias {{agente.output.campo}} contra el estado de ejecución
+ * persisted en .planning/execution-state.json, eliminando la construcción
+ * manual de prompts que dependan de outputs de agentes previos.
+ *
+ * Sintaxis soportada:
+ *   {{planificador-swl.output}}           — outputResumen completo del agente (JSON)
+ *   {{planificador-swl.output.archivos}}  — campo específico del outputResumen
+ *   {{planificador-swl.status}}           — status del agente ('done', etc.)
+ *   {{planificador-swl.slice}}            — slice que ejecutó el agente
+ *   {{contexto.archivos}}                 — archivosModificados del contexto compartido
+ *   {{contexto.decisiones}}               — decisiones del contexto compartido
+ *   {{contexto.testsStatus}}              — estado de los tests
+ *   {{contexto.<campo>}}                  — cualquier campo del contextoCompartido
+ *   {{plan.id}}                           — planId del estado
+ *   {{plan.fase}}                         — fase del estado
+ *
+ * Evaluación: lazy — las referencias se resuelven solo cuando se llama a resolver().
+ *
+ * Uso:
+ *   const vr = require('./lib/variable-resolver');
+ *
+ *   const prompt = `
+ *     Implementa los endpoints en {{contexto.archivos}}.
+ *     Decisiones ya tomadas: {{contexto.decisiones}}.
+ *     El plan identificado fue: {{planificador-swl.output.resumen}}.
+ *   `;
+ *   const resuelto = vr.resolver(prompt, process.cwd());
+ *
+ * Zero-dependencies: solo usa execution-state (que usa atomic-write y Node.js built-ins).
+ *
+ * @module hooks/lib/variable-resolver
+ */
+
+const { leer } = require('./execution-state');
+
+// ---------------------------------------------------------------------------
+// Expresión regular para referencias {{...}}
+// ---------------------------------------------------------------------------
+
+/**
+ * Coincide con: {{cualquier.cosa.con.puntos-y-guiones}}
+ * Soporta kebab-case en el nombre de agente (ej: {{planificador-swl.output}})
+ */
+const PATRON_REF = /\{\{([\w.-]+(?:-[\w]+)*(?:\.[\w.-]+)*)\}\}/g;
+
+// ---------------------------------------------------------------------------
+// Resolución de referencias individuales
+// ---------------------------------------------------------------------------
+
+/**
+ * Resuelve una referencia individual contra el estado de ejecución.
+ *
+ * @param {string} ref    — La referencia sin {{ }} (ej: "planificador-swl.output.archivos")
+ * @param {object} estado — Estado de ejecución leído de disco
+ * @returns {*} Valor resuelto, o null si no se encontró
+ */
+function resolverReferencia(ref, estado) {
+  if (!estado) return null;
+
+  // Separar por '.' pero respetar que el nombre de agente puede tener '-'
+  // Estrategia: el primer segmento antes del primer '.' es el "namespace"
+  const primerPunto = ref.indexOf('.');
+  const namespace   = primerPunto >= 0 ? ref.slice(0, primerPunto) : ref;
+  const resto       = primerPunto >= 0 ? ref.slice(primerPunto + 1) : '';
+
+  // --- Namespace especial: plan ---
+  if (namespace === 'plan') {
+    if (!resto || resto === 'id')   return estado.planId || null;
+    if (resto === 'fase')           return estado.fase   || null;
+    return null;
+  }
+
+  // --- Namespace especial: contexto ---
+  if (namespace === 'contexto') {
+    const ctx = estado.contextoCompartido || {};
+    if (!resto) return ctx;
+    if (resto === 'archivos')   return ctx.archivosModificados || [];
+    if (resto === 'decisiones') return ctx.decisiones         || [];
+    if (resto === 'tests')      return ctx.testsStatus        || 'desconocido';
+    return resto in ctx ? ctx[resto] : null;
+  }
+
+  // --- Namespace: nombre de agente ---
+  // Buscar en agentesEjecutados
+  const entrada = (estado.agentesEjecutados || []).find(a => a.agente === namespace);
+  if (!entrada) return null;
+
+  // {{agente}} — entrada completa
+  if (!resto) return entrada;
+
+  // {{agente.output}} — outputResumen completo
+  if (resto === 'output') return entrada.outputResumen || {};
+
+  // {{agente.output.campo}} — campo del outputResumen
+  if (resto.startsWith('output.')) {
+    const campo = resto.slice('output.'.length);
+    return (entrada.outputResumen || {})[campo] ?? null;
+  }
+
+  // {{agente.status}}, {{agente.slice}}, {{agente.duracionMs}}, etc.
+  if (resto in entrada) return entrada[resto];
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Formateo de valores resueltos
+// ---------------------------------------------------------------------------
+
+/**
+ * Convierte un valor resuelto a string para insertar en el template.
+ * Arrays → lista separada por comas; objetos → JSON formateado.
+ *
+ * @param {*} valor
+ * @returns {string}
+ */
+function formatearValor(valor) {
+  if (valor === null || valor === undefined) return '';
+  if (typeof valor === 'string') return valor;
+  if (typeof valor === 'boolean') return valor ? 'sí' : 'no';
+  if (typeof valor === 'number') return String(valor);
+  if (Array.isArray(valor)) {
+    if (valor.length === 0) return '(ninguno)';
+    // Arrays de strings → lista separada por comas
+    if (valor.every(v => typeof v === 'string' || typeof v === 'number')) {
+      return valor.join(', ');
+    }
+    return JSON.stringify(valor, null, 2);
+  }
+  if (typeof valor === 'object') {
+    return JSON.stringify(valor, null, 2);
+  }
+  return String(valor);
+}
+
+// ---------------------------------------------------------------------------
+// API pública
+// ---------------------------------------------------------------------------
+
+/**
+ * Resuelve todas las referencias {{...}} en un string usando el estado de ejecución.
+ * Las referencias no resueltas se dejan con una nota: "[ref: no resuelto]".
+ *
+ * @param {string} template  — Texto con posibles referencias {{...}}
+ * @param {string} [cwd]     — Directorio raíz del proyecto (para leer execution-state.json)
+ * @param {object} [vars={}] — Variables adicionales que tienen precedencia sobre el estado
+ * @returns {string}         — Texto con referencias resueltas
+ */
+function resolver(template, cwd, vars = {}) {
+  if (!template || typeof template !== 'string') return template;
+
+  // Reset lastIndex antes del test
+  PATRON_REF.lastIndex = 0;
+  if (!PATRON_REF.test(template)) return template;
+
+  // Leer estado una sola vez (lazy load)
+  PATRON_REF.lastIndex = 0;
+  const estado = cwd ? leer(cwd) : null;
+
+  return template.replace(PATRON_REF, (match, referencia) => {
+    // 1. Override manual (pruebas o edge cases)
+    if (vars[referencia] !== undefined) {
+      return formatearValor(vars[referencia]);
+    }
+
+    // 2. Resolver contra el estado de ejecución
+    const valor = resolverReferencia(referencia, estado);
+    if (valor === null) {
+      return `[${referencia}: no resuelto]`;
+    }
+    return formatearValor(valor);
+  });
+}
+
+/**
+ * Extrae todas las referencias {{...}} de un template sin resolverlas.
+ * Útil para validar que todas las dependencias están disponibles antes de ejecutar.
+ *
+ * @param {string} template
+ * @returns {string[]} Lista de referencias encontradas (sin duplicados)
+ */
+function extraerReferencias(template) {
+  if (!template) return [];
+  const refs = new Set();
+  const re   = new RegExp(PATRON_REF.source, 'g');
+  let match;
+  while ((match = re.exec(template)) !== null) {
+    refs.add(match[1]);
+  }
+  return [...refs];
+}
+
+/**
+ * Verifica si todas las referencias en un template pueden resolverse
+ * contra el estado de ejecución actual. Útil para validar prompts
+ * antes de enviarlos a un agente.
+ *
+ * @param {string} template
+ * @param {string} [cwd]
+ * @returns {{ valido: boolean, noResueltas: string[], resueltas: string[] }}
+ */
+function validar(template, cwd) {
+  const refs   = extraerReferencias(template);
+  const estado = cwd ? leer(cwd) : null;
+
+  const noResueltas = [];
+  const resueltas   = [];
+
+  for (const ref of refs) {
+    if (resolverReferencia(ref, estado) === null) {
+      noResueltas.push(ref);
+    } else {
+      resueltas.push(ref);
+    }
+  }
+
+  return { valido: noResueltas.length === 0, noResueltas, resueltas };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { resolver, extraerReferencias, validar };