aip-agents-binary 0.0.0__py3-none-any.whl

aip_agents/middleware/tools/execute.py

@@ -0,0 +1,428 @@
+"""Execute tool for running shell commands with artifact tracking.
+
+This module provides the ExecuteTool class that wraps backend command execution
+with a LangChain tool interface, including timeout handling, output formatting,
+and artifact tracking for files created during execution.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from contextlib import AsyncExitStack, asynccontextmanager
+from functools import lru_cache
+from pathlib import Path
+from typing import Annotated, Any, cast
+
+from langchain_core.tools import BaseTool
+from langgraph.types import Command
+from pydantic import BaseModel, Field, SkipValidation
+
+from aip_agents.common.callable_introspection import callable_accepts_keyword
+from aip_agents.middleware.backends.protocol import BackendProtocol, ExecuteResult
+from aip_agents.middleware.schema import MiddlewareToolConfig
+from aip_agents.utils.artifacts import ArtifactTracker
+from aip_agents.utils.file_watchers import FileWatcherStrategy, SandboxArtifactWatcher, create_local_strategy
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class ExecuteInput(BaseModel):
+    """Input schema for the execute tool.
+
+    Attributes:
+        command: The shell command to execute.
+        timeout: Timeout in seconds (optional, defaults to 30).
+    """
+
+    command: str = Field(description="Shell command to execute")
+    timeout: int = Field(default=30, description="Timeout in seconds", ge=1)
+
+
+class ExecuteTool(BaseTool):
+    """Tool for executing shell commands via backend with artifact tracking.
+
+    This tool wraps backend command execution with proper timeout handling,
+    output formatting, and artifact tracking for files created during execution.
+
+    Attributes:
+        name: Tool name ('execute').
+        description: Tool description for LLM.
+        args_schema: Input schema class.
+        backend: BackendProtocol instance for execution.
+        max_execute_timeout: Maximum allowed timeout in seconds.
+    """
+
+    name: str = "execute"
+    description: str = (
+        "Execute a shell command. Returns stdout/stderr with exit code. "
+        "Use timeout parameter for long-running commands. "
+        "Creates artifacts for any files generated during execution."
+    )
+    args_schema: type[BaseModel] = ExecuteInput  # type: ignore[assignment]
+    tool_config_schema: type[BaseModel] = MiddlewareToolConfig
+    backend: Annotated[BackendProtocol, SkipValidation()]  # BackendProtocol type with validation skipped for Protocol
+    max_execute_timeout: int = 300
+
+    async def _arun(self, command: str, timeout: int = 30) -> Command | str:
+        """Execute a command with artifact tracking (async).
+
+        Args:
+            command: Shell command to execute.
+            timeout: Timeout in seconds.
+
+        Returns:
+            Command with artifacts if files created,
+            otherwise formatted result string.
+        """
+        timeout = self._clamp_timeout(timeout)
+
+        if not self._backend_supports_execution():
+            return (
+                "Error: Execution not available. This agent's backend "
+                "does not support command execution. "
+                "To use the execute tool, provide a backend that implements "
+                "the execute() method."
+            )
+
+        backend_class = type(self.backend)
+        execute_fn = getattr(self.backend, "execute", None)
+        supports_timeout = ExecuteTool._execute_accepts_timeout(backend_class) or callable_accepts_keyword(
+            execute_fn, "timeout"
+        )
+        if not supports_timeout:
+            return (
+                "Error: This backend does not support per-command timeout "
+                "overrides. Update your backend package or omit the timeout parameter."
+            )
+
+        try:
+            return await self._arun_with_tracking(command, timeout)
+        except NotImplementedError as e:
+            return f"Error: Execution not available. {e}"
+        except ValueError as e:
+            return f"Error: Invalid parameter. {e}"
+        except Exception as e:
+            return f"Error: Execution failed. {str(e)}"
+
+    def _run(self, command: str, timeout: int = 30) -> Command | str:
+        """Execute a command synchronously with artifact tracking.
+
+        Args:
+            command: Shell command to execute.
+            timeout: Timeout in seconds.
+
+        Returns:
+            Command with artifacts (if files created) or error message string.
+        """
+        backend = cast(Any, self.backend)
+        run_sync = getattr(backend, "_run_sync", None)
+        if callable(run_sync):
+            return run_sync(self._arun(command, timeout=timeout))
+        return asyncio.run(self._arun(command, timeout=timeout))
+
+    def _clamp_timeout(self, timeout: int) -> int:
+        """Clamp timeout to valid range.
+
+        Args:
+            timeout: Requested timeout in seconds.
+
+        Returns:
+            Timeout clamped between 1 and max_execute_timeout.
+        """
+        return max(1, min(timeout, self.max_execute_timeout))
+
+    def _backend_supports_execution(self) -> bool:
+        """Check if backend supports execution.
+
+        Returns:
+            True if backend has callable execute method.
+        """
+        return hasattr(self.backend, "execute") and callable(getattr(self.backend, "execute"))
+
+    @staticmethod
+    @lru_cache(maxsize=128)
+    def _execute_accepts_timeout(backend_class: type) -> bool:
+        """Check if backend class execute accepts timeout parameter."""
+        execute_fn = getattr(backend_class, "execute", None)
+        return callable_accepts_keyword(execute_fn, "timeout")
+
+    async def _arun_with_tracking(self, command: str, timeout: int) -> Command:
+        """Execute with artifact tracking using context manager.
+
+        Args:
+            command: Shell command to execute.
+            timeout: Timeout in seconds.
+
+        Returns:
+            Command with execution result and artifacts.
+        """
+        # Initialize the runtime first so a lazily-resolved base_dir (e.g. the
+        # sandbox backend's $HOME/workspace resolution) is settled before we read
+        # it; otherwise the tracker would watch the stale default directory.
+        if hasattr(self.backend, "ensure_runtime"):
+            await self.backend.ensure_runtime()
+
+        # Get base directory from backend
+        base_dir = self._get_backend_base_dir()
+        if not base_dir:
+            # Fallback to execute without tracking
+            result = await self._aexecute_backend(command, timeout)
+            return self._format_result_as_command(result, [])
+
+        # Create watcher strategy
+        strategy = await self._create_watcher_strategy()
+
+        async with self._tracker_with_fallback(base_dir, strategy) as tracker:
+            return await self._execute_with_tracker(command, timeout, tracker)
+
+    @asynccontextmanager
+    async def _tracker_with_fallback(
+        self, base_dir: str, strategy: FileWatcherStrategy
+    ) -> AsyncIterator[ArtifactTracker]:
+        """Context manager that yields an ArtifactTracker using the given strategy.
+
+        Falls back to a non-watchdog strategy if the given strategy fails to initialize
+        (e.g. due to missing dependencies or OS limitations).
+
+        Args:
+            base_dir: Base directory to watch for artifacts.
+            strategy: Primary file watcher strategy to use.
+
+        Yields:
+            An initialized ArtifactTracker instance.
+        """
+        stack = AsyncExitStack()
+        tracker = self._make_tracker(base_dir, strategy)
+        try:
+            active_tracker = await stack.enter_async_context(tracker)
+        except (ImportError, OSError) as exc:
+            await stack.aclose()
+            logger.warning(
+                "Watchdog watcher unavailable (%s), falling back to LsDiffWatcher",
+                exc,
+            )
+            file_lister = self._get_file_lister()
+            fallback = create_local_strategy(file_lister, use_watchdog=False)
+            fallback_tracker = self._make_tracker(base_dir, fallback)
+            stack = AsyncExitStack()
+            active_tracker = await stack.enter_async_context(fallback_tracker)
+
+        try:
+            yield active_tracker
+        finally:
+            await stack.aclose()
+
+    def _make_tracker(self, base_dir: str, strategy: FileWatcherStrategy) -> ArtifactTracker:
+        """Helper to create an ArtifactTracker with the given strategy."""
+        return ArtifactTracker(
+            base_dir=base_dir,
+            file_reader=self._read_file_bytes,
+            watcher_strategy=strategy,
+        )
+
+    async def _execute_with_tracker(self, command: str, timeout: int, tracker: ArtifactTracker) -> Command:
+        """Execute command and track artifacts using the given tracker.
+
+        Args:
+            command: Shell command to execute.
+            timeout: Timeout in seconds.
+            tracker: Initialized ArtifactTracker instance.
+
+        Returns:
+            Command with execution result and artifacts.
+        """
+        result = await self._aexecute_backend(command, timeout)
+        created_files = await tracker.collect()
+
+        if created_files:
+            file_cache = await self._aread_file_cache(created_files)
+            tracker._file_reader = lambda p, _c=file_cache: _c[p]  # type: ignore[method-assign]
+
+        artifacts, errors = tracker.build_artifacts(created_files)
+        return self._format_result_as_command(result, artifacts, errors)
+
+    def _read_file_bytes(self, path: str) -> bytes:
+        """Read file as bytes using backend (synchronous fallback).
+
+        Used as the initial ``file_reader`` passed to ``ArtifactTracker``.  For
+        backends that only expose an async API (e.g. ``SandboxBackend``), the
+        caller should replace ``tracker._file_reader`` with a cache-backed
+        synchronous lambda after pre-reading the files asynchronously via
+        :meth:`_aread_file_cache`.  That avoids running async E2B client calls
+        from a sync callback that runs in a different event loop.
+
+        Args:
+            path: File path to read.
+
+        Returns:
+            File content as bytes.
+
+        Raises:
+            FileNotFoundError: If file not found.
+            PermissionError: If file not readable.
+            IsADirectoryError: If path is a directory.
+        """
+        backend = cast(Any, self.backend)
+
+        if hasattr(backend, "read_bytes") and callable(getattr(backend, "read_bytes")):
+            return backend.read_bytes(path)
+
+        content = backend.read(path)
+        return content.encode("utf-8")
+
+    async def _aread_file_bytes(self, path: str) -> bytes:
+        """Read file as bytes using the async backend API.
+
+        Args:
+            path: File path to read.
+
+        Returns:
+            File content as bytes.
+        """
+        backend = cast(Any, self.backend)
+
+        if hasattr(backend, "aread_bytes") and callable(getattr(backend, "aread_bytes")):
+            return await backend.aread_bytes(path)
+
+        if hasattr(backend, "read_bytes") and callable(getattr(backend, "read_bytes")):
+            return await asyncio.to_thread(backend.read_bytes, path)
+
+        content = await asyncio.to_thread(backend.read, path)
+        return content.encode("utf-8")
+
+    async def _aread_file_cache(self, paths: list[str]) -> dict[str, bytes]:
+        """Pre-read multiple files asynchronously into an in-memory cache.
+
+        Files that cannot be read are omitted from the returned dict; the
+        caller's ``file_reader`` lambda will raise ``KeyError`` for those paths
+        which ``ArtifactTracker.build_artifacts`` catches and converts to error
+        entries.
+
+        Args:
+            paths: Absolute file paths to read.
+
+        Returns:
+            Mapping of path → raw bytes for every file that was read
+            successfully.
+        """
+        cache: dict[str, bytes] = {}
+        for path in paths:
+            try:
+                cache[path] = await self._aread_file_bytes(path)
+            except Exception as exc:
+                logger.warning("Failed to read file %s: %s: %s", path, type(exc).__name__, exc)
+        return cache
+
+    async def _aexecute_backend(self, command: str, timeout: int) -> ExecuteResult:
+        """Execute command using the backend's async API if available, otherwise run sync execute in a thread."""
+        backend = cast(Any, self.backend)
+        if hasattr(backend, "aexecute") and callable(getattr(backend, "aexecute")):
+            return await backend.aexecute(command, timeout=timeout)
+
+        execute_fn = getattr(backend, "execute")
+        return await asyncio.to_thread(execute_fn, command, timeout=timeout)
+
+    async def _create_watcher_strategy(self) -> FileWatcherStrategy:
+        """Create and return the appropriate file watcher strategy based on the backend."""
+        try:
+            from aip_agents.middleware.backends.sandbox import SandboxBackend as sandbox_backend_type
+        except ImportError:
+            sandbox_backend_type = None
+
+        backend = cast(Any, self.backend)
+        if sandbox_backend_type is not None and isinstance(backend, sandbox_backend_type):
+            # Provider-neutral: watch via the runtime's execute_command (find -newer),
+            # so this works on any sandbox backend, not just E2B. _create_watcher_strategy
+            # runs before _aexecute_backend, so initialize the runtime first.
+            runtime = await backend._ensure_runtime()
+            return SandboxArtifactWatcher(runtime)
+
+        file_lister = self._get_file_lister()
+        return create_local_strategy(file_lister, use_watchdog=True)
+
+    def _format_result_as_command(
+        self,
+        result: ExecuteResult,
+        artifacts: list[dict[str, Any]],
+        errors: list[dict[str, str]] | None = None,
+    ) -> Command:
+        """Format execution result as Command with artifacts.
+
+        Args:
+            result: ExecuteResult from backend.
+            artifacts: List of artifact dicts.
+            errors: List of artifact error dicts.
+
+        Returns:
+            Command with result and artifacts.
+        """
+        execution_summary = self._format_result(result)
+
+        # Build response
+        response_data: dict[str, Any] = {
+            "result": execution_summary,
+            "artifacts": artifacts,
+        }
+
+        if errors:
+            response_data["artifact_errors"] = errors
+
+        # Return Command directly (not via helper to support empty artifacts)
+        return Command(update=response_data)
+
+    def _get_backend_base_dir(self) -> str | None:
+        """Get base directory from backend for artifact tracking.
+
+        Returns:
+            Base directory path or None if not available.
+        """
+        # Try common attribute names
+        for attr in ["base_path", "base_directory", "base_dir", "working_dir"]:
+            if hasattr(self.backend, attr):
+                val = getattr(self.backend, attr)
+                if isinstance(val, str | Path):
+                    return str(val)
+        return None
+
+    def _get_file_lister(self) -> Any:
+        """Get file lister callable from backend.
+
+        Returns:
+            Callable that lists files in a directory.
+
+        Raises:
+            AttributeError: If backend does not have ls_info method.
+        """
+        if hasattr(self.backend, "ls_info"):
+            return self.backend.ls_info
+
+        raise AttributeError("Backend does not support file listing. Please provide a backend with ls_info method.")
+
+    def _format_result(self, result: ExecuteResult) -> str:
+        """Format execution result for LLM consumption.
+
+        Args:
+            result: ExecuteResult from backend.
+
+        Returns:
+            Formatted output string with stdout, stderr, exit code.
+        """
+        parts: list[str] = []
+
+        if result.stdout:
+            parts.append(f"STDOUT:\n{result.stdout}")
+        if result.stderr:
+            parts.append(f"STDERR:\n{result.stderr}")
+
+        status = "succeeded" if result.exit_code == 0 else "failed"
+        parts.append(f"\n[Command {status} with exit code {result.exit_code}]")
+
+        if result.truncated:
+            parts.append("\n[Output was truncated due to size limits]")
+
+        return "\n".join(parts)

aip_agents/middleware/tools/grep_file.py

@@ -0,0 +1,79 @@
+"""Grep tool for agents.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+
+Notes:
+TODO: After migrating to deepagents:
+  - Reuse from deepagents: BackendProtocol, GrepMatch, format_grep_matches()
+"""
+
+from typing import Annotated, Any
+
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field, SkipValidation
+
+from aip_agents.middleware.backends.protocol import GrepMatch
+from aip_agents.middleware.backends.utils import ensure_absolute_path, format_grep_matches
+from aip_agents.middleware.schema import MiddlewareToolConfig
+
+GREP_TOOL_DESCRIPTION = """Search for a text pattern across files.
+
+Searches for literal text (not regex) and returns matching files or content based on output_mode.
+Special characters like parentheses, brackets, pipes, etc. are treated as literal characters, not regex operators.
+
+Examples:
+- Search all files: `grep(pattern="TODO")`
+- Search Python files only: `grep(pattern="import", glob="*.py")`
+- Show matching lines: `grep(pattern="error", output_mode="content")`
+- Search for code with special chars: `grep(pattern="def __init__(self):")`"""
+
+
+class GrepInput(BaseModel):
+    """Input schema for grep tool."""
+
+    path: str = Field(description="Directory path to search")
+    pattern: str = Field(description="Text pattern to search for (literal string)")
+    max_matches: int = Field(default=50, description="Maximum number of matches to return")
+
+
+class GrepTool(BaseTool):
+    """Tool for searching file contents across directories."""
+
+    name: str = "grep"
+    description: str = GREP_TOOL_DESCRIPTION
+    args_schema: type[BaseModel] = GrepInput
+    tool_config_schema: type[BaseModel] = MiddlewareToolConfig
+    backend: Annotated[Any, SkipValidation()]
+
+    def _run(self, path: str, pattern: str, max_matches: int = 50) -> str:
+        """Execute the grep operation.
+
+        Args:
+            path (str): Directory path to search.
+            pattern (str): Text pattern to search for.
+            max_matches (int, optional): Maximum matches to return. Defaults to 50.
+
+        Returns:
+            str: Search results or error message.
+        """
+        try:
+            matches = self.backend.grep(pattern=pattern, path=path)
+            if len(matches) > max_matches:
+                matches = matches[:max_matches]
+            # Normalize paths to absolute so read_file receives consistent input
+            normalized = [
+                GrepMatch(
+                    path=ensure_absolute_path(m.path),
+                    line_number=m.line_number,
+                    content=m.content,
+                )
+                for m in matches
+            ]
+            return format_grep_matches(normalized, output_mode="content")
+        except FileNotFoundError:
+            return f"Error: Path not found: {path}"
+        except ValueError as e:
+            return f"Error: {str(e)}"
+        except Exception as e:
+            return f"Error searching: {str(e)}"

aip_agents/middleware/tools/ls.py

@@ -0,0 +1,71 @@
+"""List files tool for agents.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+
+TODO: When migrating to deepagents, replace this entire file with:
+    from deepagents.middleware.tools.ls import LsTool, LsInput, truncate_if_too_long
+
+    Note: deepagents LsTool uses ToolRuntime pattern instead of BaseTool.
+    We'll need to adapt our middleware to use deepagents' tool registration.
+"""
+
+from typing import Annotated, Any
+
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field, SkipValidation
+
+from aip_agents.middleware.backends.utils import (
+    ensure_absolute_path,
+    truncate_if_too_long,
+)
+from aip_agents.middleware.schema import MiddlewareToolConfig
+
+LIST_FILES_TOOL_DESCRIPTION = """Lists all files in a directory.
+
+This is useful for exploring the filesystem and finding the right file to read or edit.
+You should almost ALWAYS use this tool before using the read_file tool."""
+
+
+class LsInput(BaseModel):
+    """Input schema for ls tool."""
+
+    path: str = Field(description="Absolute path to the directory to list. Must be absolute, not relative.")
+
+
+class LsTool(BaseTool):
+    """Tool for listing directory contents.
+
+    Returns a Python list representation (as string) of absolute paths for files and directories.
+    Large results are automatically truncated with guidance.
+    """
+
+    name: str = "ls"
+    description: str = LIST_FILES_TOOL_DESCRIPTION
+    args_schema: type[BaseModel] = LsInput
+    tool_config_schema: type[BaseModel] = MiddlewareToolConfig
+    backend: Annotated[Any, SkipValidation()]
+
+    def _run(self, path: str) -> str:
+        """Execute the ls operation.
+
+        Args:
+            path (str): Directory path to list.
+
+        Returns:
+            str: Python list representation (as string) of absolute paths,
+                or an error message if directory not found or path is not a directory.
+            Example: "['/workspace/file1.txt', '/workspace/file2.txt']"
+        """
+        try:
+            entries = self.backend.ls_info(path)
+            # Extract full paths like deepagents does
+            paths = [ensure_absolute_path(str(entry["path"])) for entry in entries]
+            truncated = truncate_if_too_long(paths)
+            return str(truncated)
+        except FileNotFoundError:
+            return f"No directory found: {path}"
+        except NotADirectoryError:
+            return f"Not a directory: {path}"
+        except Exception as e:
+            return f"Error: {str(e)}"