fast-agent-mcp 0.4.7__py3-none-any.whl

fast_agent/acp/filesystem_runtime.py

@@ -0,0 +1,427 @@
+"""
+ACPFilesystemRuntime - Read and write text files via ACP filesystem support.
+
+This runtime allows FastAgent to read and write files through the ACP client's filesystem
+capabilities when available (e.g., in Zed editor). This provides better integration and
+security compared to direct file system access.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from mcp.types import CallToolResult, Tool
+
+from fast_agent.core.logging.logger import get_logger
+from fast_agent.mcp.helpers.content_helpers import text_content
+
+if TYPE_CHECKING:
+    from acp import AgentSideConnection
+    from acp.schema import ReadTextFileResponse
+
+    from fast_agent.mcp.tool_execution_handler import ToolExecutionHandler
+    from fast_agent.mcp.tool_permission_handler import ToolPermissionHandler
+
+logger = get_logger(__name__)
+
+
+class ACPFilesystemRuntime:
+    """
+    Provides file reading and writing through ACP filesystem support.
+
+    This runtime implements the "read_text_file" and "write_text_file" tools by delegating
+    to the ACP client's filesystem capabilities. The client (e.g., Zed editor) handles
+    file access and permissions, providing a secure sandboxed environment.
+    """
+
+    def __init__(
+        self,
+        connection: "AgentSideConnection",
+        session_id: str,
+        activation_reason: str,
+        logger_instance=None,
+        enable_read: bool = True,
+        enable_write: bool = True,
+        tool_handler: "ToolExecutionHandler | None" = None,
+        permission_handler: "ToolPermissionHandler | None" = None,
+    ):
+        """
+        Initialize the ACP filesystem runtime.
+
+        Args:
+            connection: The ACP connection to use for filesystem operations
+            session_id: The ACP session ID for this runtime
+            activation_reason: Human-readable reason for activation
+            logger_instance: Optional logger instance
+            enable_read: Whether to enable the read_text_file tool
+            enable_write: Whether to enable the write_text_file tool
+            tool_handler: Optional tool execution handler for telemetry
+            permission_handler: Optional permission handler for tool execution authorization
+        """
+        self.connection = connection
+        self.session_id = session_id
+        self.activation_reason = activation_reason
+        self.logger = logger_instance or logger
+        self._enable_read = enable_read
+        self._enable_write = enable_write
+        self._tool_handler = tool_handler
+        self._permission_handler = permission_handler
+
+        # Tool definition for reading text files
+        self._read_tool = Tool(
+            name="read_text_file",
+            description="Read content from a text file. Returns the file contents as a string. ",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "Absolute path to the file to read.",
+                    },
+                    "line": {
+                        "type": "integer",
+                        "description": "Optional line number to start reading from (1-based).",
+                        "minimum": 1,
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "description": "Optional maximum number of lines to read.",
+                        "minimum": 1,
+                    },
+                },
+                "required": ["path"],
+                "additionalProperties": False,
+            },
+        )
+
+        # Tool definition for writing text files
+        self._write_tool = Tool(
+            name="write_text_file",
+            description="Write content to a text file. Creates or overwrites the file. ",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "Absolute path to the file to write.",
+                    },
+                    "content": {
+                        "type": "string",
+                        "description": "The text content to write to the file.",
+                    },
+                },
+                "required": ["path", "content"],
+                "additionalProperties": False,
+            },
+        )
+
+        self.logger.info(
+            "ACPFilesystemRuntime initialized",
+            session_id=session_id,
+            reason=activation_reason,
+        )
+
+    @property
+    def read_tool(self) -> Tool:
+        """Get the read_text_file tool definition."""
+        return self._read_tool
+
+    @property
+    def write_tool(self) -> Tool:
+        """Get the write_text_file tool definition."""
+        return self._write_tool
+
+    @property
+    def tools(self) -> list[Tool]:
+        """Get all enabled filesystem tools."""
+        tools = []
+        if self._enable_read:
+            tools.append(self._read_tool)
+        if self._enable_write:
+            tools.append(self._write_tool)
+        return tools
+
+    async def read_text_file(
+        self, arguments: dict[str, Any], tool_use_id: str | None = None
+    ) -> CallToolResult:
+        """
+        Read a text file using ACP filesystem support.
+
+        Args:
+            arguments: Tool arguments containing 'path' and optionally 'line' and 'limit'
+            tool_use_id: LLM's tool use ID (for matching with stream events)
+
+        Returns:
+            CallToolResult with file contents
+        """
+        # Validate arguments
+        if not isinstance(arguments, dict):
+            return CallToolResult(
+                content=[text_content("Error: arguments must be a dict")],
+                isError=True,
+            )
+
+        path = arguments.get("path")
+        if not path or not isinstance(path, str):
+            return CallToolResult(
+                content=[text_content("Error: 'path' argument is required and must be a string")],
+                isError=True,
+            )
+
+        self.logger.info(
+            "Reading file via ACP filesystem",
+            session_id=self.session_id,
+            path=path,
+        )
+
+        # Check permission before execution
+        if self._permission_handler:
+            try:
+                permission_result = await self._permission_handler.check_permission(
+                    tool_name="read_text_file",
+                    server_name="acp_filesystem",
+                    arguments=arguments,
+                    tool_use_id=tool_use_id,
+                )
+                if not permission_result.allowed:
+                    error_msg = permission_result.error_message or (
+                        f"Permission denied for reading file: {path}"
+                    )
+                    self.logger.info(
+                        "File read denied by permission handler",
+                        data={
+                            "path": path,
+                            "cancelled": permission_result.is_cancelled,
+                        },
+                    )
+                    return CallToolResult(
+                        content=[text_content(error_msg)],
+                        isError=True,
+                    )
+            except Exception as e:
+                self.logger.error(f"Error checking file read permission: {e}", exc_info=True)
+                # Fail-safe: deny on permission check error
+                return CallToolResult(
+                    content=[text_content(f"Permission check failed: {e}")],
+                    isError=True,
+                )
+
+        # Notify tool handler that execution is starting
+        tool_call_id = None
+        if self._tool_handler:
+            try:
+                tool_call_id = await self._tool_handler.on_tool_start(
+                    "read_text_file", "acp_filesystem", arguments, tool_use_id
+                )
+            except Exception as e:
+                self.logger.error(f"Error in tool start handler: {e}", exc_info=True)
+
+        try:
+            # Send request using the proper ACP method with flattened parameters
+            response: ReadTextFileResponse = await self.connection.read_text_file(
+                path=path,
+                session_id=self.session_id,
+                line=arguments.get("line"),
+                limit=arguments.get("limit"),
+            )
+            content = response.content
+
+            self.logger.info(
+                "File read completed",
+                session_id=self.session_id,
+                path=path,
+                content_length=len(content),
+            )
+
+            result = CallToolResult(
+                content=[text_content(content)],
+                isError=False,
+            )
+
+            # Notify tool handler of completion
+            if self._tool_handler and tool_call_id:
+                try:
+                    await self._tool_handler.on_tool_complete(
+                        tool_call_id, True, result.content, None
+                    )
+                except Exception as e:
+                    self.logger.error(f"Error in tool complete handler: {e}", exc_info=True)
+
+            return result
+
+        except Exception as e:
+            self.logger.error(
+                f"Error reading file: {e}",
+                session_id=self.session_id,
+                path=path,
+                exc_info=True,
+            )
+
+            # Notify tool handler of error
+            if self._tool_handler and tool_call_id:
+                try:
+                    await self._tool_handler.on_tool_complete(tool_call_id, False, None, str(e))
+                except Exception as handler_error:
+                    self.logger.error(
+                        f"Error in tool complete handler: {handler_error}", exc_info=True
+                    )
+
+            return CallToolResult(
+                content=[text_content(f"Error reading file: {e}")],
+                isError=True,
+            )
+
+    async def write_text_file(
+        self, arguments: dict[str, Any], tool_use_id: str | None = None
+    ) -> CallToolResult:
+        """
+        Write a text file using ACP filesystem support.
+
+        Args:
+            arguments: Tool arguments containing 'path' and 'content'
+            tool_use_id: LLM's tool use ID (for matching with stream events)
+
+        Returns:
+            CallToolResult indicating success or failure
+        """
+        # Validate arguments
+        if not isinstance(arguments, dict):
+            return CallToolResult(
+                content=[text_content("Error: arguments must be a dict")],
+                isError=True,
+            )
+
+        path = arguments.get("path")
+        if not path or not isinstance(path, str):
+            return CallToolResult(
+                content=[text_content("Error: 'path' argument is required and must be a string")],
+                isError=True,
+            )
+
+        content = arguments.get("content")
+        if content is None or not isinstance(content, str):
+            return CallToolResult(
+                content=[
+                    text_content("Error: 'content' argument is required and must be a string")
+                ],
+                isError=True,
+            )
+
+        self.logger.info(
+            "Writing file via ACP filesystem",
+            session_id=self.session_id,
+            path=path,
+            content_length=len(content),
+        )
+
+        # Check permission before execution
+        if self._permission_handler:
+            try:
+                permission_result = await self._permission_handler.check_permission(
+                    tool_name="write_text_file",
+                    server_name="acp_filesystem",
+                    arguments=arguments,
+                    tool_use_id=tool_use_id,
+                )
+                if not permission_result.allowed:
+                    error_msg = permission_result.error_message or (
+                        f"Permission denied for writing file: {path}"
+                    )
+                    self.logger.info(
+                        "File write denied by permission handler",
+                        data={
+                            "path": path,
+                            "cancelled": permission_result.is_cancelled,
+                        },
+                    )
+                    return CallToolResult(
+                        content=[text_content(error_msg)],
+                        isError=True,
+                    )
+            except Exception as e:
+                self.logger.error(f"Error checking file write permission: {e}", exc_info=True)
+                # Fail-safe: deny on permission check error
+                return CallToolResult(
+                    content=[text_content(f"Permission check failed: {e}")],
+                    isError=True,
+                )
+
+        # Notify tool handler that execution is starting
+        tool_call_id = None
+        if self._tool_handler:
+            try:
+                tool_call_id = await self._tool_handler.on_tool_start(
+                    "write_text_file", "acp_filesystem", arguments, tool_use_id
+                )
+            except Exception as e:
+                self.logger.error(f"Error in tool start handler: {e}", exc_info=True)
+
+        try:
+            # Send request using the proper ACP method with flattened parameters
+            await self.connection.write_text_file(
+                content=content,
+                path=path,
+                session_id=self.session_id,
+            )
+
+            self.logger.info(
+                "File write completed",
+                session_id=self.session_id,
+                path=path,
+            )
+
+            result = CallToolResult(
+                content=[text_content(f"Successfully wrote {len(content)} characters to {path}")],
+                isError=False,
+            )
+
+            # Notify tool handler of completion
+            if self._tool_handler and tool_call_id:
+                try:
+                    await self._tool_handler.on_tool_complete(
+                        tool_call_id, True, result.content, None
+                    )
+                except Exception as e:
+                    self.logger.error(f"Error in tool complete handler: {e}", exc_info=True)
+
+            return result
+
+        except Exception as e:
+            self.logger.error(
+                f"Error writing file: {e}",
+                session_id=self.session_id,
+                path=path,
+                exc_info=True,
+            )
+
+            # Notify tool handler of error
+            if self._tool_handler and tool_call_id:
+                try:
+                    await self._tool_handler.on_tool_complete(tool_call_id, False, None, str(e))
+                except Exception as handler_error:
+                    self.logger.error(
+                        f"Error in tool complete handler: {handler_error}", exc_info=True
+                    )
+
+            return CallToolResult(
+                content=[text_content(f"Error writing file: {e}")],
+                isError=True,
+            )
+
+    def metadata(self) -> dict[str, Any]:
+        """
+        Get metadata about this runtime for display/logging.
+
+        Returns:
+            Dict with runtime information
+        """
+        enabled_tools = []
+        if self._enable_read:
+            enabled_tools.append("read_text_file")
+        if self._enable_write:
+            enabled_tools.append("write_text_file")
+
+        return {
+            "type": "acp_filesystem",
+            "session_id": self.session_id,
+            "activation_reason": self.activation_reason,
+            "tools": enabled_tools,
+        }

fast_agent/acp/permission_store.py

@@ -0,0 +1,269 @@
+"""
+ACP Tool Permission Store
+
+Provides persistent storage for tool execution permissions.
+Stores permissions in a human-readable markdown file at .fast-agent/auths.md.
+"""
+
+import asyncio
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+from fast_agent.core.logging.logger import get_logger
+
+logger = get_logger(__name__)
+
+# Default path relative to session working directory
+DEFAULT_PERMISSIONS_FILE = ".fast-agent/auths.md"
+
+
+class PermissionDecision(str, Enum):
+    """Stored permission decisions (only 'always' variants are persisted)."""
+
+    ALLOW_ALWAYS = "allow_always"
+    REJECT_ALWAYS = "reject_always"
+
+
+@dataclass
+class PermissionResult:
+    """Result of a permission check or request."""
+
+    allowed: bool
+    remember: bool = False
+    is_cancelled: bool = False
+
+    @classmethod
+    def allow_once(cls) -> "PermissionResult":
+        """Create an allow-once result (not persisted)."""
+        return cls(allowed=True, remember=False)
+
+    @classmethod
+    def allow_always(cls) -> "PermissionResult":
+        """Create an allow-always result (persisted)."""
+        return cls(allowed=True, remember=True)
+
+    @classmethod
+    def reject_once(cls) -> "PermissionResult":
+        """Create a reject-once result (not persisted)."""
+        return cls(allowed=False, remember=False)
+
+    @classmethod
+    def reject_always(cls) -> "PermissionResult":
+        """Create a reject-always result (persisted)."""
+        return cls(allowed=False, remember=True)
+
+    @classmethod
+    def cancelled(cls) -> "PermissionResult":
+        """Create a cancelled result (rejected, not persisted)."""
+        return cls(allowed=False, remember=False, is_cancelled=True)
+
+
+class PermissionStore:
+    """
+    Persistent storage for tool execution permissions.
+
+    Stores allow_always and reject_always decisions in a markdown file
+    that is human-readable and editable. The file is only created when
+    the first 'always' permission is set.
+
+    Thread-safe for concurrent access using asyncio locks.
+    """
+
+    def __init__(self, cwd: str | Path | None = None) -> None:
+        """
+        Initialize the permission store.
+
+        Args:
+            cwd: Working directory for the session. If None, uses current directory.
+        """
+        self._cwd = Path(cwd) if cwd else Path.cwd()
+        self._file_path = self._cwd / DEFAULT_PERMISSIONS_FILE
+        self._cache: dict[str, PermissionDecision] = {}
+        self._loaded = False
+        self._lock = asyncio.Lock()
+
+    @property
+    def file_path(self) -> Path:
+        """Get the path to the permissions file."""
+        return self._file_path
+
+    def _get_permission_key(self, server_name: str, tool_name: str) -> str:
+        """Get a unique key for a server/tool combination."""
+        return f"{server_name}/{tool_name}"
+
+    async def _ensure_loaded(self) -> None:
+        """Ensure permissions are loaded from disk (lazy loading)."""
+        if self._loaded:
+            return
+
+        if self._file_path.exists():
+            try:
+                await self._load_from_file()
+            except Exception as e:
+                logger.warning(
+                    f"Failed to load permissions file: {e}",
+                    name="permission_store_load_error",
+                )
+                # Continue without persisted permissions
+        self._loaded = True
+
+    async def _load_from_file(self) -> None:
+        """Load permissions from the markdown file."""
+        content = await asyncio.to_thread(self._file_path.read_text, encoding="utf-8")
+
+        # Parse markdown table format:
+        # | Server | Tool | Permission |
+        # |--------|------|------------|
+        # | server1 | tool1 | allow_always |
+
+        in_table = False
+        for line in content.splitlines():
+            line = line.strip()
+
+            # Skip empty lines and header
+            if not line:
+                continue
+            if line.startswith("# "):
+                continue
+            if line.startswith("|--") or line.startswith("| --"):
+                in_table = True
+                continue
+            if line.startswith("| Server"):
+                continue
+
+            # Parse table rows
+            if in_table and line.startswith("|") and line.endswith("|"):
+                parts = [p.strip() for p in line.split("|")[1:-1]]
+                if len(parts) >= 3:
+                    server_name, tool_name, permission = parts[0], parts[1], parts[2]
+                    key = self._get_permission_key(server_name, tool_name)
+                    try:
+                        self._cache[key] = PermissionDecision(permission)
+                    except ValueError:
+                        logger.warning(
+                            f"Invalid permission value in auths.md: {permission}",
+                            name="permission_store_parse_error",
+                        )
+
+    async def _save_to_file(self) -> None:
+        """Save permissions to the markdown file."""
+        if not self._cache:
+            # Don't create file if no permissions to save
+            return
+
+        # Ensure directory exists
+        self._file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Build markdown content
+        lines = [
+            "# fast-agent Tool Permissions",
+            "",
+            "This file stores persistent tool execution permissions.",
+            "You can edit this file manually to add or remove permissions.",
+            "",
+            "| Server | Tool | Permission |",
+            "|--------|------|------------|",
+        ]
+
+        for key, decision in sorted(self._cache.items()):
+            server_name, tool_name = key.split("/", 1)
+            lines.append(f"| {server_name} | {tool_name} | {decision.value} |")
+
+        lines.append("")  # Trailing newline
+        content = "\n".join(lines)
+
+        await asyncio.to_thread(self._file_path.write_text, content, encoding="utf-8")
+
+        logger.debug(
+            f"Saved {len(self._cache)} permissions to {self._file_path}",
+            name="permission_store_saved",
+        )
+
+    async def get(self, server_name: str, tool_name: str) -> PermissionDecision | None:
+        """
+        Get stored permission for a server/tool.
+
+        Args:
+            server_name: Name of the MCP server
+            tool_name: Name of the tool
+
+        Returns:
+            PermissionDecision if stored, None if not found
+        """
+        async with self._lock:
+            await self._ensure_loaded()
+            key = self._get_permission_key(server_name, tool_name)
+            return self._cache.get(key)
+
+    async def set(self, server_name: str, tool_name: str, decision: PermissionDecision) -> None:
+        """
+        Store a permission decision.
+
+        Args:
+            server_name: Name of the MCP server
+            tool_name: Name of the tool
+            decision: The permission decision to store
+        """
+        async with self._lock:
+            await self._ensure_loaded()
+            key = self._get_permission_key(server_name, tool_name)
+            self._cache[key] = decision
+            try:
+                await self._save_to_file()
+            except Exception as e:
+                logger.warning(
+                    f"Failed to save permissions file: {e}",
+                    name="permission_store_save_error",
+                )
+                # Continue - in-memory cache is still valid
+
+    async def remove(self, server_name: str, tool_name: str) -> bool:
+        """
+        Remove a stored permission.
+
+        Args:
+            server_name: Name of the MCP server
+            tool_name: Name of the tool
+
+        Returns:
+            True if permission was removed, False if not found
+        """
+        async with self._lock:
+            await self._ensure_loaded()
+            key = self._get_permission_key(server_name, tool_name)
+            if key in self._cache:
+                del self._cache[key]
+                try:
+                    await self._save_to_file()
+                except Exception as e:
+                    logger.warning(
+                        f"Failed to save permissions file after removal: {e}",
+                        name="permission_store_save_error",
+                    )
+                return True
+            return False
+
+    async def clear(self) -> None:
+        """Clear all stored permissions."""
+        async with self._lock:
+            self._cache.clear()
+            if self._file_path.exists():
+                try:
+                    await asyncio.to_thread(self._file_path.unlink)
+                except Exception as e:
+                    logger.warning(
+                        f"Failed to delete permissions file: {e}",
+                        name="permission_store_delete_error",
+                    )
+
+    async def list_all(self) -> dict[str, PermissionDecision]:
+        """
+        Get all stored permissions.
+
+        Returns:
+            Dictionary of permission key -> decision
+        """
+        async with self._lock:
+            await self._ensure_loaded()
+            return dict(self._cache)

fast_agent/acp/server/__init__.py

@@ -0,0 +1,5 @@
+"""ACP server implementation."""
+
+from fast_agent.acp.server.agent_acp_server import AgentACPServer
+
+__all__ = ["AgentACPServer"]