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

autobyteus/tools/registry/tool_definition.py

@@ -38,7 +38,8 @@ class ToolDefinition:
                  config_schema_provider: Callable[[], Optional['ParameterSchema']],
                  tool_class: Optional[Type['BaseTool']] = None,
                  custom_factory: Optional[Callable[['ToolConfig'], 'BaseTool']] = None,
-                 metadata: Optional[Dict[str, Any]] = None):
+                 metadata: Optional[Dict[str, Any]] = None,
+                 description_provider: Optional[Callable[[], str]] = None):
         """
         Initializes the ToolDefinition.
         """
@@ -69,6 +70,19 @@ class ToolDefinition:
             raise ValueError(f"ToolDefinition '{name}' with origin MCP must provide a 'mcp_server_id' in its metadata.")
 
         self._name = name
+        # Prefer an explicit description provider, otherwise derive one from the tool class when available.
+        if description_provider is not None and not callable(description_provider):
+            raise TypeError(f"ToolDefinition '{name}' requires a callable for 'description_provider' if provided.")
+
+        if description_provider:
+            self._description_provider = description_provider
+        elif tool_class is not None and hasattr(tool_class, "get_description") and callable(getattr(tool_class, "get_description")):
+            # Use the tool class' get_description as a dynamic provider by default.
+            self._description_provider = tool_class.get_description
+        else:
+            # Fall back to a static description provider.
+            self._description_provider = lambda: description
+
         self._description = description
         self._tool_class = tool_class
         self._custom_factory = custom_factory
@@ -136,15 +150,42 @@ class ToolDefinition:
     def reload_cached_schema(self) -> None:
         """
         Actively re-generates the schemas from their providers and updates the cache.
-        This is an eager operation.
+        Also refreshes the description if a provider is available. This is an eager operation.
         """
         logger.info(f"Eagerly reloading schema cache for tool '{self.name}'.")
+        self._reload_description()
         self._cached_argument_schema = _CACHE_NOT_SET
         self._cached_config_schema = _CACHE_NOT_SET
         # The schemas will be regenerated on the next property access.
         # To make it fully eager, we can trigger the access here.
         _ = self.argument_schema
         _ = self.config_schema
+
+    def _reload_description(self) -> None:
+        """
+        Refreshes the cached description using the provider if available.
+        """
+        if not self._description_provider:
+            return
+        try:
+            new_description = self._description_provider()
+            if isinstance(new_description, str) and new_description:
+                if new_description != self._description:
+                    logger.info(
+                        f"Description for tool '{self.name}' updated during reload."
+                    )
+                self._description = new_description
+            else:
+                logger.warning(
+                    f"Description provider for tool '{self.name}' returned an invalid value. "
+                    "Keeping existing description."
+                )
+        except Exception as exc:
+            logger.warning(
+                f"Failed to refresh description for tool '{self.name}' during reload: {exc}. "
+                "Keeping existing description.",
+                exc_info=True
+            )
     
     # --- Convenience Schema/Example Generation API (using default formatters) ---
     def get_usage_xml(self, provider: Optional[LLMProvider] = None) -> str:

autobyteus/tools/skill/load_skill.py

@@ -0,0 +1,50 @@
+import logging
+from typing import TYPE_CHECKING
+from autobyteus.tools import tool
+from autobyteus.tools.tool_category import ToolCategory
+from autobyteus.skills.registry import SkillRegistry
+
+if TYPE_CHECKING:
+    from autobyteus.agent.context import AgentContext
+
+logger = logging.getLogger(__name__)
+
+@tool(name="load_skill", category=ToolCategory.GENERAL)
+async def load_skill(context: 'AgentContext', skill_name: str) -> str:
+    """
+    Loads a skill's entry point (SKILL.md) and provides its root path context.
+    Use this to understand a specialized skill's capabilities and internal assets.
+    
+    Args:
+        skill_name: The registered name of the skill (e.g., 'java_expert') or a path to a skill directory.
+    
+    Returns:
+        A formatted context block containing the skill's map, its absolute root path, and path resolution guidance.
+    """
+    logger.debug(f"Tool 'load_skill' called for skill: {skill_name}")
+    registry = SkillRegistry()
+    skill = registry.get_skill(skill_name)
+    
+    if not skill:
+        # Fallback: check if skill_name is actually a path
+        logger.debug(f"Skill '{skill_name}' not found in registry. Attempting to register from path.")
+        try:
+            skill = registry.register_skill_from_path(skill_name)
+        except Exception as e:
+            error_msg = f"Skill '{skill_name}' not found and is not a valid skill path: {e}"
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+
+    logger.info(f"Skill '{skill.name}' successfully loaded.")
+    return f"""## Skill: {skill.name}
+Root Path: {skill.root_path}
+
+> **CRITICAL: Path Resolution When Using Tools**
+> 
+> This skill uses relative paths. When using any tool that requires a file path,
+> you MUST first construct the full absolute path by combining the Root Path above
+> with the relative path from the skill instructions.
+> 
+> **Example:** Root Path + `./scripts/format.sh` = `{skill.root_path}/scripts/format.sh`
+
+{skill.content}"""

autobyteus/tools/terminal/__init__.py

@@ -0,0 +1,45 @@
+"""
+Terminal tools package.
+
+Provides PTY-based terminal operations for agents with stateful
+command execution and background process management.
+"""
+
+import os
+
+from autobyteus.tools.terminal.types import (
+    TerminalResult,
+    BackgroundProcessOutput,
+    ProcessInfo,
+)
+from autobyteus.tools.terminal.output_buffer import OutputBuffer
+from autobyteus.tools.terminal.prompt_detector import PromptDetector
+from autobyteus.tools.terminal.terminal_session_manager import TerminalSessionManager
+from autobyteus.tools.terminal.background_process_manager import BackgroundProcessManager
+from autobyteus.tools.terminal.session_factory import get_default_session_factory
+
+PtySession = None
+WslTmuxSession = None
+
+if os.name != "nt":
+    from autobyteus.tools.terminal.pty_session import PtySession
+else:
+    from autobyteus.tools.terminal.wsl_tmux_session import WslTmuxSession
+
+__all__ = [
+    # Types
+    "TerminalResult",
+    "BackgroundProcessOutput",
+    "ProcessInfo",
+    # Components
+    "OutputBuffer",
+    "PromptDetector",
+    "TerminalSessionManager",
+    "BackgroundProcessManager",
+    "get_default_session_factory",
+]
+
+if PtySession is not None:
+    __all__.append("PtySession")
+if WslTmuxSession is not None:
+    __all__.append("WslTmuxSession")

autobyteus/tools/terminal/ansi_utils.py

@@ -0,0 +1,32 @@
+"""
+ANSI escape sequence utilities for cleaning terminal output.
+"""
+
+import re
+
+# Regex pattern for ANSI escape sequences
+# Matches: ESC[...m (colors), ESC[...H (cursor), etc.
+_ANSI_ESCAPE_PATTERN = re.compile(r'\x1b\[[0-9;?]*[a-zA-Z]|\x1b\][^\x07]*\x07|\x1b[=>]')
+
+
+def strip_ansi_codes(text: str) -> str:
+    """Remove ANSI escape sequences from text.
+    
+    Strips color codes, cursor control, and other terminal escape
+    sequences, leaving only the plain text content.
+    
+    Args:
+        text: String potentially containing ANSI escape codes.
+        
+    Returns:
+        Clean string with ANSI codes removed.
+        
+    Examples:
+        >>> strip_ansi_codes('\x1b[31mRed text\x1b[0m')
+        'Red text'
+        >>> strip_ansi_codes('Hello\x1b[1;32m World\x1b[0m')
+        'Hello World'
+    """
+    if not text:
+        return text
+    return _ANSI_ESCAPE_PATTERN.sub('', text)

autobyteus/tools/terminal/background_process_manager.py

@@ -0,0 +1,233 @@
+"""
+Background Process Manager for long-running processes.
+
+Manages multiple PTY sessions for background processes like servers,
+with output buffering and lifecycle management.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+import uuid
+from typing import Callable, Dict, Optional
+
+from autobyteus.tools.terminal.output_buffer import OutputBuffer
+from autobyteus.tools.terminal.session_factory import get_default_session_factory
+from autobyteus.tools.terminal.types import BackgroundProcessOutput, ProcessInfo
+from autobyteus.tools.terminal.ansi_utils import strip_ansi_codes
+
+logger = logging.getLogger(__name__)
+
+
+class BackgroundProcess:
+    """Wrapper for a background process with its PTY and output buffer."""
+    
+    def __init__(
+        self,
+        process_id: str,
+        command: str,
+        session: object,
+        output_buffer: OutputBuffer
+    ):
+        self.process_id = process_id
+        self.command = command
+        self.session = session
+        self.output_buffer = output_buffer
+        self.started_at = time.time()
+        self._reader_task: Optional[asyncio.Task] = None
+    
+    @property
+    def is_running(self) -> bool:
+        return self.session.is_alive
+    
+    def to_info(self) -> ProcessInfo:
+        return ProcessInfo(
+            process_id=self.process_id,
+            command=self.command,
+            started_at=self.started_at,
+            is_running=self.is_running
+        )
+
+
+class BackgroundProcessManager:
+    """Manages background processes (servers, watchers, etc.).
+    
+    Each background process runs in its own PTY session with
+    continuous output buffering.
+    """
+    
+    def __init__(
+        self,
+        session_factory: Callable[[str], object] = None,
+        max_output_bytes: int = 1_000_000
+    ):
+        """Initialize the background process manager.
+        
+        Args:
+            session_factory: Factory function to create PtySession instances.
+            max_output_bytes: Maximum bytes to buffer per process.
+        """
+        self._session_factory = session_factory or get_default_session_factory()
+        self._max_output_bytes = max_output_bytes
+        self._processes: Dict[str, BackgroundProcess] = {}
+        self._counter = 0
+    
+    def _generate_id(self) -> str:
+        """Generate a unique process ID."""
+        self._counter += 1
+        return f"bg_{self._counter:03d}"
+    
+    async def start_process(self, command: str, cwd: str) -> str:
+        """Start a long-running process in the background.
+        
+        Args:
+            command: The command to run.
+            cwd: Working directory for the process.
+            
+        Returns:
+            Process ID that can be used to reference this process.
+        """
+        process_id = self._generate_id()
+        session_id = f"bg-{uuid.uuid4().hex[:8]}"
+        
+        session = self._session_factory(session_id)
+        output_buffer = OutputBuffer(max_bytes=self._max_output_bytes)
+        
+        # Start the session
+        await session.start(cwd)
+        
+        # Create process wrapper
+        bg_process = BackgroundProcess(
+            process_id=process_id,
+            command=command,
+            session=session,
+            output_buffer=output_buffer
+        )
+        
+        # Write the command
+        if not command.endswith('\n'):
+            command += '\n'
+        await session.write(command.encode('utf-8'))
+        
+        # Start background reader task
+        bg_process._reader_task = asyncio.create_task(
+            self._read_loop(bg_process)
+        )
+        
+        self._processes[process_id] = bg_process
+        logger.info(f"Started background process {process_id}: {command.strip()}")
+        
+        return process_id
+    
+    async def _read_loop(self, process: BackgroundProcess) -> None:
+        """Background task that continuously reads output from the PTY.
+        
+        Args:
+            process: The background process to read from.
+        """
+        try:
+            while process.session.is_alive:
+                try:
+                    data = await process.session.read(timeout=0.1)
+                    if data:
+                        process.output_buffer.append(data)
+                except Exception as e:
+                    logger.debug(f"Read error for {process.process_id}: {e}")
+                    break
+                
+                await asyncio.sleep(0.05)
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            logger.error(f"Error in read loop for {process.process_id}: {e}")
+    
+    def get_output(
+        self,
+        process_id: str,
+        lines: int = 100
+    ) -> BackgroundProcessOutput:
+        """Get recent output from a background process.
+        
+        Args:
+            process_id: ID of the process.
+            lines: Number of recent lines to return.
+            
+        Returns:
+            BackgroundProcessOutput with output and status.
+            
+        Raises:
+            KeyError: If process_id not found.
+        """
+        if process_id not in self._processes:
+            raise KeyError(f"Process {process_id} not found")
+        
+        process = self._processes[process_id]
+        raw_output = process.output_buffer.get_lines(lines)
+        clean_output = strip_ansi_codes(raw_output)
+        return BackgroundProcessOutput(
+            output=clean_output,
+            is_running=process.is_running,
+            process_id=process_id
+        )
+    
+    async def stop_process(self, process_id: str) -> bool:
+        """Stop a background process.
+        
+        Sends SIGTERM, then SIGKILL if necessary.
+        
+        Args:
+            process_id: ID of the process to stop.
+            
+        Returns:
+            True if process was found and stopped, False if not found.
+        """
+        if process_id not in self._processes:
+            return False
+        
+        process = self._processes.pop(process_id)
+        
+        # Cancel reader task
+        if process._reader_task:
+            process._reader_task.cancel()
+            try:
+                await process._reader_task
+            except asyncio.CancelledError:
+                pass
+        
+        # Close the PTY session
+        await process.session.close()
+        
+        logger.info(f"Stopped background process {process_id}")
+        return True
+    
+    async def stop_all(self) -> int:
+        """Stop all background processes.
+        
+        Returns:
+            Number of processes stopped.
+        """
+        count = len(self._processes)
+        process_ids = list(self._processes.keys())
+        
+        for process_id in process_ids:
+            await self.stop_process(process_id)
+        
+        return count
+    
+    def list_processes(self) -> Dict[str, ProcessInfo]:
+        """List all background processes.
+        
+        Returns:
+            Dict mapping process_id to ProcessInfo.
+        """
+        return {
+            pid: proc.to_info()
+            for pid, proc in self._processes.items()
+        }
+    
+    @property
+    def process_count(self) -> int:
+        """Number of managed processes."""
+        return len(self._processes)

autobyteus/tools/terminal/output_buffer.py

@@ -0,0 +1,105 @@
+"""
+Ring buffer for capturing terminal output.
+
+Provides bounded memory storage for command output with
+support for retrieving recent lines.
+"""
+
+import threading
+from collections import deque
+from typing import List
+
+
+class OutputBuffer:
+    """Ring buffer that stores output with bounded memory.
+    
+    Thread-safe buffer for capturing terminal output. Stores data
+    up to a maximum byte limit, discarding oldest data when full.
+    
+    Attributes:
+        max_bytes: Maximum bytes to store before discarding old data.
+    """
+    
+    def __init__(self, max_bytes: int = 1_000_000):
+        """Initialize the output buffer.
+        
+        Args:
+            max_bytes: Maximum bytes to store (default 1MB).
+        """
+        self._max_bytes = max_bytes
+        self._buffer: deque = deque()
+        self._total_bytes = 0
+        self._lock = threading.Lock()
+    
+    def append(self, data: bytes) -> None:
+        """Append data to the buffer.
+        
+        If adding data would exceed max_bytes, oldest lines are
+        discarded to make room.
+        
+        Args:
+            data: Bytes to append to the buffer.
+        """
+        if not data:
+            return
+            
+        with self._lock:
+            # Decode and split by lines, keeping line endings
+            try:
+                text = data.decode('utf-8', errors='replace')
+            except Exception:
+                text = str(data)
+            
+            # Split into lines but keep partial lines
+            lines = text.splitlines(keepends=True)
+            
+            for line in lines:
+                line_bytes = len(line.encode('utf-8'))
+                self._buffer.append(line)
+                self._total_bytes += line_bytes
+            
+            # Trim oldest lines if over limit
+            while self._total_bytes > self._max_bytes and self._buffer:
+                removed = self._buffer.popleft()
+                self._total_bytes -= len(removed.encode('utf-8'))
+    
+    def get_lines(self, n: int = 100) -> str:
+        """Get the last n lines from the buffer.
+        
+        Args:
+            n: Number of lines to retrieve.
+            
+        Returns:
+            String containing the last n lines.
+        """
+        with self._lock:
+            if n >= len(self._buffer):
+                return ''.join(self._buffer)
+            return ''.join(list(self._buffer)[-n:])
+    
+    def get_all(self) -> str:
+        """Get all content from the buffer.
+        
+        Returns:
+            String containing all buffered content.
+        """
+        with self._lock:
+            return ''.join(self._buffer)
+    
+    def clear(self) -> None:
+        """Clear all content from the buffer."""
+        with self._lock:
+            self._buffer.clear()
+            self._total_bytes = 0
+    
+    @property
+    def size(self) -> int:
+        """Current size of buffer in bytes."""
+        with self._lock:
+            return self._total_bytes
+    
+    @property
+    def line_count(self) -> int:
+        """Current number of lines in buffer."""
+        with self._lock:
+            return len(self._buffer)

autobyteus/tools/terminal/prompt_detector.py

@@ -0,0 +1,63 @@
+"""
+Prompt detection for terminal command completion.
+
+Detects when a shell prompt has returned, indicating command completion.
+"""
+
+import re
+from typing import Optional
+
+
+class PromptDetector:
+    """Detects when shell prompt returns after command execution.
+    
+    Uses regex pattern matching to identify when the shell has
+    returned to a prompt state, indicating command completion.
+    """
+    
+    # Default pattern matches common prompts ending with $ or #
+    DEFAULT_PATTERN = r'[\$#]\s*$'
+    
+    def __init__(self, prompt_pattern: Optional[str] = None):
+        """Initialize the prompt detector.
+        
+        Args:
+            prompt_pattern: Regex pattern to match prompt. 
+                          Defaults to matching $ or # at end of line.
+        """
+        self._pattern = prompt_pattern or self.DEFAULT_PATTERN
+        self._compiled = re.compile(self._pattern, re.MULTILINE)
+    
+    def check(self, output: str) -> bool:
+        """Check if output ends with a prompt.
+        
+        Args:
+            output: Terminal output to check.
+            
+        Returns:
+            True if output appears to end with a prompt.
+        """
+        if not output:
+            return False
+        
+        # Check the last few lines for a prompt
+        lines = output.rstrip().split('\n')
+        if not lines:
+            return False
+        
+        last_line = lines[-1]
+        return bool(self._compiled.search(last_line))
+    
+    def set_pattern(self, pattern: str) -> None:
+        """Update the prompt pattern.
+        
+        Args:
+            pattern: New regex pattern to use.
+        """
+        self._pattern = pattern
+        self._compiled = re.compile(self._pattern, re.MULTILINE)
+    
+    @property
+    def pattern(self) -> str:
+        """Current prompt pattern."""
+        return self._pattern