ripperdoc 0.2.9__py3-none-any.whl → 0.2.10__py3-none-any.whl

ripperdoc/tools/background_shell.py

@@ -8,9 +8,11 @@ via the KillBash tool.
 import asyncio
 import concurrent.futures
 import contextlib
+import os
 import threading
 import time
 import uuid
+import weakref
 from dataclasses import dataclass, field
 from typing import Any, Dict, List, Optional
 
@@ -41,67 +43,271 @@ class BackgroundTask:
     done_event: asyncio.Event = field(default_factory=asyncio.Event)
 
 
-_tasks: Dict[str, BackgroundTask] = {}
-_tasks_lock = threading.Lock()
-_background_loop: Optional[asyncio.AbstractEventLoop] = None
-_background_thread: Optional[threading.Thread] = None
-_loop_lock = threading.Lock()
-_shutdown_registered = False
+DEFAULT_TASK_TTL_SEC = float(os.getenv("RIPPERDOC_BASH_TASK_TTL_SEC", "3600"))
 
 
-def _safe_log_exception(message: str, **extra: Any) -> None:
-    """Log an exception but never let logging failures bubble up."""
-    try:
-        logger.exception(message, extra=extra)
-    except (OSError, RuntimeError, ValueError):
-        pass
+class BackgroundShellManager:
+    """Manager for background shell tasks with proper lifecycle control.
 
+    This class encapsulates all global state for background shell management,
+    providing better testability and proper resource cleanup.
+    """
 
-def _ensure_background_loop() -> asyncio.AbstractEventLoop:
-    """Create (or return) a dedicated loop for background processes."""
-    global _background_loop, _background_thread
+    _instance: Optional["BackgroundShellManager"] = None
+    _instance_lock = threading.Lock()
+
+    def __init__(self) -> None:
+        """Initialize the manager. Use get_instance() for singleton access."""
+        self._tasks: Dict[str, BackgroundTask] = {}
+        self._tasks_lock = threading.Lock()
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._thread: Optional[threading.Thread] = None
+        self._loop_lock = threading.Lock()
+        self._shutdown_event = threading.Event()
+        self._shutdown_registered = False
+        self._is_shutting_down = False
+
+    @classmethod
+    def get_instance(cls) -> "BackgroundShellManager":
+        """Get or create the singleton instance."""
+        if cls._instance is None:
+            with cls._instance_lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    @classmethod
+    def reset_instance(cls) -> None:
+        """Reset the singleton instance. Useful for testing.
+
+        This method shuts down the current instance and clears it,
+        allowing a fresh instance to be created on next access.
+        """
+        with cls._instance_lock:
+            if cls._instance is not None:
+                cls._instance.shutdown()
+                cls._instance = None
+
+    @classmethod
+    def _set_instance_for_testing(cls, instance: Optional["BackgroundShellManager"]) -> None:
+        """Set a custom instance for testing purposes."""
+        with cls._instance_lock:
+            cls._instance = instance
+
+    @property
+    def tasks(self) -> Dict[str, BackgroundTask]:
+        """Access to tasks dict (for internal use)."""
+        return self._tasks
+
+    @property
+    def tasks_lock(self) -> threading.Lock:
+        """Access to tasks lock (for internal use)."""
+        return self._tasks_lock
+
+    def ensure_loop(self) -> asyncio.AbstractEventLoop:
+        """Create (or return) a dedicated loop for background processes."""
+        if self._loop and self._loop.is_running():
+            return self._loop
+
+        with self._loop_lock:
+            if self._loop and self._loop.is_running():
+                return self._loop
+
+            loop = asyncio.new_event_loop()
+            ready = threading.Event()
+            shutdown_event = self._shutdown_event
+
+            def _run_loop() -> None:
+                asyncio.set_event_loop(loop)
+                ready.set()
+                try:
+                    loop.run_forever()
+                finally:
+                    # Ensure cleanup happens even if loop is stopped abruptly
+                    shutdown_event.set()
+
+            # Use non-daemon thread to ensure atexit handlers can complete
+            thread = threading.Thread(
+                target=_run_loop,
+                name="ripperdoc-bg-loop",
+                daemon=False,  # Non-daemon for proper shutdown
+            )
+            thread.start()
+            ready.wait()
+
+            self._loop = loop
+            self._thread = thread
+            self._register_shutdown_hook()
+            return loop
+
+    def _register_shutdown_hook(self) -> None:
+        """Register atexit handler for cleanup."""
+        if self._shutdown_registered:
+            return
+
+        # Use weakref to avoid preventing garbage collection
+        manager_ref = weakref.ref(self)
+
+        def _shutdown_callback() -> None:
+            manager = manager_ref()
+            if manager is not None:
+                manager.shutdown()
+
+        atexit.register(_shutdown_callback)
+        self._shutdown_registered = True
+
+    def submit_to_loop(self, coro: Any) -> concurrent.futures.Future:
+        """Run a coroutine on the background loop and return a thread-safe future."""
+        loop = self.ensure_loop()
+        return asyncio.run_coroutine_threadsafe(coro, loop)
+
+    def shutdown(self, force: bool = False) -> None:
+        """Stop background tasks/loop to avoid resource leaks.
+
+        Args:
+            force: If True, use minimal timeouts for faster exit.
+        """
+        if self._is_shutting_down:
+            # If already shutting down and force is requested, just mark done
+            if force:
+                self._shutdown_event.set()
+            return
+        self._is_shutting_down = True
+
+        loop = self._loop
+        thread = self._thread
+
+        if not loop or loop.is_closed():
+            self._loop = None
+            self._thread = None
+            self._is_shutting_down = False
+            return
+
+        # Use shorter timeouts for faster exit
+        async_timeout = 0.5 if force else 2.0
+        join_timeout = 0.5 if force else 1.0
 
-    if _background_loop and _background_loop.is_running():
-        return _background_loop
+        try:
+            if loop.is_running():
+                try:
+                    fut = asyncio.run_coroutine_threadsafe(
+                        self._shutdown_loop_async(loop, force=force), loop
+                    )
+                    fut.result(timeout=async_timeout)
+                except (RuntimeError, TimeoutError, concurrent.futures.TimeoutError):
+                    logger.debug("Failed to cleanly shutdown background loop", exc_info=True)
+                try:
+                    loop.call_soon_threadsafe(loop.stop)
+                except (RuntimeError, OSError):
+                    logger.debug("Failed to stop background loop", exc_info=True)
+            else:
+                # If loop isn't running, try to run cleanup synchronously
+                try:
+                    loop.run_until_complete(self._shutdown_loop_async(loop, force=force))
+                except RuntimeError:
+                    pass  # Loop may already be closed
+        finally:
+            if thread and thread.is_alive():
+                thread.join(timeout=join_timeout)
+                # If thread is still alive after timeout, don't block further
+                if thread.is_alive():
+                    logger.debug("Background thread did not stop in time, continuing shutdown")
+            with contextlib.suppress(Exception):
+                if not loop.is_closed():
+                    loop.close()
+            self._loop = None
+            self._thread = None
+            self._shutdown_event.set()
+            self._is_shutting_down = False
+
+    async def _shutdown_loop_async(
+        self, loop: asyncio.AbstractEventLoop, force: bool = False
+    ) -> None:
+        """Drain running background processes before stopping the loop.
+
+        Args:
+            loop: The event loop to shutdown.
+            force: If True, use minimal timeouts for faster exit.
+        """
+        with self._tasks_lock:
+            tasks = list(self._tasks.values())
+            self._tasks.clear()
+
+        # Use shorter timeouts when force is True
+        wait_timeout = 0.3 if force else 1.5
+        kill_timeout = 0.2 if force else 0.5
+
+        for task in tasks:
+            try:
+                task.killed = True
+                with contextlib.suppress(ProcessLookupError):
+                    task.process.kill()
+                try:
+                    with contextlib.suppress(ProcessLookupError):
+                        await asyncio.wait_for(task.process.wait(), timeout=wait_timeout)
+                except asyncio.TimeoutError:
+                    with contextlib.suppress(ProcessLookupError, PermissionError):
+                        task.process.kill()
+                    with contextlib.suppress(asyncio.TimeoutError, ProcessLookupError):
+                        await asyncio.wait_for(task.process.wait(), timeout=kill_timeout)
+                task.exit_code = task.process.returncode or -1
+            except (OSError, RuntimeError, asyncio.CancelledError) as exc:
+                if not isinstance(exc, asyncio.CancelledError):
+                    _safe_log_exception(
+                        "Error shutting down background task",
+                        task_id=task.id,
+                        command=task.command,
+                    )
+            finally:
+                await _finalize_reader_tasks(task.reader_tasks, timeout=0.3 if force else 1.0)
+                task.done_event.set()
+
+        current = asyncio.current_task()
+        pending = [t for t in asyncio.all_tasks(loop) if t is not current]
+        for pending_task in pending:
+            pending_task.cancel()
+        if pending:
+            with contextlib.suppress(Exception):
+                await asyncio.gather(*pending, return_exceptions=True)
 
-    with _loop_lock:
-        if _background_loop and _background_loop.is_running():
-            return _background_loop
+        with contextlib.suppress(Exception):
+            await loop.shutdown_asyncgens()
 
-        loop = asyncio.new_event_loop()
-        ready = threading.Event()
 
-        def _run_loop() -> None:
-            asyncio.set_event_loop(loop)
-            ready.set()
-            loop.run_forever()
+# Module-level functions that delegate to the singleton manager
+# These maintain backward compatibility with existing code
 
-        thread = threading.Thread(
-            target=_run_loop,
-            name="ripperdoc-bg-loop",
-            daemon=True,
-        )
-        thread.start()
-        ready.wait()
+def _get_manager() -> BackgroundShellManager:
+    """Get the singleton manager instance."""
+    return BackgroundShellManager.get_instance()
 
-        _background_loop = loop
-        _background_thread = thread
-        _register_shutdown_hook()
-        return loop
 
+def _get_tasks_lock() -> threading.Lock:
+    """Get the tasks lock from the manager."""
+    return _get_manager().tasks_lock
 
-def _register_shutdown_hook() -> None:
-    global _shutdown_registered
-    if _shutdown_registered:
-        return
-    atexit.register(shutdown_background_shell)
-    _shutdown_registered = True
+
+def _get_tasks() -> Dict[str, BackgroundTask]:
+    """Get the tasks dict from the manager."""
+    return _get_manager().tasks
+
+
+def _safe_log_exception(message: str, **extra: Any) -> None:
+    """Log an exception but never let logging failures bubble up."""
+    try:
+        logger.exception(message, extra=extra)
+    except (OSError, RuntimeError, ValueError):
+        pass
+
+
+def _ensure_background_loop() -> asyncio.AbstractEventLoop:
+    """Create (or return) a dedicated loop for background processes."""
+    return _get_manager().ensure_loop()
 
 
 def _submit_to_background_loop(coro: Any) -> concurrent.futures.Future:
     """Run a coroutine on the background loop and return a thread-safe future."""
-    loop = _ensure_background_loop()
-    return asyncio.run_coroutine_threadsafe(coro, loop)
+    return _get_manager().submit_to_loop(coro)
 
 
 async def _pump_stream(stream: asyncio.StreamReader, sink: List[str]) -> None:
@@ -112,7 +318,7 @@ async def _pump_stream(stream: asyncio.StreamReader, sink: List[str]) -> None:
             if not chunk:
                 break
             text = chunk.decode("utf-8", errors="replace")
-            with _tasks_lock:
+            with _get_tasks_lock():
                 sink.append(text)
     except (OSError, RuntimeError, asyncio.CancelledError) as exc:
         if isinstance(exc, asyncio.CancelledError):
@@ -147,15 +353,15 @@ async def _monitor_task(task: BackgroundTask) -> None:
             await asyncio.wait_for(task.process.wait(), timeout=task.timeout)
         else:
             await task.process.wait()
-        with _tasks_lock:
+        with _get_tasks_lock():
             task.exit_code = task.process.returncode
     except asyncio.TimeoutError:
         logger.warning(f"Background task {task.id} timed out after {task.timeout}s: {task.command}")
-        with _tasks_lock:
+        with _get_tasks_lock():
             task.timed_out = True
         task.process.kill()
         await task.process.wait()
-        with _tasks_lock:
+        with _get_tasks_lock():
             task.exit_code = -1
     except asyncio.CancelledError:
         return
@@ -166,7 +372,7 @@ async def _monitor_task(task: BackgroundTask) -> None:
             exc,
             extra={"task_id": task.id, "command": task.command},
         )
-        with _tasks_lock:
+        with _get_tasks_lock():
             task.exit_code = -1
     finally:
         # Ensure readers are finished before marking done.
@@ -196,8 +402,8 @@ async def _start_background_command(
         start_time=_loop_time(),
         timeout=timeout,
     )
-    with _tasks_lock:
-        _tasks[task_id] = record
+    with _get_tasks_lock():
+        _get_tasks()[task_id] = record
 
     # Start stream pumps and monitor task.
     if process.stdout:
@@ -247,11 +453,12 @@ def get_background_status(task_id: str, consume: bool = True) -> dict:
 
     If consume is True, buffered stdout/stderr are cleared after reading.
     """
-    with _tasks_lock:
-        if task_id not in _tasks:
+    tasks = _get_tasks()
+    with _get_tasks_lock():
+        if task_id not in tasks:
             raise KeyError(f"No background task found with id '{task_id}'")
 
-        task = _tasks[task_id]
+        task = tasks[task_id]
         stdout = "".join(task.stdout_chunks)
         stderr = "".join(task.stderr_chunks)
 
@@ -277,8 +484,9 @@ async def kill_background_task(task_id: str) -> bool:
     KILL_WAIT_SECONDS = 2.0
 
     async def _kill(task_id: str) -> bool:
-        with _tasks_lock:
-            task = _tasks.get(task_id)
+        tasks = _get_tasks()
+        with _get_tasks_lock():
+            task = tasks.get(task_id)
             if not task:
                 return False
 
@@ -296,7 +504,7 @@ async def kill_background_task(task_id: str) -> bool:
                     task.process.kill()
                 await asyncio.wait_for(task.process.wait(), timeout=1.0)
 
-            with _tasks_lock:
+            with _get_tasks_lock():
                 task.exit_code = task.process.returncode or -1
             return True
         finally:
@@ -309,82 +517,45 @@ async def kill_background_task(task_id: str) -> bool:
 
 def list_background_tasks() -> List[str]:
     """Return known background task ids."""
-    with _tasks_lock:
-        return list(_tasks.keys())
-
-
-async def _shutdown_loop(loop: asyncio.AbstractEventLoop) -> None:
-    """Drain running background processes before stopping the loop."""
-    with _tasks_lock:
-        tasks = list(_tasks.values())
-        _tasks.clear()
-
-    for task in tasks:
-        try:
-            task.killed = True
-            with contextlib.suppress(ProcessLookupError):
-                task.process.kill()
-            try:
-                with contextlib.suppress(ProcessLookupError):
-                    await asyncio.wait_for(task.process.wait(), timeout=1.5)
-            except asyncio.TimeoutError:
-                with contextlib.suppress(ProcessLookupError, PermissionError):
-                    task.process.kill()
-                with contextlib.suppress(asyncio.TimeoutError, ProcessLookupError):
-                    await asyncio.wait_for(task.process.wait(), timeout=0.5)
-            task.exit_code = task.process.returncode or -1
-        except (OSError, RuntimeError, asyncio.CancelledError) as exc:
-            if not isinstance(exc, asyncio.CancelledError):
-                _safe_log_exception(
-                    "Error shutting down background task",
-                    task_id=task.id,
-                    command=task.command,
-                )
-        finally:
-            await _finalize_reader_tasks(task.reader_tasks)
-            task.done_event.set()
-
-    current = asyncio.current_task()
-    pending = [t for t in asyncio.all_tasks(loop) if t is not current]
-    for pending_task in pending:
-        pending_task.cancel()
-    if pending:
-        with contextlib.suppress(Exception):
-            await asyncio.gather(*pending, return_exceptions=True)
-
-    with contextlib.suppress(Exception):
-        await loop.shutdown_asyncgens()
-
-
-def shutdown_background_shell() -> None:
-    """Stop background tasks/loop to avoid asyncio 'Event loop is closed' warnings."""
-    global _background_loop, _background_thread
+    _prune_background_tasks()
+    with _get_tasks_lock():
+        return list(_get_tasks().keys())
+
+
+def _prune_background_tasks(max_age_seconds: Optional[float] = None) -> int:
+    """Remove finished background tasks older than the TTL."""
+    ttl = DEFAULT_TASK_TTL_SEC if max_age_seconds is None else max_age_seconds
+    if ttl is None or ttl <= 0:
+        return 0
+    now = _loop_time()
+    removed = 0
+    tasks = _get_tasks()
+    with _get_tasks_lock():
+        for task_id, task in list(tasks.items()):
+            if task.exit_code is None:
+                continue
+            age = (now - task.start_time) if task.start_time else 0.0
+            if age > ttl:
+                tasks.pop(task_id, None)
+                removed += 1
+    return removed
+
+
+def shutdown_background_shell(force: bool = False) -> None:
+    """Stop background tasks/loop to avoid asyncio 'Event loop is closed' warnings.
+
+    This function maintains backward compatibility by delegating to the manager.
+
+    Args:
+        force: If True, use minimal timeouts for faster exit.
+    """
+    _get_manager().shutdown(force=force)
 
-    loop = _background_loop
-    thread = _background_thread
 
-    if not loop or loop.is_closed():
-        _background_loop = None
-        _background_thread = None
-        return
+def reset_background_shell_for_testing() -> None:
+    """Reset all background shell state. Useful for testing.
 
-    try:
-        if loop.is_running():
-            try:
-                fut = asyncio.run_coroutine_threadsafe(_shutdown_loop(loop), loop)
-                fut.result(timeout=3)
-            except (RuntimeError, TimeoutError, concurrent.futures.TimeoutError):
-                logger.debug("Failed to cleanly shutdown background loop", exc_info=True)
-            try:
-                loop.call_soon_threadsafe(loop.stop)
-            except (RuntimeError, OSError):
-                logger.debug("Failed to stop background loop", exc_info=True)
-        else:
-            loop.run_until_complete(_shutdown_loop(loop))
-    finally:
-        if thread and thread.is_alive():
-            thread.join(timeout=2)
-        with contextlib.suppress(Exception):
-            loop.close()
-        _background_loop = None
-        _background_thread = None
+    This function shuts down the current manager instance and clears it,
+    allowing a fresh instance to be created on next access.
+    """
+    BackgroundShellManager.reset_instance()

ripperdoc/tools/bash_tool.py

@@ -41,7 +41,6 @@ from ripperdoc.utils.output_utils import (
     truncate_output,
 )
 from ripperdoc.utils.permissions.path_validation_utils import validate_shell_command_paths
-from ripperdoc.utils.permissions.shell_command_validation import validate_shell_command
 from ripperdoc.utils.permissions.tool_permission_utils import (
     evaluate_shell_command_permissions,
     is_command_read_only,
@@ -341,9 +340,8 @@ build projects, run tests, and interact with the file system."""
             allow_rules,
             deny_rules,
             allowed_dirs,
-            command_injection_detected=False,
-            injection_detector=lambda cmd: validate_shell_command(cmd).behavior != "passthrough",
-            read_only_detector=lambda cmd, detector: is_command_read_only(cmd),
+            # danger_detector uses default: validate_shell_command(cmd).behavior != "passthrough"
+            # read_only_detector uses default: _is_command_read_only
         )
 
         # Background executions need an explicit confirmation even if heuristics
@@ -384,6 +382,43 @@ build projects, run tests, and interact with the file system."""
                 result=False, message="Sandbox mode requested but not available."
             )
 
+        # Validate shell_executable if provided
+        if input_data.shell_executable:
+            shell_path = Path(input_data.shell_executable)
+            # Must be an absolute path
+            if not shell_path.is_absolute():
+                return ValidationResult(
+                    result=False,
+                    message=f"shell_executable must be an absolute path: {input_data.shell_executable}",
+                )
+            # Must exist and be a file
+            if not shell_path.exists():
+                return ValidationResult(
+                    result=False,
+                    message=f"shell_executable not found: {input_data.shell_executable}",
+                )
+            if not shell_path.is_file():
+                return ValidationResult(
+                    result=False,
+                    message=f"shell_executable is not a file: {input_data.shell_executable}",
+                )
+            # Must be executable
+            if not os.access(shell_path, os.X_OK):
+                return ValidationResult(
+                    result=False,
+                    message=f"shell_executable is not executable: {input_data.shell_executable}",
+                )
+            # Must be in a safe system directory or match known shell patterns
+            safe_dirs = {"/bin", "/usr/bin", "/usr/local/bin", "/opt/homebrew/bin"}
+            shell_name = shell_path.name.lower()
+            known_shells = {"bash", "sh", "zsh", "fish", "dash", "ksh", "tcsh", "csh"}
+            parent_dir = str(shell_path.parent)
+            if parent_dir not in safe_dirs and shell_name not in known_shells:
+                return ValidationResult(
+                    result=False,
+                    message=f"shell_executable must be a known shell in a standard location: {input_data.shell_executable}",
+                )
+
         # Note: Path validation for sensitive directories (cd/find to /usr, /etc, etc.)
         # is now handled in check_permissions() to allow user confirmation for read-only ops.
 
@@ -396,15 +431,9 @@ build projects, run tests, and interact with the file system."""
                     result=False, message="This command cannot be run in background"
                 )
 
-        validation = validate_shell_command(input_data.command)
-        if validation.behavior == "ask":
-            # In yolo mode, allow shell metacharacters
-            if context and hasattr(context, 'yolo_mode') and context.yolo_mode \
-               and "shell metacharacters" in validation.message:
-                # Allow commands with shell metacharacters in yolo mode
-                return ValidationResult(result=True)
-            return ValidationResult(result=False, message=validation.message)
-
+        # Note: Security validation (shell metacharacters, destructive commands, etc.)
+        # is handled in check_permissions() via evaluate_shell_command_permissions().
+        # validate_input() should only perform format/parameter validation.
         return ValidationResult(result=True)
 
     def render_result_for_assistant(self, output: BashToolOutput) -> str: