autobyteus 1.2.1__py3-none-any.whl → 1.3.0__py3-none-any.whl

autobyteus/tools/terminal/pty_session.py

@@ -0,0 +1,241 @@
+"""
+PTY Session wrapper for stateful terminal sessions.
+
+This module provides a pseudo-terminal (PTY) abstraction that spawns
+a persistent bash shell, enabling stateful terminal operations where
+directory changes, environment variables, and shell state persist
+across commands.
+"""
+
+import asyncio
+import fcntl
+import logging
+import os
+import pty
+import select
+import signal
+import struct
+import termios
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+class PtySession:
+    """PTY session implementation using the pty module.
+    
+    Spawns a persistent bash shell that maintains state across commands.
+    
+    For testing, create a MockPtySession with the same interface (duck typing).
+    
+    Attributes:
+        session_id: Unique identifier for this session.
+    """
+    
+    def __init__(self, session_id: str):
+        """Initialize a PTY session.
+        
+        Args:
+            session_id: Unique identifier for this session.
+        """
+        self._session_id = session_id
+        self._master_fd: Optional[int] = None
+        self._pid: Optional[int] = None
+        self._closed = False
+        self._cwd: Optional[str] = None
+    
+    @property
+    def session_id(self) -> str:
+        """Unique session identifier."""
+        return self._session_id
+    
+    @property
+    def is_alive(self) -> bool:
+        """Check if the shell process is still running."""
+        if self._pid is None or self._closed:
+            return False
+        try:
+            # Check if process exists without waiting
+            pid, status = os.waitpid(self._pid, os.WNOHANG)
+            if pid == 0:
+                return True  # Process still running
+            return False  # Process exited
+        except ChildProcessError:
+            return False
+    
+    async def start(self, cwd: str) -> None:
+        """Start a bash shell in a PTY.
+        
+        Uses fork/exec to create a child process with a pseudo-terminal.
+        
+        Args:
+            cwd: Working directory for the shell.
+            
+        Raises:
+            RuntimeError: If session is already started.
+            OSError: If fork or PTY creation fails.
+        """
+        if self._master_fd is not None:
+            raise RuntimeError("Session already started")
+        
+        self._cwd = cwd
+        
+        # Create pseudo-terminal
+        master_fd, slave_fd = pty.openpty()
+        
+        pid = os.fork()
+        
+        if pid == 0:
+            # Child process
+            try:
+                os.close(master_fd)
+                os.setsid()
+                
+                # Make slave the controlling terminal
+                fcntl.ioctl(slave_fd, termios.TIOCSCTTY, 0)
+                
+                # Redirect stdin/stdout/stderr to slave
+                os.dup2(slave_fd, 0)
+                os.dup2(slave_fd, 1)
+                os.dup2(slave_fd, 2)
+                
+                if slave_fd > 2:
+                    os.close(slave_fd)
+                
+                # Set environment variables for better UX
+                os.environ['TERM'] = 'xterm-256color'
+                # Simple prompt for easier detection
+                os.environ['PS1'] = r'\w $ '
+                
+                # Change to working directory
+                os.chdir(cwd)
+                
+                # Execute bash with minimal startup
+                os.execlp('bash', 'bash', '--norc', '--noprofile', '-i')
+            except Exception as e:
+                logger.error(f"Child process error: {e}")
+                os._exit(1)
+        else:
+            # Parent process
+            os.close(slave_fd)
+            self._master_fd = master_fd
+            self._pid = pid
+            
+            # Set non-blocking mode
+            flags = fcntl.fcntl(master_fd, fcntl.F_GETFL)
+            fcntl.fcntl(master_fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)
+            
+            # Give bash a moment to start
+            await asyncio.sleep(0.1)
+            
+            logger.info(f"Started PTY session {self._session_id} (pid={pid}) in {cwd}")
+    
+    async def write(self, data: bytes) -> None:
+        """Write data to the PTY master.
+        
+        Args:
+            data: Bytes to write to the terminal.
+            
+        Raises:
+            RuntimeError: If session is closed or not started.
+        """
+        if self._closed:
+            raise RuntimeError("Session is closed")
+        if self._master_fd is None:
+            raise RuntimeError("Session not started")
+        
+        try:
+            os.write(self._master_fd, data)
+        except OSError as e:
+            logger.error(f"Error writing to PTY: {e}")
+            raise
+    
+    async def read(self, timeout: float = 0.1) -> Optional[bytes]:
+        """Read available data from the PTY.
+        
+        Uses select for non-blocking read with timeout.
+        
+        Args:
+            timeout: Maximum time to wait for data in seconds.
+            
+        Returns:
+            Bytes read from PTY, or None if no data available.
+            
+        Raises:
+            RuntimeError: If session not started.
+        """
+        if self._closed:
+            return None
+        if self._master_fd is None:
+            raise RuntimeError("Session not started")
+        
+        try:
+            # Wait for data with timeout
+            readable, _, _ = select.select([self._master_fd], [], [], timeout)
+            
+            if not readable:
+                return None
+            
+            # Read available data
+            data = os.read(self._master_fd, 4096)
+            return data if data else None
+            
+        except OSError as e:
+            if e.errno == 5:  # EIO - terminal closed
+                return None
+            logger.error(f"Error reading from PTY: {e}")
+            raise
+    
+    def resize(self, rows: int, cols: int) -> None:
+        """Resize the PTY terminal.
+        
+        Args:
+            rows: Number of rows.
+            cols: Number of columns.
+        """
+        if self._master_fd is None:
+            raise RuntimeError("Session not started")
+        if self._closed:
+            return
+        
+        try:
+            winsize = struct.pack('HHHH', rows, cols, 0, 0)
+            fcntl.ioctl(self._master_fd, termios.TIOCSWINSZ, winsize)
+            logger.debug(f"Resized PTY {self._session_id} to {rows}x{cols}")
+        except OSError as e:
+            logger.error(f"Error resizing PTY: {e}")
+    
+    async def close(self) -> None:
+        """Close the PTY and terminate the shell.
+        
+        Sends SIGTERM first, then SIGKILL if necessary.
+        """
+        if self._closed:
+            return
+        
+        self._closed = True
+        
+        if self._master_fd is not None:
+            try:
+                os.close(self._master_fd)
+            except OSError:
+                pass
+            self._master_fd = None
+        
+        if self._pid is not None:
+            try:
+                # Try graceful termination first
+                os.kill(self._pid, signal.SIGTERM)
+                # Wait briefly
+                await asyncio.sleep(0.1)
+                # Force kill if still running
+                try:
+                    os.kill(self._pid, signal.SIGKILL)
+                except ProcessLookupError:
+                    pass  # Already dead
+                os.waitpid(self._pid, 0)
+            except (ProcessLookupError, ChildProcessError):
+                pass
+            self._pid = None
+        
+        logger.info(f"Closed PTY session {self._session_id}")

autobyteus/tools/terminal/session_factory.py

@@ -0,0 +1,20 @@
+"""
+Session factory selection for terminal backends.
+"""
+
+import os
+
+
+def _is_windows() -> bool:
+    """Return True if running on Windows."""
+    return os.name == "nt"
+
+
+def get_default_session_factory():
+    """Return the default PTY session class for the current platform."""
+    if _is_windows():
+        from autobyteus.tools.terminal.wsl_tmux_session import WslTmuxSession
+        return WslTmuxSession
+
+    from autobyteus.tools.terminal.pty_session import PtySession
+    return PtySession

autobyteus/tools/terminal/terminal_session_manager.py

@@ -0,0 +1,226 @@
+"""
+Terminal Session Manager for executing commands in a stateful PTY.
+
+Provides high-level command execution with prompt detection and
+timeout handling.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+from typing import Callable, Optional
+
+from autobyteus.tools.terminal.output_buffer import OutputBuffer
+from autobyteus.tools.terminal.prompt_detector import PromptDetector
+from autobyteus.tools.terminal.session_factory import get_default_session_factory
+from autobyteus.tools.terminal.types import TerminalResult
+from autobyteus.tools.terminal.ansi_utils import strip_ansi_codes
+
+logger = logging.getLogger(__name__)
+
+
+class TerminalSessionManager:
+    """Manages the main stateful terminal session for an agent.
+    
+    Provides command execution with automatic prompt detection and
+    timeout handling. The underlying PTY maintains state between
+    commands (cd, environment variables, etc).
+    
+    Attributes:
+        current_session: The active PTY session if started.
+    """
+    
+    def __init__(
+        self,
+        session_factory: Callable[[str], object] = None,
+        prompt_detector: PromptDetector = None
+    ):
+        """Initialize the terminal session manager.
+        
+        Args:
+            session_factory: Factory function to create PtySession instances.
+                           Defaults to PtySession constructor.
+            prompt_detector: PromptDetector instance for command completion.
+                           Defaults to standard PromptDetector.
+        """
+        self._session_factory = session_factory or get_default_session_factory()
+        self._prompt_detector = prompt_detector or PromptDetector()
+        self._session: Optional[object] = None
+        self._output_buffer = OutputBuffer()
+        self._cwd: Optional[str] = None
+        self._started = False
+    
+    @property
+    def current_session(self) -> Optional[object]:
+        """The active PTY session if started."""
+        return self._session
+    
+    @property
+    def is_started(self) -> bool:
+        """True if session has been started."""
+        return self._started and self._session is not None
+    
+    async def ensure_started(self, cwd: str) -> None:
+        """Ensure the session is started.
+        
+        Creates a new session if not already started.
+        
+        Args:
+            cwd: Working directory for the shell.
+        """
+        if self._session is not None and self._session.is_alive:
+            return
+        
+        # Clean up dead session if any
+        if self._session is not None:
+            await self._session.close()
+        
+        session_id = f"term-{uuid.uuid4().hex[:8]}"
+        self._session = self._session_factory(session_id)
+        await self._session.start(cwd)
+        self._cwd = cwd
+        self._started = True
+        
+        # Drain initial prompt output
+        await self._drain_output(timeout=0.5)
+        self._output_buffer.clear()
+        
+        logger.info(f"Terminal session started in {cwd}")
+    
+    async def execute_command(
+        self,
+        command: str,
+        timeout_seconds: int = 30
+    ) -> TerminalResult:
+        """Execute a command and wait for completion.
+        
+        Writes the command to the PTY and waits for the prompt to
+        return, indicating command completion.
+        
+        Args:
+            command: The bash command to execute.
+            timeout_seconds: Maximum time to wait for completion.
+            
+        Returns:
+            TerminalResult with captured output.
+            
+        Raises:
+            RuntimeError: If session is not started.
+        """
+        if self._session is None:
+            raise RuntimeError("Session not started. Call ensure_started first.")
+        
+        # Clear buffer for this command
+        self._output_buffer.clear()
+        
+        # Ensure command ends with newline
+        if not command.endswith('\n'):
+            command += '\n'
+        
+        # Write command
+        await self._session.write(command.encode('utf-8'))
+        
+        # Wait for prompt with timeout
+        timed_out = False
+        start_time = asyncio.get_event_loop().time()
+        
+        while True:
+            elapsed = asyncio.get_event_loop().time() - start_time
+            if elapsed >= timeout_seconds:
+                timed_out = True
+                logger.warning(f"Command timed out after {timeout_seconds}s: {command.strip()}")
+                break
+            
+            # Read available output
+            try:
+                data = await self._session.read(timeout=0.1)
+                if data:
+                    self._output_buffer.append(data)
+                    
+                    # Check if prompt returned
+                    current_output = self._output_buffer.get_all()
+                    if self._prompt_detector.check(current_output):
+                        break
+            except Exception as e:
+                logger.error(f"Error reading from PTY: {e}")
+                break
+        
+        # Get captured output and strip ANSI escape codes
+        output = self._output_buffer.get_all()
+        clean_output = strip_ansi_codes(output)
+        
+        # Try to extract exit code if not timed out
+        exit_code = None
+        if not timed_out:
+            exit_code = await self._get_exit_code()
+        
+        return TerminalResult(
+            stdout=clean_output,
+            stderr="",  # PTY mixes stdout/stderr
+            exit_code=exit_code,
+            timed_out=timed_out
+        )
+    
+    async def _get_exit_code(self) -> Optional[int]:
+        """Try to get the exit code of the last command.
+        
+        Returns:
+            Exit code if successfully retrieved, None otherwise.
+        """
+        try:
+            # Clear buffer
+            self._output_buffer.clear()
+            
+            # Echo the exit code
+            await self._session.write(b"echo $?\n")
+            
+            # Wait for output
+            await asyncio.sleep(0.2)
+            await self._drain_output(timeout=0.3)
+            
+            output = self._output_buffer.get_all()
+            output = strip_ansi_codes(output)
+            
+            # Parse the exit code from output
+            lines = output.strip().split('\n')
+            for line in lines:
+                line = line.strip()
+                if line.isdigit():
+                    return int(line)
+            
+            return None
+        except Exception as e:
+            logger.debug(f"Failed to get exit code: {e}")
+            return None
+    
+    async def _drain_output(self, timeout: float = 0.5) -> None:
+        """Read and buffer all available output.
+        
+        Args:
+            timeout: Maximum time to wait for more output.
+        """
+        if self._session is None:
+            return
+            
+        start = asyncio.get_event_loop().time()
+        while asyncio.get_event_loop().time() - start < timeout:
+            try:
+                data = await self._session.read(timeout=0.05)
+                if data:
+                    self._output_buffer.append(data)
+                else:
+                    # No more data immediately available
+                    await asyncio.sleep(0.05)
+            except Exception:
+                break
+    
+    async def close(self) -> None:
+        """Close the terminal session."""
+        if self._session is not None:
+            await self._session.close()
+            self._session = None
+        self._started = False
+        self._output_buffer.clear()
+        logger.info("Terminal session closed")

autobyteus/tools/terminal/tools/__init__.py

@@ -0,0 +1,13 @@
+"""Terminal tools package - LLM-facing tool functions."""
+
+from autobyteus.tools.terminal.tools.run_bash import run_bash
+from autobyteus.tools.terminal.tools.start_background_process import start_background_process
+from autobyteus.tools.terminal.tools.get_process_output import get_process_output
+from autobyteus.tools.terminal.tools.stop_background_process import stop_background_process
+
+__all__ = [
+    "run_bash",
+    "start_background_process",
+    "get_process_output",
+    "stop_background_process",
+]

autobyteus/tools/terminal/tools/get_process_output.py

@@ -0,0 +1,81 @@
+"""
+get_process_output tool - Read output from background processes.
+
+Returns recent output from a background process started with
+start_background_process.
+"""
+
+import logging
+from typing import TYPE_CHECKING, Optional
+
+from autobyteus.tools import tool
+from autobyteus.tools.tool_category import ToolCategory
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+
+logger = logging.getLogger(__name__)
+
+
+def _get_background_manager(context: Optional['AgentContext']):
+    """Get the background process manager for this agent."""
+    from autobyteus.tools.terminal.background_process_manager import BackgroundProcessManager
+    
+    if context is None:
+        if not hasattr(_get_background_manager, '_default_manager'):
+            _get_background_manager._default_manager = BackgroundProcessManager()
+        return _get_background_manager._default_manager
+    
+    if not hasattr(context, '_background_process_manager'):
+        context._background_process_manager = BackgroundProcessManager()
+    
+    return context._background_process_manager
+
+
+@tool(name="get_process_output", category=ToolCategory.SYSTEM)
+async def get_process_output(
+    context: Optional['AgentContext'],
+    process_id: str,
+    lines: int = 100
+) -> dict:
+    """
+    Get recent output from a background process.
+
+    Use this to check what a background process (started with
+    start_background_process) is outputting. This is useful to:
+    - Verify a server started successfully
+    - Check for errors in the output
+    - Monitor progress of a long-running task
+
+    Args:
+        process_id: ID returned by start_background_process.
+        lines: Number of recent lines to return (default 100).
+
+    Returns:
+        dict with:
+        - output: Recent output lines from the process
+        - is_running: True if process is still running
+        - process_id: The process identifier
+
+    Examples:
+        - After starting "yarn dev", check output to verify server is ready
+        - Check for compilation errors in build output
+        - Monitor test runner output
+    """
+    manager = _get_background_manager(context)
+    
+    try:
+        result = manager.get_output(process_id, lines)
+        return {
+            "output": result.output,
+            "is_running": result.is_running,
+            "process_id": result.process_id
+        }
+    except KeyError:
+        logger.warning(f"Process not found: {process_id}")
+        return {
+            "output": "",
+            "is_running": False,
+            "process_id": process_id,
+            "error": f"Process '{process_id}' not found. It may have already stopped or never existed."
+        }

autobyteus/tools/terminal/tools/run_bash.py

@@ -0,0 +1,109 @@
+"""
+run_bash tool - Execute commands in a stateful terminal.
+
+This tool replaces the stateless bash_executor with a PTY-based
+implementation that maintains shell state (cd, environment variables).
+"""
+
+import logging
+from typing import TYPE_CHECKING, Optional
+
+from autobyteus.tools import tool
+from autobyteus.tools.tool_category import ToolCategory
+from autobyteus.tools.terminal.types import TerminalResult
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+
+logger = logging.getLogger(__name__)
+
+
+def _get_terminal_manager(context: Optional['AgentContext']):
+    """Get or create the terminal session manager for this agent.
+    
+    Args:
+        context: The agent context.
+        
+    Returns:
+        TerminalSessionManager instance.
+    """
+    from autobyteus.tools.terminal.terminal_session_manager import TerminalSessionManager
+    
+    if context is None:
+        # Fallback for non-agent use
+        if not hasattr(_get_terminal_manager, '_default_manager'):
+            _get_terminal_manager._default_manager = TerminalSessionManager()
+        return _get_terminal_manager._default_manager
+    
+    # Store manager in context for per-agent isolation
+    if not hasattr(context, '_terminal_session_manager'):
+        context._terminal_session_manager = TerminalSessionManager()
+    
+    return context._terminal_session_manager
+
+
+def _get_cwd(context: Optional['AgentContext']) -> str:
+    """Get the working directory for the terminal.
+    
+    Args:
+        context: The agent context.
+        
+    Returns:
+        Working directory path.
+    """
+    import tempfile
+    
+    if context and hasattr(context, 'workspace') and context.workspace:
+        try:
+            base_path = context.workspace.get_base_path()
+            if base_path and isinstance(base_path, str):
+                return base_path
+        except Exception:
+            pass
+    
+    return tempfile.gettempdir()
+
+
+@tool(name="run_bash", category=ToolCategory.SYSTEM)
+async def run_bash(
+    context: Optional['AgentContext'],
+    command: str,
+    timeout_seconds: int = 30
+) -> TerminalResult:
+    """
+    Execute a command in the terminal and wait for completion.
+
+    This tool is STATELESS. Each command runs in a fresh shell session.
+    Directory changes (cd) and environment variables (export) DO NOT persist
+    between calls. You must chain commands if state dependence is needed.
+
+    Args:
+        command: The bash command to execute.
+        timeout_seconds: Maximum time to wait for completion (default 30s).
+                        Command is killed if timeout is exceeded.
+
+    Returns:
+        TerminalResult with:
+        - stdout: Output from the command
+        - stderr: Error output (may be mixed with stdout in PTY)
+        - exit_code: Exit code if available
+        - timed_out: True if command exceeded timeout
+    
+    Examples:
+        - run_bash("ls -la")
+        - run_bash("cd src && npm install", timeout_seconds=120)  # Correct way to run in subdir
+        - run_bash("cd src; ls")  # Correct way to list subdir
+    """
+    manager = _get_terminal_manager(context)
+    cwd = _get_cwd(context)
+    
+    # Ensure session is started
+    await manager.ensure_started(cwd)
+    
+    logger.debug(f"Executing terminal command: {command}")
+    result = await manager.execute_command(command, timeout_seconds)
+    
+    if result.timed_out:
+        logger.warning(f"Command timed out: {command}")
+    
+    return result