TODO.md

TODO

Lista de temas detectados para revisar antes de una publicación estable.

LLM, AI SDK y tools

• Mejorar la interacción de tools con modelos Transformers.js usando AI SDK: revisar documentación oficial, ejemplos actuales, patrones de tool calling, streaming, stop conditions, middlewares y limitaciones de modelos locales.
• Revisar el bloque de thinking en modelos que muestran razonamiento: cuándo aparece, cómo se renderiza, toggle de visibilidad y coherencia con el streaming.
• Revisar la detección de JSON en respuestas de modelos: validar si el parser actual es adecuado para tool calling y si el mensaje «El modelo local no generó texto. Recarga (Ctrl+Shift+R) o prueba otro modelo.» cubre bien los casos reales (respuesta vacía, solo JSON, razonamiento sin texto visible).
• Revisar integración con Ollama cuando el proyecto esté publicado en internet: CORS, origen permitido, endpoints locales, seguridad y experiencia de configuración.
• Mejorar y revisar la gestión de artifacts: ciclo de vida,persistencia, limpieza, referencias desde el contexto, visualización en UI y límites de memoria.
• Seleccionar mejor los modelos que aceptan y funcionan correctamente con tools por defecto.
• Revisar el funcionamiento real de todas las tools creadas y añadir una tool sencilla para escribir ficheros en la VM (p. ej. ruta + contenido, límites de tamaño, creación de directorios opcional y validación de errores/permisos).
  • Probar manualmente cada tool en cada perfil (alpine-base, alpine-pentest-lite, alpine-pentest-web) y confirmar que solo aparecen las que corresponden a los paquetes incluidos en el perfil.
  • Revisar códigos de salida reales por tool, especialmente casos con salida útil y rc != 0 (curl, ffuf, httpx, nikto, nmap), para distinguir fallo real, resultado parcial y salida válida.
  • Validar vm.fs.write: escritura nueva, bloqueo de sobrescritura, overwrite, createDirs, límites de contenido, permisos y rutas bloqueadas.
• Revisar la visualización del razonamiento (thinking) en el chat: con el toggle activo, comprobar en qué casos se muestra, si permanece en el historial y si es coherente con tools, respuestas vacías o turnos sin texto final (p. ej. cuando hubo razonamiento pero no respuesta visible, o el modelo ejecutó una tool y el bloque desaparece al cerrar el turno).
• Revisar el fallback WASM tras fallo WebGPU al cargar modelos Transformers.js: comprobar que la alternativa funciona bien y que un segundo intento de carga usa realmente el backend esperado (WASM vs GPU).
• Hacer que el botón Comprobar derive los checks de tools desde las propias definiciones de tool, no desde un mapa hardcodeado de paquetes en la UI. Opción propuesta: añadir availabilityChecks/runtimeChecks opcional a ToolDefinition, que cada tool declare los comandos mínimos que prueban su disponibilidad real (command -v curl, command -v nikto.pl, fallback de nombres para httpx, etc.) y que checks-panel.ts los obtenga desde el registry usando allowedTools del perfil activo. Mantener el check de paquetes instalado separado de los checks de disponibilidad de tools.
• Resolver el papel de validationCommands: se eliminan del contrato de perfiles porque solo eran metadata impresa al final del build y no se ejecutaban en setup, build, check, runtime ni frontend. Las comprobaciones reales deben vivir en buildCommands, firstBootCommands o runtimeChecks de cada tool.

Producto y publicación

• Crear repositorio públicohttps://github.com/Len4m/browser-agent-v86-poc cuando se decida publicar.
• Metadatos básicos para la demo pública (https://browseragent.icu/): favicon real, apple-touch-icon, meta description, Open Graph/Twitter Card con imagen de preview, canonical configurable por BA_PUBLIC_SITE_URL y robots.txt estático en public/. No se añade sitemap.xml mientras la SPA pública no exponga rutas indexables diferenciadas.
• SEO multilingüe por URL (mejora opcional para publicación): hoy el idioma es solo en cliente (misma URL + selector ES/EN), insuficiente para indexar ES y EN por separado. Valorar rutas distintas (p. ej. / y /en/) con lang, meta y hreflang por idioma; valorar sitemap.xml solo si se crean rutas estáticas indexables. Preferir generación estática en build (sin lógica extra en servidor más allá de servir public/). Complementa el punto anterior; puede aplazarse si basta meta en inglés con mención a la UI en español.
• Publicar assets descargables en GitHub Releases (zip listo para ejecutar sin clonar ni npm install). Al crear una release sobre la tag de versión, adjuntar un archivo comprimido con el build de producción ya generado. Contenido mínimo propuesto: public/ (tras npm run setup + npm run build:prod), server.mjs, LICENSE e instrucciones breves (descomprimir → node server.mjs → abrir http://127.0.0.1:5173/). Valorar script en scripts/ (p. ej. empaquetar y nombrar browser-agent-v86-poc-<version>.zip) e integración en CI al publicar tag/release. Documentar en release notes: requisito Node 18+, tamaño aproximado del zip (WASM v86, imágenes VM, bundles LLM), que los modelos Transformers.js siguen descargándose en el navegador salvo que se decida incluirlos, y que wsnic/Ollama siguen siendo opcionales locales. Criterio de aceptación: un usuario sin repo puede descargar el zip de una release, arrancarlo y usar la demo local con el mismo comportamiento que servir public/ desde el repositorio.

Consola y xterm.js

• Revisar manualmente la ramaxterm-direct-consoles: consolas xterm con PTYs independientes dentro de la VM, máximo 4 sesiones, transporte multiplexado porserial2 y tools separadas porserial1.
• Decidir el lenguaje de los runners guest envm/overlay/common/usr/local/bin/: se mantiene python3 como dependencia obligatoria de todos los perfiles y se migra ba-serial1-runner a Python 3, igual que ba-serial2-console-runner. Criterio: la red/v86 dominan la latencia, el runner serial1 es persistente y no paga arranque de Python por job, y unificar en Python simplifica el protocolo, timeouts y drenaje de stdout/stderr.
• La consola1 (la que funciona por serial0) no permite copiar texto con el botón derecho del ratón ni por ningún otro medio, mientras que en el resto de consolas sí es posible copiar usando el botón derecho.

VM y carga inicial

• Revisar restauración de máquinas desde fichero/snapshot: tras restaurar, revalidar o reenganchar serial1 y serial2 para que funcionen tools y creación de nuevas consolas. Definir también qué debe ocurrir con pestañas xterm/PTY ya existentes: si el snapshot contenía procesos en otras pestañas, la UI debería recuperar esas pestañas y reconectarlas a sus sesiones/procesos, o detectar claramente que no son recuperables y recrearlas de forma consistente.
• Permitir cancelar la descarga de assets de la VM: hoy, una vez iniciado el arranque (preloadVmAssets enruntime-assets.ts), las peticiones de kernel, initrd, disco hda y scripts no se pueden abortar; si el usuario se equivoca de perfil/disco o la descarga tarda demasiado, la única salida es refrescar la página. Añadir cancelación explícita (p. ej. botón en#loading-overlay,AbortController en los fetch, limpieza de estado enserial-vm.ts y desbloqueo de opciones/Start).
• Probar la experiencia en conexiones lentas y valorar un loading inicial de la aplicación: antes de arrancar la VM, el bundle JS, los catálogos i18n y otros assets pueden tardar en redes lentas sin feedback claro. Hacer pruebas con throttling (DevTools) y, si hace falta, reutilizar el overlay de carga existente (#loading-overlay/setLoading) para mostrar progreso o estado indeterminado hasta que la UI esté lista para interactuar.
• Incluir la carga del catálogo i18n en la precarga inicial: el overlay ya cubre el bundle JS y otros assets, pero el idioma se resuelve después y la UI puede mostrarse brevemente con textos del idioma base o claves sin traducir antes de aplicar el locale elegido. Precargar ./locales/{lang}.json (según preferencia almacenada o idioma del navegador) dentro del flujo de arranque, antes de quitar el overlay, para que la interfaz aparezca ya traducida.
• Comparar NE2000 (ne2k) frente a virtio-net en v86 + Alpine y conmutar a virtio como predeterminado. Resultado: con wsnic local y Alpine moderno, virtio (virtio_net) mantiene DHCP estable y latencia comparable a ne2k-pci, pero descarga local HTTP en torno a 2-3x más rápido. Se mantiene ne2k-pci empaquetado como fallback.
• Mejorar las opciones de conexión de red v86/wsnic para no depender únicamente del contenedor Docker local. Contemplar ws:// (8086), wss:// (8087, certificado + clave y terminación TLS con stunnel) y endpoints remotos. Evaluar e implementar una solución con estos criterios:
  • Probar como opción externa inmediata el relay público gratuito que documenta v86, wss://relay.widgetry.org/, dejando claro en la UI que es compartido, de ancho de banda limitado, sin SLA ni garantía de privacidad/disponibilidad; no convertirlo en predeterminado sin validar DHCP/DNS, tráfico TCP/UDP, límites, abuso y estabilidad.
  • Consolidar el soporte de wss:// que la URL y las validaciones actuales ya aceptan y probarlo extremo a extremo con un endpoint remoto. Ofrecer ejemplos seguros con certificado público (p. ej. Let's Encrypt o TLS terminado en Caddy/Nginx/Traefik/túnel), validación del certificado y una advertencia contra certificados autofirmados o flags del navegador que deshabiliten su seguridad.
  • Extender la configuración/UI con presets local ws, local/remote wss y relay público experimental, errores TLS diferenciados, reconexión con backoff, test previo y documentación ES/EN. Criterio de aceptación: matriz reproducible que cubra el relay público y un endpoint wss:// remoto, incluyendo conexión, desconexión y gestión de errores.
• Valorar la instalación de paquetes base adicionales en los perfiles Alpine: openssh para uso SSH si aplica, git para clonar repositorios y py3-pip para disponer de pip. Revisar impacto en tamaño de imagen, dependencias, tiempo de descarga y qué perfiles deberían incluirlos por defecto.

i18n

• Revisar textos visibles de la UI y documentación para preparar internacionalización: separar cadenas traducibles, decidir idioma base y evitar textos hardcodeados en JavaScript cuando sea posible. Tener especial cuidado con el uso de memoria: no cargar catálogos de idiomas grandes ni mantener duplicadas cadenas que no sean necesarias en runtime.
• Traducir la UI y los prompts LLM al inglés: catálogo en.json en paridad con es.json (~780 claves), selector ES/EN y comprobación de claves en npm run check.
• Revisar la calidad de las traducciones al inglés: npm run check garantiza paridad de claves, no que el texto EN sea correcto o natural. Repasar manualmente las cadenas más visibles (errores, panel LLM, chat, checks).
• Alinear la documentación con i18n: actualizar README.md y docs/USAGE.md (y lo que aplique) para reflejar el selector de idioma ES/EN y no dejar solo contenido en español donde deba servir también a usuarios en inglés.

Documentación y manual de usuario

• Mantener README.md y la documentación de docs/ en español e inglés, con estructura equivalente y enlaces claros entre idiomas.
• Crear un manual de uso de la aplicación separado de la documentación del repositorio: debe explicar el funcionamiento para usuarios finales sin centrarse en instalación, desarrollo ni scripts.
• Enlazar el manual de usuario desde la GUI, respetando el idioma activo cuando existan versiones ES/EN.
• Documentar en el manual las pantallas principales, botones, controles, perfiles VM, consolas, chat LLM, tools, carga de modelos, snapshots, discos y estados/errores habituales.
• Añadir capturas definitivas al manual: vista principal con VM encendida, consola visible y paneles inferiores abiertos; capturas de detalle para selector de tools, artifacts, recursos/contexto del LLM y ejemplos de ejecución del agente.

Build, CSS y tamaño

• Revisar HTML/CSS generado o inyectado desde JavaScript (p. ej. plantillas del panel LLM): decidir qué puede vivir directamente enindex.html o ficheros estáticos para evitar construcción en runtime, reducir JS y simplificar mantenimiento.
• Optimizar el render markdown durante streaming: AI SDK entrega los deltas, pero el DOM lo gestionastreaming-markdown; reducir pasadas repetidas de mejora de bloques de código durante la generación.
• Reducir reconstrucciones del panel LLM coninnerHTML: tools nativas, recursos/contexto y metadatos deberían tender a DOM persistente, event delegation y actualizaciones puntuales.
• Revisar CSS: ahora hay muchos ficheros; agrupar o simplificar reglas si mejora mantenimiento y permite reducir bytes sin perder claridad.
• Revisar configuración de esbuild para reducir tamaño: minify en runtime zip, sourcemaps opcionales, splitting si aporta valor, tree shaking real y separación de bundles pesados.
• Revisar qué assets se copian apublic/vendor/ y asegurar que solo se incluyen los necesarios para ejecución.
• Reorganizar scripts/ con orquestadores simples en la raíz (build.mjs, setup.mjs, check.mjs, clean.mjs) y pasos internos en build/, setup/, check/ y clean/.
• Eliminar duplicación del runtime Transformers entre hilo principal y worker LLM. Hoy public/assets/chat/ai-sdk-browser.mjs (~1,1 MB minificado) y public/assets/chat/workers/llm-browser-ai.worker.mjs (~557 KB) empaquetan por separado @huggingface/transformers, onnxruntime-web y @browser-ai/transformers-js (~1,2 MB de código repetido en disco y, al activar inferencia local, dos copias parseadas en memoria). Elaborar un plan de refactor antes de tocar build:
  • Auditar qué usa realmente el bundle principal frente al worker (entry.ts vs llm-browser-ai.worker.ts, imports desde ai-sdk-bridge.ts y middlewares AI SDK).
  • Objetivo: una sola copia del stack de inferencia; el hilo principal solo expone API del AI SDK (Ollama, orquestación, tools) sin cargar Transformers.js salvo que sea estrictamente necesario.
  • Opciones a comparar: (a) mover toda inferencia Transformers.js al worker y comunicar por postMessage/Comlink; (b) worker único con cola de peticiones y main sin imports de @huggingface/transformers; (c) chunk compartido servido una vez (import map o bundle externo cacheable) si el worker puede reutilizarlo sin reparsear.
  • Validar compatibilidad con WebGPU/WASM, fallback tras fallo GPU, recarga del worker (disposeGenerationCacheBeforeGenerate) y modelos Ollama (no deben verse afectados).
  • Medir antes/después con metafile esbuild y gzip: tamaño total LLM, tiempo de primera inferencia y pico de memoria en DevTools (main + worker).
  • Documentar la arquitectura elegida en comentarios del build (llm-browser-bundles.mjs) y criterio de aceptación: reducción clara del peso combinado y una sola instancia del runtime ONNX/Transformers en runtime local.
  • Resuelto en refactor/single-transformers-runtime: main usa adapter AI SDK ligero + cola postMessage; el runtime Transformers/ONNX queda solo en el worker.

Calidad y tests

• CI mínimo en GitHub: workflow que ejecute npm run check (y, si encaja, npm run build) en push y pull requests a main.
• Definir e introducir tests automatizados más allá de npm run check: hoy solo hay validaciones estáticas (schemas, i18n, manifest, syntax). Decidir alcance (unitarios de módulos browser p. ej. i18n, tool-registry, context-budget; integración de scripts de build/check; smoke o e2e en navegador/VM), elegir runner (p. ej. Node test runner, Vitest, Playwright) e integrarlos en CI antes de una release estable.