openprompt-lang 1.3.0 → 1.4.0

package/docs/04-TICKETS/_archive/BOOST-006-validation-loop.md

@@ -0,0 +1,66 @@
+# BOOST-006 — Validation Feedback Loop
+
+## Metadatos
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | BOOST-006 |
+| **Título** | Validation Feedback Loop |
+| **Épica** | Módulo OPL Boost |
+| **Prioridad** | Alta |
+| **Estado** | 🔴 Pendiente |
+| **Depende de** | BOOST-005 |
+| **Archivos** | `src/boost/validation-loop.js` |
+
+## Descripción
+
+Sistema post-generación que corre validación OPL y TypeScript sobre el código generado, y retroalimenta los errores específicos al modelo para que los corrija. Los modelos pequeños son significativamente mejores corrigiendo errores específicos que generando código correcto la primera vez.
+
+Si tras N reintentos el código sigue fallando, escala hacia abajo la complejidad de la tarea.
+
+## Criterios de Aceptación
+
+### CA-1: Validación post-generación
+- [ ] `validate(code, kind)` → ejecuta validación OPL sobre el código generado
+- [ ] Detecta: errores de anotaciones, errores de tipo, errores de sintaxis, violaciones de @limit
+- [ ] Retorna array de errores con: tipo, mensaje, línea, sugerencia de fix
+
+### CA-2: Feedback loop
+- [ ] `feedbackLoop(code, errors, profile)` → intenta corregir errores iterativamente
+- [ ] Por cada error, genera un mensaje de feedback claro para el modelo
+- [ ] El feedback dice exactamente qué está mal y da una sugerencia de cómo arreglarlo
+- [ ] El modelo corrige y se re-valida
+- [ ] Número de reintentos según perfil: small=3, medium=2, large=1
+
+### CA-3: Escalado de complejidad
+- [ ] Si tras 3 reintentos (small) el código sigue fallando, reduce complejidad
+- [ ] Estrategias de escalado: simplificar lógica, usar skeleton más básico, dividir en más micro-tareas
+- [ ] `escalateDown(task, attempt)` → devuelve versión simplificada de la tarea
+- [ ] El escalado se registra como @learn-error para futuras sesiones
+
+### CA-4: Integración con micro-tasker
+- [ ] Cuando una micro-tarea individual falla la validación, se reintenta antes de pasar a la siguiente
+- [ ] Si la micro-tarea falla consistentemente, el orquestador (BOOST-005) decide escalar
+
+### CA-5: Reporte de calidad
+- [ ] `generateReport(codeHistory, errors)` → genera reporte de cuántos intentos tomó, qué errores se corrigieron
+- [ ] El reporte se puede incluir en la documentación de la sesión
+
+### CA-6: Tests
+- [ ] Test de detección de errores de anotaciones
+- [ ] Test de feedback loop con mock de correcciones
+- [ ] Test de escalado tras N reintentos fallidos
+- [ ] Test de reporte de calidad
+
+## Archivos a crear/modificar
+
+| Archivo | Acción |
+|---------|--------|
+| `src/boost/validation-loop.js` | ➕ Crear |
+
+## Notas técnicas
+
+- La validación OPL se hace invocando `npx openprompt-lang validate` o usando el módulo de validación directamente
+- El feedback loop necesita acceso al modelo para re-generar — pero en esta fase inicial, solo prepara los mensajes de feedback (la re-generación la hace quien llame al boost)
+- El escalado de complejidad es determinista (no necesita IA): simplifica basado en reglas
+- Los errores más comunes en modelos pequeños: @kind faltante, @limit excedido, tipos incorrectos

package/docs/04-TICKETS/_archive/BOOST-007-progressive-pipeline.md

@@ -0,0 +1,69 @@
+# BOOST-007 — Progressive Disclosure Pipeline
+
+## Metadatos
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | BOOST-007 |
+| **Título** | Progressive Disclosure Pipeline |
+| **Épica** | Módulo OPL Boost |
+| **Prioridad** | Alta |
+| **Estado** | 🔴 Pendiente |
+| **Depende de** | BOOST-002, BOOST-006 |
+| **Archivos** | `src/boost/progressive-pipeline.js`, `src/boost/index.js` |
+
+## Descripción
+
+Pipeline multi-etapa que orquesta todos los componentes Boost en un flujo coherente. Cada etapa expone gradualmente más complejidad al modelo, de modo que nunca ve el problema completo de golpe.
+
+El `index.js` es el punto de entrada unificado del módulo Boost.
+
+## Criterios de Aceptación
+
+### CA-1: Pipeline multi-etapa
+- [ ] **Stage 1 — Diseño**: el modelo define props, tipos, interface, contract sin implementar lógica
+- [ ] **Stage 2 — Implementación**: el modelo rellena el skeleton con lógica de negocio
+- [ ] **Stage 3 — Polish**: el modelo recibe feedback de validación y corrige errores
+- [ ] Cada etapa es más específica que la anterior
+
+### CA-2: Orchestrador unificado (index.js)
+- [ ] `boost(task, options)` → orquesta todo el pipeline
+- [ ] `options.profile` → perfil a usar
+- [ ] `options.kind` → tipo de archivo a generar
+- [ ] `options.dryRun` → mostrar plan sin ejecutar
+- [ ] `options.output` → archivo de salida (opcional)
+- [ ] Retorna: `{ code, metadata, report }`
+
+### CA-3: Metadata de ejecución
+- [ ] `{ profile, stages: [{name, duration, result}], totalTime, compressionRatio, validationAttempts }`
+- [ ] Permite comparar rendimiento entre perfiles
+- [ ] Se puede exportar como JSON
+
+### CA-4: Modo dry-run
+- [ ] `boost(task, { dryRun: true })` → muestra qué haría en cada etapa sin ejecutar
+- [ ] Muestra: plan de micro-tareas, skeletons a usar, ejemplos a inyectar
+
+### CA-5: Integración con compress
+- [ ] Antes del Stage 1, comprime el contexto según perfil (usa BOOST-002)
+- [ ] El Stage 1 recibe contexto mínimo
+- [ ] Los Stages 2 y 3 pueden recibir contexto adicional si es necesario
+
+### CA-6: Tests
+- [ ] Test de pipeline completo con mock de modelo
+- [ ] Test de metadata de ejecución
+- [ ] Test de dry-run
+- [ ] Test de integración: pipeline completo produce código válido
+
+## Archivos a crear/modificar
+
+| Archivo | Acción |
+|---------|--------|
+| `src/boost/index.js` | ➕ Crear (orquestador unificado) |
+| `src/boost/progressive-pipeline.js` | ➕ Crear (pipeline multi-etapa) |
+
+## Notas técnicas
+
+- El index.js es el API público del módulo Boost
+- Cada etapa del pipeline es un plugin: `pipeline.use(stage)` para futura extensibilidad
+- El pipeline registra tiempo de cada etapa para diagnóstico
+- Si una etapa falla, el pipeline detiene la ejecución y devuelve error con estado parcial

package/docs/04-TICKETS/_archive/BOOST-008-cli-mcp-integration.md

@@ -0,0 +1,74 @@
+# BOOST-008 — CLI + MCP Integration
+
+## Metadatos
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | BOOST-008 |
+| **Título** | CLI + MCP Integration |
+| **Épica** | Módulo OPL Boost |
+| **Prioridad** | Media |
+| **Estado** | 🔴 Pendiente |
+| **Depende de** | BOOST-007 |
+| **Archivos** | `src/cli/commands-boost.js`, `src/mcp-server.js`, `src/mcp-refactor/router.js`, `AGENTS.md` |
+
+## Descripción
+
+Integrar el módulo Boost con la CLI de OPL (comandos `opl boost *`) y con el servidor MCP (tools `OPL_Boost_*`). También actualizar AGENTS.md con la sección Boost Workflow para que las IAs futuras sepan cómo usar el módulo.
+
+## Criterios de Aceptación
+
+### CA-1: CLI completa
+- [ ] `opl boost check` → diagnóstico del perfil activo
+- [ ] `opl boost profile <name>` → forzar perfil (small/medium/large/auto)
+- [ ] `opl boost generate <desc>` → generar código con pipeline completo
+- [ ] `opl boost microtask <task>` → descomponer tarea en micro-tareas
+- [ ] Todos los comandos tienen `--help` descriptivo
+- [ ] Todos los comandos tienen `--dry-run`
+
+### CA-2: MCP tools
+- [ ] `OPL_Boost_profile` → mostrar perfil actual del modelo
+- [ ] `OPL_Boost_compress` → comprimir contexto según perfil
+- [ ] `OPL_Boost_microtask` → ejecutar pipeline de micro-tasking
+- [ ] `OPL_Boost_hydrate` → hidratar un skeleton con lógica
+- [ ] `OPL_Boost_validate` → loop de validación con retroalimentación
+- [ ] Las tools aparecen en el servidor MCP y son invocables
+
+### CA-3: AGENTS.md actualizado
+- [ ] Nueva sección "## 🚀 OPL Boost — Potenciar modelos pequeños" en AGENTS.md
+- [ ] Describe: qué es, cuándo usarlo, cómo configurarlo
+- [ ] Tabla de perfiles (small/medium/large)
+- [ ] Workflow Boost para IAs que usan el módulo
+- [ ] Referencia rápida de comandos `opl boost *`
+
+### CA-4: Registrar en bin/cli.js
+- [ ] `registerBoost(program)` llamado desde `bin/cli.js`
+- [ ] Import y registro consistente con los otros comandos
+
+### CA-5: Registrar en MCP server
+- [ ] Tools de boost agregadas a TOOLS en `src/mcp-refactor/tools.js`
+- [ ] Router en `src/mcp-refactor/router.js` maneja boost tools
+- [ ] Workflow generator en `src/mcp-workflow.js` incluye boost
+
+### CA-6: Tests de integración
+- [ ] Test de CLI: `opl boost check` funciona sin errores
+- [ ] Test de MCP: tools registradas correctamente
+- [ ] Test que todos los comandos tienen `--help`
+
+## Archivos a crear/modificar
+
+| Archivo | Acción |
+|---------|--------|
+| `src/cli/commands-boost.js` | ➕ Crear (registro completo de comandos) |
+| `bin/cli.js` | ✏️ Modificar (import + register) |
+| `src/mcp-server.js` | ✏️ Modificar (boost tools en TOOLS) |
+| `src/mcp-refactor/router.js` | ✏️ Modificar (boost routes) |
+| `src/mcp-workflow.js` | ✏️ Modificar (boost instructions) |
+| `AGENTS.md` | ✏️ Modificar (sección Boost) |
+
+## Notas técnicas
+
+- Los MCP tools deben seguir el patrón existente en `src/mcp-refactor/tools.js`
+- Los comandos CLI deben seguir el patrón de commander (`.command().description().action()`)
+- La sección de AGENTS.md debe seguir el tono y formato del documento existente
+- No debe romper comandos existentes ni tools MCP existentes

package/docs/AI_CONTEXT.md

@@ -60,8 +60,24 @@ npx openPrompt-Lang validate        # Validar anotaciones
 npx openPrompt-Lang lang list       # Listar módulos
 npx openPrompt-Lang teach <id>      # Aprender de un template
 npx openPrompt-Lang qa-gen          # Generar tests de regresión
+
+# OPL Boost (multi-agente para modelos pequeños)
+opl boost check                     # Diagnóstico perfil + estado del sistema
+opl boost profile [name]            # Ver/forzar perfil (small/medium/large/auto)
+opl boost setup                     # Detectar hardware + configurar
+opl boost generate <desc>           # Generar código con pipeline Boost
+opl boost microtask <task>          # Descomponer tarea en DAG
+opl boost cache [action]            # Gestionar caché (stats, clear, clean)
 ```
 
+## 5.5. Módulo OPL Boost
+- **12 tickets implementados** (BOOST-001 a BOOST-012, todos completados)
+- **Pipeline**: profile detection → context compression → few-shot → agent pool → skeleton hydration → validation loop
+- **Dos modos**: single-pass (default) y multi-agent (`--multi-agent`)
+- **Código**: `src/boost/` (17 archivos, ~3,700 líneas)
+- **MCP tools**: `boost_generate`, `boost_compress`, `boost_profile`, `boost_plan`, `boost_validate`
+- **Filosofía**: cada componente funciona independientemente; el multi-agente es opt-in
+
 ## 6. Referencia canónica
 - `.openprompt/FRAMEWORK.md` — Manual completo: anotaciones, comandos CLI, MCP, dominios, módulos, reglas estrictas.
 - `AGENTS.md` — Stack, convenciones, UI, calidad.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openprompt-lang",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "PromptLang CLI — Context Engine de anotaciones para desarrollo asistido por IA",
   "type": "module",
   "main": "./bin/cli.js",
@@ -55,7 +55,8 @@
     "opencode:wizard": "openprompt-lang wizard",
     "opencode:plan": "openprompt-lang plan",
     "opencode:execute": "openprompt-lang execute",
-    "opencode:mode": "openprompt-lang mode"
+    "opencode:mode": "openprompt-lang mode",
+    "opl:enforce": "node scripts/opl-enforce-setup.mjs"
   },
   "keywords": [
     "prompt-lang",

package/src/boost/agent-pool.js

@@ -0,0 +1,442 @@
+// @use(kind, contract, limit, error)
+// @kind(util)
+// @contract(in: prompt, role, profile -> out: AgentPool instance + callOllama, buildPrompt, checkOllama @error: OllamaConnectionError, AgentTimeoutError)
+// @limit(lines: 200)
+
+/**
+ * Agent Pool — Módulo OPL Boost
+ *
+ * Conector a Ollama + pool de agentes para orquestación interna.
+ * Permite que OPL llame a modelos locales sin depender de OpenCode.
+ *
+ * Modo de uso:
+ *   import { agentPool } from './agent-pool.js'
+ *   const result = await agentPool.submit('types', 'hook useAuth')
+ *
+ * Modo cola (FIFO): default, una solicitud a la vez
+ * Modo paralelo: configurable via profile.agentPool.maxConcurrency
+ */
+
+import { getProfile } from "./profile-registry.js"
+
+// ──────────────────────────────────────────────
+// Configuración
+// ──────────────────────────────────────────────
+
+const OLLAMA_HOST = process.env.OLLAMA_HOST || "http://localhost:11434"
+const DEFAULT_TIMEOUT = 30_000 // 30s
+
+// ──────────────────────────────────────────────
+// System prompts por rol de agente
+// ──────────────────────────────────────────────
+
+const AGENT_SYSTEM_PROMPTS = {
+  types:
+    "Eres un experto en TypeScript. Tu única tarea es definir TYPES e INTERFACES. " +
+    "No implementes lógica. No generes JSX. Solo tipos, interfaces, y anotaciones de tipo. " +
+    "Output exacto: bloques de código TypeScript con export.",
+
+  state:
+    "Eres un experto en React state management. Recibes types ya definidos. " +
+    "Tu tarea es diseñar el ESTADO del componente/hook: useState, useReducer, useEffect. " +
+    "No implementes lógica de negocio. Solo estructura de estado y efectos. " +
+    "Output exacto: bloques de código con hooks de React.",
+
+  logic:
+    "Eres un experto en implementar lógica de negocio. Recibes types + estado ya definidos. " +
+    "Tu tarea es IMPLEMENTAR las funciones con lógica real. " +
+    "Usa los types y estado existentes. No los redefinas. " +
+    "Output exacto: la función/componente completo con implementación.",
+
+  cleaner:
+    "Eres un compresor de contexto para desarrollo asistido por IA. " +
+    "Recibes reglas extensas y debes devolver SOLO las reglas relevantes para la tarea específica. " +
+    "Prioriza: límites de líneas (@kind + @limit), reglas de enforcement, prohibiciones (NUNCA). " +
+    "Omite: stack, UI, colores, documentación de comandos no relevantes. " +
+    "Output exacto: markdown compacto con las reglas esenciales.",
+
+  validate:
+    "Eres un corrector de código. Recibes código que falló validación y los errores específicos. " +
+    "Tu tarea es CORREGIR solo los errores reportados, no reescribir todo. " +
+    "Conserva la estructura y lógica original. Arregla solo lo que falló. " +
+    "Output exacto: el código completo corregido.",
+}
+
+// ──────────────────────────────────────────────
+// Builders de prompts
+// ──────────────────────────────────────────────
+
+const PROMPT_TEMPLATES = {
+  types: (input) =>
+    `Task: Define types for "${input}"
+
+Rules:
+- Export all interfaces
+- Use TypeScript strict mode
+- Add JSDoc comments
+- Maximum 60 lines
+
+Output ONLY TypeScript types.`,
+
+  state: (input) =>
+    `Task: Design state management
+
+Context: ${input}
+
+Rules:
+- Use React hooks (useState, useEffect, useCallback)
+- Reference existing types
+- No business logic
+- Maximum 60 lines
+
+Output ONLY React hooks and state.`,
+
+  logic: (input) =>
+    `Task: Implement business logic
+
+Context: ${input}
+
+Rules:
+- Use existing types and state
+- Implement full logic
+- Handle errors and edge cases
+- Maximum 80 lines
+
+Output ONLY the implementation.`,
+
+  cleaner: (input) =>
+    `Task: Compress context for code generation
+
+Target task: ${input.substring(0, 200)}
+
+Rules to preserve (if present in context):
+- @kind limits (hook:80, component:120, page:200, service:150, store:100, util:100)
+- @limit blocks commits, NOT a suggestion
+- @use() required at file top
+- Named exports over default
+- NUNCA rules (any, template files, etc.)
+- Annotations first, implementation second
+
+Compress to <200 lines. Preserve critical rules only.`,
+
+  validate: (input) =>
+    `Task: Fix validation errors
+
+Code with errors:
+\`\`\`
+${input.substring(0, 1500)}
+\`\`\`
+
+Fix ONLY the reported errors. Do not rewrite.
+Output the ENTIRE corrected file.`,
+}
+
+export function buildPrompt(role, input) {
+  const systemPrompt = AGENT_SYSTEM_PROMPTS[role]
+  const template = PROMPT_TEMPLATES[role]
+
+  if (!systemPrompt || !template) {
+    throw new Error(`Rol de agente desconocido: "${role}". Roles: ${Object.keys(AGENT_SYSTEM_PROMPTS).join(", ")}`)
+  }
+
+  return {
+    system: systemPrompt,
+    prompt: template(input),
+    role,
+  }
+}
+
+// ──────────────────────────────────────────────
+// Ollama connector
+// ──────────────────────────────────────────────
+
+export class OllamaConnectionError extends Error {
+  constructor(message, cause) {
+    super(message)
+    this.name = "OllamaConnectionError"
+    this.cause = cause
+  }
+}
+
+export class AgentTimeoutError extends Error {
+  constructor(role, timeout) {
+    super(`Agent "${role}" timed out after ${timeout}ms`)
+    this.name = "AgentTimeoutError"
+    this.role = role
+    this.timeout = timeout
+  }
+}
+
+// Cache de modelo seleccionado para no re-detectar en cada llamada
+let _bestModelCache = null
+
+export async function callOllama(promptText, options = {}) {
+  const {
+    model = _bestModelCache || "llama3.2:latest", // default seguro siempre disponible
+    system = "",
+    temperature = 0.2,
+    maxTokens = 4096,
+    timeout = DEFAULT_TIMEOUT,
+  } = options
+
+  const controller = new AbortController()
+  const timeoutId = setTimeout(() => controller.abort(), timeout)
+
+  try {
+    const body = {
+      model,
+      prompt: promptText,
+      system,
+      stream: false,
+      options: {
+        temperature,
+        num_predict: maxTokens,
+      },
+    }
+
+    const response = await fetch(`${OLLAMA_HOST}/api/generate`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    })
+
+    if (!response.ok) {
+      throw new OllamaConnectionError(
+        `Ollama responded with ${response.status}: ${response.statusText}`
+      )
+    }
+
+    const data = await response.json()
+
+    if (data.error) {
+      throw new OllamaConnectionError(`Ollama error: ${data.error}`)
+    }
+
+    return {
+      text: data.response || "",
+      totalDuration: data.total_duration || 0,
+      tokensPerSecond: data.tokens_per_second || 0,
+      tokenCount: (data.tokens_evaluated || 0) + (data.prompt_eval_count || 0),
+    }
+  } catch (err) {
+    if (err.name === "AbortError") {
+      throw new AgentTimeoutError(options.role || "unknown", timeout)
+    }
+    if (err instanceof OllamaConnectionError || err instanceof AgentTimeoutError) {
+      throw err
+    }
+    throw new OllamaConnectionError(
+      `Failed to connect to Ollama at ${OLLAMA_HOST}: ${err.message}`,
+      err
+    )
+  } finally {
+    clearTimeout(timeoutId)
+  }
+}
+
+// ──────────────────────────────────────────────
+// Pool de agentes (cola FIFO)
+// ──────────────────────────────────────────────
+
+class AgentPool {
+  constructor() {
+    this._queue = []
+    this._running = false
+    this._currentTask = null
+    this._stats = { completed: 0, failed: 0, totalTime: 0 }
+  }
+
+  /**
+   * Encola una solicitud de agente y retorna el resultado.
+   * Antes de encolar, verifica el estado del sistema (RAM, CPU).
+   *
+   * @param {string} role - Rol del agente (types, state, logic, cleaner, validate)
+   * @param {string} input - Input para el agente
+   * @param {object} [profile] - Perfil Boost (opcional, auto-detecta si se omite)
+   * @returns {Promise<{text: string, role: string, duration: number, metrics: object}>}
+   */
+  async submit(role, input, profile) {
+    const prof = profile || getProfile()
+    const agentConfig = prof?.agentPool || {}
+
+    // Verificar estado del sistema antes de encolar
+    const { getSafeParallelism, getRAMWarning } = await import("./hardware-detector.js")
+    const safety = getSafeParallelism(prof)
+
+    if (!safety.safe) {
+      const warning = getRAMWarning()
+      throw new Error(
+        `Boost bloqueado por recursos insuficientes.\n${warning}\n` +
+        `→ Libera memoria y vuelve a intentarlo.`
+      )
+    }
+
+    return new Promise((resolve, reject) => {
+      this._queue.push({
+        role,
+        input,
+        profile: prof,
+        agentConfig,
+        safety, // guardamos la recomendación de seguridad
+        resolve,
+        reject,
+      })
+      this._processQueue()
+    })
+  }
+
+  async _processQueue() {
+    if (this._running || this._queue.length === 0) return
+    this._running = true
+
+    while (this._queue.length > 0) {
+      const task = this._queue.shift()
+      this._currentTask = task
+      const startTime = Date.now()
+
+      // Re-verificar sistema antes de CADA agente (por si cambió)
+      try {
+        const { getSafeParallelism, getRAMWarning } = await import("./hardware-detector.js")
+        const currentSafety = getSafeParallelism(task.profile)
+
+        if (!currentSafety.safe) {
+          // Si el sistema se saturó mientras esperaba, re-encolar
+          const warning = getRAMWarning()
+          console.warn(`\n  ⏸  Agente "${task.role}" pausado — ${warning}`)
+          // Esperar 5 segundos y re-intentar
+          await new Promise((r) => setTimeout(r, 5000))
+          this._queue.unshift(task) // re-encolar al principio
+          continue
+        }
+
+        // Si hay demasiados agentes en paralelo y estamos en modo cola, esperar
+        if (currentSafety.mode === "queue" && task.safety?.mode === "parallel") {
+          // La situación cambió: degradar a cola automáticamente
+          console.warn(`\n  ⏸  Cambiando a modo cola por carga del sistema.`)
+        }
+      } catch {
+        // Si falla la verificación, continuar de todas formas
+      }
+
+      try {
+        const prompt = buildPrompt(task.role, task.input)
+        const modelName =
+          task.agentConfig.modelName || task.profile?.agentPool?.modelName || _bestModelCache || await selectBestModel(task.profile) || "llama3.2:latest"
+
+        // Estimar RAM que usará el modelo
+        const { estimateModelRAM } = await import("./hardware-detector.js")
+        const estimatedRAM = estimateModelRAM(modelName)
+
+        const result = await callOllama(prompt.prompt, {
+          model: modelName,
+          system: prompt.system,
+          temperature: task.agentConfig.temperature || 0.2,
+          timeout: task.agentConfig.timeout || DEFAULT_TIMEOUT,
+          role: task.role,
+        })
+
+        const duration = Date.now() - startTime
+        this._stats.completed++
+        this._stats.totalTime += duration
+
+        task.resolve({
+          text: result.text.trim(),
+          role: task.role,
+          duration,
+          metrics: {
+            tokensPerSecond: result.tokensPerSecond,
+            tokenCount: result.tokenCount,
+            model: modelName,
+            estimatedRAMGB: estimatedRAM,
+          },
+        })
+      } catch (err) {
+        this._stats.failed++
+        task.reject(err)
+      }
+    }
+
+    this._running = false
+    this._currentTask = null
+  }
+
+  get stats() {
+    return { ...this._stats, queueLength: this._queue.length, isRunning: this._running }
+  }
+
+  async clear() {
+    this._queue = []
+  }
+}
+
+// Singleton
+export const agentPool = new AgentPool()
+
+// ──────────────────────────────────────────────
+// Utilidades de detección
+// ──────────────────────────────────────────────
+
+export async function checkOllama() {
+  try {
+    const response = await fetch(`${OLLAMA_HOST}/api/tags`, {
+      signal: AbortSignal.timeout(5000),
+    })
+    return response.ok
+  } catch {
+    return false
+  }
+}
+
+export async function listOllamaModels() {
+  try {
+    const response = await fetch(`${OLLAMA_HOST}/api/tags`, {
+      signal: AbortSignal.timeout(5000),
+    })
+    if (!response.ok) return []
+    const data = await response.json()
+    return (data.models || []).map((m) => ({
+      name: m.name,
+      size: m.size,
+      modifiedAt: m.modified_at,
+    }))
+  } catch {
+    return []
+  }
+}
+
+export async function selectBestModel(profile) {
+  const models = await listOllamaModels()
+  if (models.length === 0) return null
+
+  const profileName = profile?.name || "medium"
+
+  // Preferencias según perfil — mapeadas a modelos que existen en esta instancia
+  const preferences = {
+    small: ["qwen2.5-coder:7b", "qwen2.5-coder", "llama3.2", "llama3.2:latest", "phi", "deepseek-coder"],
+    medium: ["qwen2.5-coder:7b", "qwen2.5-coder", "codellama", "mistral", "llama3"],
+    large: ["qwen2.5-72b", "llama-3-70b", "llama3:latest", "qwen2.5-coder:7b"],
+  }
+
+  const preferred = preferences[profileName] || preferences.medium
+
+  // Buscar el mejor modelo disponible según preferencias
+  for (const pref of preferred) {
+    const match = models.find((m) => m.name === pref || m.name.toLowerCase().includes(pref))
+    if (match) {
+      _bestModelCache = match.name
+      return match.name
+    }
+  }
+
+  // Fallback: primer modelo disponible (excluir embeddings)
+  const nonEmbedding = models.find((m) => !m.name.includes("nomic") && !m.name.includes("embed"))
+  if (nonEmbedding) {
+    _bestModelCache = nonEmbedding.name
+    return nonEmbedding.name
+  }
+
+  // Último recurso
+  _bestModelCache = models[0].name
+  return models[0].name
+}