Visión del proyecto — Shell Sentinel

Misión

Ofrecer un copiloto de IA nativo en terminal que mantiene sesiones SSH/SFTP persistentes, habla en lenguaje natural y acerca operaciones amigables a infraestructura crítica.

Stack técnico

• Python 3.12, Textual 8.2.8 para la TUI, Strands Agents SDK 1.61.1 y Strands Agents Tools 0.8.9 para el razonamiento conversacional, transportes MCP sobre mcp 2.x.
• Instalación reproducible con pyproject.toml y lockfiles pip-tools (make lock, make install).
• Proveedores: Bedrock, OpenAI, LM Studio, Cerebras, Mistral AI, Google Gemini y Ollama. OpenAI admite Chat Completions y Responses; se normalizan los parámetros de tokens y razonamiento por endpoint, Responses permite function tools con razonamiento activo, Mistral AI usa su SDK oficial y Google Gemini se apoya en el GeminiModel de Strands con el SDK google-genai.
• Prompt caching por proveedor (bloque cache) y un tope de turnos por instrucción (agent.max_turns, 25 por defecto) mantienen bajo control el coste y los bucles descontrolados.
• Herramientas personalizadas: remote_ssh_command, remote_sftp_transfer, local_datetime.
• Herramientas MCP Firecrawl para investigación, scraping y extracción estructurada.

Responsabilidades clave

• Centralizar la configuración en conf/; sin valores hardcodeados en código.
• Actualizar traducciones, manuales y web estática cuando cambie el comportamiento.
• Documentar proveedores personalizados y reglas de plugins; cada plugin con documentación concisa.
• Respetar políticas de seguridad (sin secretos en claro, solo variables de entorno).

Flujo de trabajo

1. Crear entorno virtual con python3.12 -m venv .venv y activarlo.
2. Instalar dependencias con make install.
3. Antes de un PR: make format, make lint, make test (pruebas unitarias más la capa end-to-end offline de tests/e2e, que ejecuta la TUI real contra un servidor SSH en proceso).
4. Si tocas la TUI, el runtime del agente o un proveedor, ejecuta opcionalmente make test-e2e-live (RUN_E2E=1 más OPENAI_API_KEY, MISTRAL_API_KEY o GEMINI_API_KEY; los escenarios MCP necesitan además FIRECRAWL_API_KEY y npx); consume tokens y nunca corre en CI.
5. Validar la TUI con make run y la web con make website-serve.

Para políticas completas consulta el manual de colaboración y la documentación de gobernanza. La web estática forma parte del contrato de documentación del producto.