Servicio app_main — Aplicación principal del Local Agent

{“related”: [“feature—terminal—lanzador-estable-f1”, “entity—core—service—pkg-updater”, “entity—terminal—service—sentinel-runtime”, “entity—terminal—service—saas-commands”, “entity—terminal—service—sync-throttle”], “sources”: [{“type”: “commit”, “ref”: “d20beb1”}, {“type”: “commit”, “ref”: “525fa99a539ebf6a791f8d8252c2e27cdd9b9967”, “last_seen”: “2026-08-29”}, {“type”: “code”, “ref”: “terminal/agent/app_main.py”, “last_seen”: “2026-08-29”}], “content”: ”## Descripción\n\nMódulo: terminal/agent/app_main.py \nIntroducido: v1.45.14 (Agent 2.14.0, 2026-07-07) \nContexto: Lanzador Estable (F1) — código del Agente trasladado del viejo main.py\n\nLa aplicación principal del Local Agent. Antes viajaba compilada dentro del .exe (con todas sus dependencias); ahora se distribuye como código Python dentro de paquetes app-X.Y.Z.zip firmados criptográficamente.\n\nInvocada por el bootstrap (terminal/agent/main.py) tras verificar la integridad del paquete.\n\n## Interfaz pública\n\n### Punto de entrada\n\npython\ndef main_app():\n \"\"\"Inicia la aplicación del Agente.\n \n - Carga config desde `config.py`\n - Inicia listeners: SNMP trap receiver (UDP 9162)\n - Inicia WebSocket client → SaaS (heartbeat, ordenes, consola remota)\n - Ingesta de métricas: cluster_engine, platform_mod, sentinel\n - CLI local: debug.html, terminal.html en puerto de desarrollo\n \"\"\"\n\n\n### Módulos internos que componen app_main\n\n| Módulo | Responsabilidad | Fuente |\n|--------|-----------------|--------|\n| config.py | Configuración del Agente (org ID, URL SaaS, logs) | Cargado en destino desde paquete |\n| version.py | AGENT_VERSION (leída por bootstrap para puntero de versión) | Paquete |\n| models.py | DTO/esquemas (SNMP trap, métrica de red, estado de puerto) | Paquete |\n| cluster_engine.py | Ingesta de métricas de cluster (CPU, mem, I/O) | Paquete |\n| trap_receiver.py | Listener SNMP en UDP 9162 | Paquete |\n| routes/ | Handlers WebSocket y REST (heartbeat, command, telemetría) | Paquete |\n| core/ | Utilidades de red, control de procesos, logging — incluye [[entity—terminal—service—sentinel-runtime]] (ciclo de vida del Modo Sentinel) y [[entity—terminal—service—saas-commands]] (conexión + handlers de comandos WS del SaaS) | Paquete |\n| network/ | Interrogación de dispositivos (LLDP, ARP, BGP) | Paquete |\n| platform_mod/ | Abstracción SO (Windows/Linux) | Paquete |\n| sentinel/ | Alertas y acciones automáticas | Paquete |\n| assets/ | UI estática (terminal.html, debug.html, métricas) | Paquete |\n\n## Ciclo de vida\n\n### Instalación (bootstrap)\n\n1. Bootstrap (main.py) lee puntero atómico → decide app_main.py de qué versión ejecutar\n2. Monta el zip correspondiente (current → previous → embebido)\n3. Importa app_main como módulo\n4. Invoca main_app()\n\n### Ejecución\n\n- Heartbeat periódico al SaaS: reporte de estado, solicitud de órdenes\n- SNMP listener: recibe traps de dispositivos\n- Ingesta: sondeo activo de mnemónicos (CPU, uptime, disponibilidad de servicios)\n- WebSocket: canal bidireccional para consola remota, descarga de config de red\n\n### Actualización\n\n- pkg_updater (nuevo paquete) descarga app-X.Y.Z.zip + verifica Ed25519\n- Swap de puntero en ocio → siguiente restart usa nuevo paquete\n- Rollback automático si falla: watchdog revierte puntero a previous\n\n## Refactor v2.25.1 — partición del monolito (Regla 5, 28-08-2026, PR #467)\n\napp_main.py rondaba las 677 líneas (~486 de lógica), por encima del tope de 500 LOC/módulo de la Regla 5. Se trocea en dos módulos nuevos, sin ningún cambio de comportamiento (verificado con la suite completa de tests del agente):\n\n- [[entity—terminal—service—sentinel-runtime]] (core/sentinel_runtime.py, 209 líneas) — ciclo de vida del Modo Sentinel: start_sentinel_mode, stop_sentinel_mode, _start_sync_for_sentinel, _auto_resume_sentinel, get_sentinel_info y la clase SentinelScheduler resuelta en caliente.\n- [[entity—terminal—service—saas-commands]] (core/saas_commands.py, 262 líneas) — setup_saas_connection con los 8 handlers de comandos WS del SaaS y _post_remediate_result.\n\napp_main.py queda en 274 líneas: AppState, get_uptime_str, el lifespan de FastAPI, create_app y el entry point. Los consumidores (routes/health.py, routes/saas.py, routes/sentinel.py, network/snmp.py) actualizan sus imports a los módulos nuevos.\n\n## Cambios vs. v2.13.x\n\n| Aspecto | Antes | Ahora |\n|--------|--------|------|\n| Distribución | Compilado dentro del .exe (PyInstaller, 23 MB) | Python en paquete ZIP firmado (~0,5 MB) |\n| Actualización | Descarga + ejecuta binario nuevo | Descarga + verifica paquete, swapea puntero atómico |\n| Antivirus | Bloqueaba/retenía binario recién llegado | No ve binario nuevo (el .exe no cambia) |\n| Integridad | SHA-256 del .exe servido por SaaS (comprometible) | Firma Ed25519 verificada en el bootstrap (no comprometible) |\n| Rollback | Rollback del .exe (legacy) | Rollback de puntero (atomic, sin tocar archivos) |\n\n## Migración desde v2.13.x\n\nPara máquinas con bootstrap aún no compilado:\n- Se sigue usando el schema antiguo (version + sha256 + url del .exe en manifest)\n- download_agent sigue sirviendo .exe\n- Cuando bootstrap 2.14.0 se instale, automáticamente:\n - Lee package_* del manifest\n - Descarga primer paquete\n - Futuras actualizaciones = paquetes (jamás más binarios)\n\n## Véase también\n\n- [[feature—terminal—lanzador-estable-f1]]\n- [[entity—core—service—pkg-updater]]\n- [[entity—terminal—service—sentinel-runtime]] — ciclo de vida del Modo Sentinel, extraído en v2.25.1.\n- [[entity—terminal—service—saas-commands]] — conexión y handlers WS del SaaS, extraídos en v2.25.1.\n- [[entity—terminal—service—sync-throttle]] — sincronización de métricas que arranca el Modo Sentinel.\n”}