# app/xulcan/tools/executors/sandbox/provider.py

import logging
from abc import ABC, abstractmethod
from typing import Dict, Any, Optional

logger = logging.getLogger("xulcan.tools.sandbox.provider")

class IsolationProvider(ABC):
    """
    Contrato estricto para cualquier tecnología de aislamiento (Docker, Firecracker, WASM).
    100% Stateless: Las implementaciones no deben guardar estado en memoria (self), 
    deben consultar la fuente de verdad (el motor subyacente).
    """

    @abstractmethod
    async def is_active(self, session_id: str) -> bool:
        """Verifica en el motor subyacente si la máquina de la sesión ya está encendida."""
        pass

    @abstractmethod
    async def start_session(self, session_id: str, workspace_path: Optional[str] = None) -> None:
        """Inicializa o despierta una máquina aislada para un session_id (run_id)."""
        pass

    @abstractmethod
    async def execute_command(self, session_id: str, command: str, timeout: int = 30) -> Dict[str, Any]:
        """
        Ejecuta un comando en la sesión viva de forma determinista.
        Retorna: {"stdout": str, "stderr": str, "exit_code": int}
        """
        pass

    @abstractmethod
    async def read_file(self, session_id: str, file_path: str) -> str:
        """Lee el contenido de un archivo del disco de la sesión."""
        pass

    @abstractmethod
    async def write_file(self, session_id: str, file_path: str, content: str) -> None:
        """Escribe un archivo en el disco duro de la sesión de forma segura."""
        pass

    @abstractmethod
    async def terminate_session(self, session_id: str) -> None:
        """Apaga y destruye el entorno efímero. Limpia recursos."""
        pass