flowly-code 1.0.0__py3-none-any.whl

flowly_code/agent/tools/filesystem.py

@@ -0,0 +1,280 @@
+"""File system tools: read, write, edit."""
+
+from pathlib import Path
+from typing import Any
+
+from flowly_code.agent.tools.base import Tool
+
+# Allowed paths outside workspace (home-relative config/data dirs)
+_ALLOWED_PREFIXES = (
+    Path.home() / ".flowly",
+)
+
+
+def _is_path_allowed(
+    resolved_path: Path,
+    workspace: Path | None,
+    access_mode: str = "full",
+    allowed_paths: list[Path] | None = None,
+) -> bool:
+    """Check if a resolved path is allowed based on access mode.
+
+    Modes:
+        full — all paths allowed
+        projects — only Dispatch project dirs + ~/.flowly
+        workspace — only ~/.flowly/workspace + ~/.flowly
+    """
+    if access_mode == "full":
+        return True
+
+    # ~/.flowly is always allowed
+    for prefix in _ALLOWED_PREFIXES:
+        try:
+            resolved_path.relative_to(prefix.resolve())
+            return True
+        except ValueError:
+            continue
+
+    # Project directories (when mode=projects)
+    if access_mode == "projects" and allowed_paths:
+        for p in allowed_paths:
+            try:
+                resolved_path.relative_to(p.resolve())
+                return True
+            except ValueError:
+                continue
+
+    # Workspace directory
+    if workspace:
+        try:
+            resolved_path.relative_to(workspace.resolve())
+            return True
+        except ValueError:
+            pass
+
+    return False
+
+
+class ReadFileTool(Tool):
+    """Tool to read file contents."""
+
+    def __init__(self, workspace: Path | None = None,
+                 access_mode: str = "full", allowed_paths: list[Path] | None = None):
+        self.workspace = workspace
+        self.access_mode = access_mode
+        self.allowed_paths = allowed_paths
+
+    @property
+    def name(self) -> str:
+        return "read_file"
+
+    @property
+    def description(self) -> str:
+        return "Read the contents of a file at the given path."
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "The file path to read"
+                }
+            },
+            "required": ["path"]
+        }
+
+    async def execute(self, path: str, **kwargs: Any) -> str:
+        try:
+            file_path = Path(path).expanduser().resolve()
+
+            if not _is_path_allowed(file_path, self.workspace, self.access_mode, self.allowed_paths):
+                return f"Error: Access denied — path outside allowed directories: {path}"
+
+            if not file_path.exists():
+                return f"Error: File not found: {path}"
+            if not file_path.is_file():
+                return f"Error: Not a file: {path}"
+
+            content = file_path.read_text(encoding="utf-8")
+            return content
+        except PermissionError:
+            return f"Error: Permission denied: {path}"
+        except Exception as e:
+            return f"Error reading file: {str(e)}"
+
+
+class WriteFileTool(Tool):
+    """Tool to write content to a file."""
+
+    def __init__(self, workspace: Path | None = None,
+                 access_mode: str = "full", allowed_paths: list[Path] | None = None):
+        self.workspace = workspace
+        self.access_mode = access_mode
+        self.allowed_paths = allowed_paths
+
+    @property
+    def name(self) -> str:
+        return "write_file"
+
+    @property
+    def description(self) -> str:
+        return "Write content to a file at the given path. Creates parent directories if needed."
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "The file path to write to"
+                },
+                "content": {
+                    "type": "string",
+                    "description": "The content to write"
+                }
+            },
+            "required": ["path", "content"]
+        }
+
+    async def execute(self, path: str, content: str, **kwargs: Any) -> str:
+        try:
+            file_path = Path(path).expanduser().resolve()
+
+            if not _is_path_allowed(file_path, self.workspace, self.access_mode, self.allowed_paths):
+                return f"Error: Access denied — path outside allowed directories: {path}"
+
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+            file_path.write_text(content, encoding="utf-8")
+            return f"Successfully wrote {len(content)} bytes to {path}"
+        except PermissionError:
+            return f"Error: Permission denied: {path}"
+        except Exception as e:
+            return f"Error writing file: {str(e)}"
+
+
+class EditFileTool(Tool):
+    """Tool to edit a file by replacing text."""
+
+    def __init__(self, workspace: Path | None = None,
+                 access_mode: str = "full", allowed_paths: list[Path] | None = None):
+        self.workspace = workspace
+        self.access_mode = access_mode
+        self.allowed_paths = allowed_paths
+
+    @property
+    def name(self) -> str:
+        return "edit_file"
+
+    @property
+    def description(self) -> str:
+        return "Edit a file by replacing old_text with new_text. The old_text must exist exactly in the file."
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "The file path to edit"
+                },
+                "old_text": {
+                    "type": "string",
+                    "description": "The exact text to find and replace"
+                },
+                "new_text": {
+                    "type": "string",
+                    "description": "The text to replace with"
+                }
+            },
+            "required": ["path", "old_text", "new_text"]
+        }
+
+    async def execute(self, path: str, old_text: str, new_text: str, **kwargs: Any) -> str:
+        try:
+            file_path = Path(path).expanduser().resolve()
+
+            if not _is_path_allowed(file_path, self.workspace, self.access_mode, self.allowed_paths):
+                return f"Error: Access denied — path outside allowed directories: {path}"
+
+            if not file_path.exists():
+                return f"Error: File not found: {path}"
+
+            content = file_path.read_text(encoding="utf-8")
+
+            if old_text not in content:
+                return f"Error: old_text not found in file. Make sure it matches exactly."
+
+            # Count occurrences
+            count = content.count(old_text)
+            if count > 1:
+                return f"Warning: old_text appears {count} times. Please provide more context to make it unique."
+
+            new_content = content.replace(old_text, new_text, 1)
+            file_path.write_text(new_content, encoding="utf-8")
+
+            return f"Successfully edited {path}"
+        except PermissionError:
+            return f"Error: Permission denied: {path}"
+        except Exception as e:
+            return f"Error editing file: {str(e)}"
+
+
+class ListDirTool(Tool):
+    """Tool to list directory contents."""
+
+    def __init__(self, workspace: Path | None = None,
+                 access_mode: str = "full", allowed_paths: list[Path] | None = None):
+        self.workspace = workspace
+        self.access_mode = access_mode
+        self.allowed_paths = allowed_paths
+
+    @property
+    def name(self) -> str:
+        return "list_dir"
+
+    @property
+    def description(self) -> str:
+        return "List the contents of a directory."
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "The directory path to list"
+                }
+            },
+            "required": ["path"]
+        }
+
+    async def execute(self, path: str, **kwargs: Any) -> str:
+        try:
+            dir_path = Path(path).expanduser().resolve()
+
+            if not _is_path_allowed(dir_path, self.workspace, self.access_mode, self.allowed_paths):
+                return f"Error: Access denied — path outside allowed directories: {path}"
+
+            if not dir_path.exists():
+                return f"Error: Directory not found: {path}"
+            if not dir_path.is_dir():
+                return f"Error: Not a directory: {path}"
+
+            items = []
+            for item in sorted(dir_path.iterdir()):
+                prefix = "d " if item.is_dir() else "f "
+                items.append(f"{prefix}{item.name}")
+
+            if not items:
+                return f"Directory {path} is empty"
+
+            return "\n".join(items)
+        except PermissionError:
+            return f"Error: Permission denied: {path}"
+        except Exception as e:
+            return f"Error listing directory: {str(e)}"

flowly_code/agent/tools/mcp.py

@@ -0,0 +1,85 @@
+"""MCP client: connects to MCP servers and wraps their tools as native flowly tools."""
+
+from contextlib import AsyncExitStack
+from typing import Any
+
+from loguru import logger
+
+from flowly_code.agent.tools.base import Tool
+from flowly_code.agent.tools.registry import ToolRegistry
+
+
+class MCPToolWrapper(Tool):
+    """Wraps a single MCP server tool as a flowly Tool."""
+
+    def __init__(self, session, server_name: str, tool_def):
+        self._session = session
+        self._original_name = tool_def.name
+        self._name = f"mcp_{server_name}_{tool_def.name}"
+        self._description = tool_def.description or tool_def.name
+        self._parameters = tool_def.inputSchema or {"type": "object", "properties": {}}
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def description(self) -> str:
+        return self._description
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return self._parameters
+
+    async def execute(self, **kwargs: Any) -> str:
+        from mcp import types
+
+        result = await self._session.call_tool(self._original_name, arguments=kwargs)
+        parts = []
+        for block in result.content:
+            if isinstance(block, types.TextContent):
+                parts.append(block.text)
+            else:
+                parts.append(str(block))
+        return "\n".join(parts) or "(no output)"
+
+
+async def connect_mcp_servers(
+    mcp_servers: dict, registry: ToolRegistry, stack: AsyncExitStack
+) -> None:
+    """Connect to configured MCP servers and register their tools."""
+    from mcp import ClientSession, StdioServerParameters
+    from mcp.client.stdio import stdio_client
+
+    for name, cfg in mcp_servers.items():
+        try:
+            if cfg.command:
+                env = dict(cfg.env) if cfg.env else None
+                params = StdioServerParameters(
+                    command=cfg.command, args=list(cfg.args), env=env
+                )
+                read, write = await stack.enter_async_context(stdio_client(params))
+            elif cfg.url:
+                from mcp.client.streamable_http import streamable_http_client
+
+                read, write, _ = await stack.enter_async_context(
+                    streamable_http_client(cfg.url)
+                )
+            else:
+                logger.warning(f"MCP server '{name}': no command or url configured, skipping")
+                continue
+
+            session = await stack.enter_async_context(ClientSession(read, write))
+            await session.initialize()
+
+            tools = await session.list_tools()
+            for tool_def in tools.tools:
+                wrapper = MCPToolWrapper(session, name, tool_def)
+                registry.register(wrapper)
+                logger.debug(f"MCP: registered tool '{wrapper.name}' from server '{name}'")
+
+            logger.info(
+                f"MCP server '{name}': connected, {len(tools.tools)} tools registered"
+            )
+        except Exception as e:
+            logger.error(f"MCP server '{name}': failed to connect: {e}")

flowly_code/agent/tools/message.py

@@ -0,0 +1,235 @@
+"""Message tool for sending messages and media to users."""
+
+import mimetypes
+from pathlib import Path
+from typing import Any, Callable, Awaitable
+
+from loguru import logger
+
+from flowly_code.agent.tools.base import Tool
+from flowly_code.bus.events import OutboundMessage
+
+
+# Supported media MIME types
+SUPPORTED_IMAGE_TYPES = {"image/jpeg", "image/png", "image/gif", "image/webp"}
+SUPPORTED_DOCUMENT_TYPES = {"application/pdf", "text/plain", "application/zip"}
+SUPPORTED_MEDIA_TYPES = SUPPORTED_IMAGE_TYPES | SUPPORTED_DOCUMENT_TYPES
+
+# Maximum media file size (10MB)
+MAX_MEDIA_SIZE = 10 * 1024 * 1024
+
+
+class MessageTool(Tool):
+    """
+    Tool to send messages and media to users on chat channels.
+
+    Supports:
+    - Text messages
+    - Images (jpg, png, gif, webp)
+    - Documents (pdf, txt, zip)
+
+    Media files are validated for existence, type, and size before sending.
+    """
+
+    def __init__(
+        self,
+        send_callback: Callable[[OutboundMessage], Awaitable[None]] | None = None,
+        default_channel: str = "",
+        default_chat_id: str = ""
+    ):
+        """
+        Initialize the message tool.
+
+        Args:
+            send_callback: Async function to send OutboundMessage.
+            default_channel: Default channel for messages.
+            default_chat_id: Default chat ID for messages.
+        """
+        self._send_callback = send_callback
+        self._default_channel = default_channel
+        self._default_chat_id = default_chat_id
+
+    def set_context(self, channel: str, chat_id: str) -> None:
+        """Set the current message context (channel and chat_id)."""
+        self._default_channel = channel
+        self._default_chat_id = chat_id
+
+    def set_send_callback(self, callback: Callable[[OutboundMessage], Awaitable[None]]) -> None:
+        """Set the callback for sending messages."""
+        self._send_callback = callback
+
+    @property
+    def name(self) -> str:
+        return "message"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Send a message to the user, optionally with media attachments (images, documents). "
+            "Use media_paths to attach files like screenshots. "
+            "The content will be sent as the caption for media messages."
+        )
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "content": {
+                    "type": "string",
+                    "description": "The message text to send. Used as caption when sending media."
+                },
+                "media_paths": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": (
+                        "Optional list of file paths to send as media attachments. "
+                        "Supports images (jpg, png, gif) and documents (pdf, txt). "
+                        "Example: [\"/path/to/screenshot.png\"]"
+                    )
+                },
+                "channel": {
+                    "type": "string",
+                    "description": "Optional: target channel (telegram, whatsapp, etc.)"
+                },
+                "chat_id": {
+                    "type": "string",
+                    "description": "Optional: target chat/user ID"
+                }
+            },
+            "required": ["content"]
+        }
+
+    async def execute(
+        self,
+        content: str,
+        media_paths: list[str] | None = None,
+        channel: str | None = None,
+        chat_id: str | None = None,
+        **kwargs: Any
+    ) -> str:
+        """
+        Send a message, optionally with media attachments.
+
+        Args:
+            content: Message text content.
+            media_paths: Optional list of file paths to attach.
+            channel: Target channel (uses default if not specified).
+            chat_id: Target chat ID (uses default if not specified).
+
+        Returns:
+            Success or error message.
+        """
+        # Use defaults if not specified
+        channel = channel or self._default_channel
+        chat_id = chat_id or self._default_chat_id
+
+        # Validate required fields
+        if not channel or not chat_id:
+            return "Error: No target channel/chat specified. Cannot send message."
+
+        if not self._send_callback:
+            return "Error: Message sending not configured. Internal error."
+
+        # Validate and filter media paths
+        validated_media: list[str] = []
+        media_errors: list[str] = []
+
+        if media_paths:
+            for path_str in media_paths:
+                validation_result = self._validate_media_file(path_str)
+                if validation_result is None:
+                    validated_media.append(path_str)
+                else:
+                    media_errors.append(validation_result)
+
+        # Build outbound message
+        msg = OutboundMessage(
+            channel=channel,
+            chat_id=chat_id,
+            content=content,
+            media=validated_media,
+            metadata={
+                "has_media": len(validated_media) > 0,
+                "media_count": len(validated_media)
+            }
+        )
+
+        # Send the message
+        try:
+            await self._send_callback(msg)
+
+            # Build response
+            result_parts = [f"Message sent to {channel}:{chat_id}"]
+
+            if validated_media:
+                result_parts.append(f"Attached {len(validated_media)} media file(s)")
+
+            if media_errors:
+                result_parts.append(f"Skipped {len(media_errors)} invalid file(s):")
+                for error in media_errors:
+                    result_parts.append(f"  - {error}")
+
+            return "\n".join(result_parts)
+
+        except Exception as e:
+            logger.error(f"Failed to send message: {e}")
+            return f"Error sending message: {str(e)}"
+
+    def _validate_media_file(self, path_str: str) -> str | None:
+        """
+        Validate a media file for sending.
+
+        Args:
+            path_str: Path to the file.
+
+        Returns:
+            None if valid, error message if invalid.
+        """
+        try:
+            path = Path(path_str).expanduser().resolve()
+
+            # Check existence
+            if not path.exists():
+                return f"File not found: {path_str}"
+
+            if not path.is_file():
+                return f"Not a file: {path_str}"
+
+            # Check file size
+            file_size = path.stat().st_size
+            if file_size == 0:
+                return f"File is empty: {path_str}"
+
+            if file_size > MAX_MEDIA_SIZE:
+                size_mb = file_size / 1024 / 1024
+                return f"File too large ({size_mb:.1f}MB > 10MB): {path_str}"
+
+            # Check MIME type
+            mime_type, _ = mimetypes.guess_type(str(path))
+            if mime_type is None:
+                # Allow files with common image extensions even without MIME detection
+                ext = path.suffix.lower()
+                if ext in {".jpg", ".jpeg", ".png", ".gif", ".webp"}:
+                    return None  # Accept based on extension
+                return f"Unknown file type: {path_str}"
+
+            if mime_type not in SUPPORTED_MEDIA_TYPES:
+                return f"Unsupported file type ({mime_type}): {path_str}"
+
+            return None  # Valid
+
+        except Exception as e:
+            return f"Error validating file: {str(e)}"
+
+    @staticmethod
+    def is_image(path: str) -> bool:
+        """Check if a file path points to an image."""
+        mime_type, _ = mimetypes.guess_type(path)
+        return mime_type in SUPPORTED_IMAGE_TYPES if mime_type else False
+
+    @staticmethod
+    def is_document(path: str) -> bool:
+        """Check if a file path points to a document."""
+        mime_type, _ = mimetypes.guess_type(path)
+        return mime_type in SUPPORTED_DOCUMENT_TYPES if mime_type else False