massgen 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

massgen/configs/tools/custom_tools/multimodal_tools/youtube_video_analysis.yaml

@@ -0,0 +1,59 @@
+# MassGen Configuration: YouTube Video Analysis with Multimodal Understanding
+#
+# Use Case: Download and analyze YouTube videos from MassGen case studies
+#
+# This demonstrates MassGen's self-evolution capabilities by having agents:
+# 1. Read local case study documentation to discover video URLs
+# 2. Download YouTube videos using yt-dlp via command-line execution
+# 3. Analyze video content using the understand_video multimodal tool
+# 4. Extract insights that could inform future feature development
+#
+# Run with:
+#   uv run massgen --config massgen/configs/tools/custom_tools/multimodal_tools/youtube_video_analysis.yaml "Download recent MassGen case study videos listed in the case study md files, analyze them, find out how to improve them and automate their creation."
+
+agents:
+  - id: "agent_a"
+    backend:
+      type: "openai"
+      model: "gpt-5-mini"
+      text:
+        verbosity: "medium"
+      reasoning:
+        effort: "medium"
+        summary: "auto"
+      custom_tools:
+        - name: ["understand_video"]
+          category: "multimodal"
+          path: "massgen/tool/_multimodal_tools/understand_video.py"
+          function: ["understand_video"]
+      enable_mcp_command_line: true
+      command_line_execution_mode: docker
+      command_line_docker_enable_sudo: true
+      command_line_docker_network_mode: "bridge"
+      cwd: "workspace1"
+
+  - id: "agent_b"
+    backend:
+      type: "claude_code"
+      model: "claude-sonnet-4-5-20250929"
+      custom_tools:
+        - name: ["understand_video"]
+          category: "multimodal"
+          path: "massgen/tool/_multimodal_tools/understand_video.py"
+          function: ["understand_video"]
+      enable_mcp_command_line: true
+      command_line_execution_mode: docker
+      command_line_docker_enable_sudo: true
+      command_line_docker_network_mode: "bridge"
+      cwd: "workspace2"
+
+orchestrator:
+  snapshot_storage: "snapshots"
+  agent_temporary_workspace: "temp_workspaces"
+  context_paths:
+    - path: "docs/source/examples/case_studies"
+      permission: "read"
+
+ui:
+  display_type: "rich_terminal"
+  logging_enabled: true

massgen/docker/README.md

@@ -115,6 +115,7 @@ agents:
 | `command_line_docker_memory_limit` | None | Memory limit (e.g., `"2g"`, `"512m"`) |
 | `command_line_docker_cpu_limit` | None | CPU cores limit (e.g., `2.0`) |
 | `command_line_docker_network_mode` | `"none"` | `"none"`, `"bridge"`, or `"host"` |
+| `command_line_docker_enable_sudo` | `false` | Enable sudo in containers (isolated from host) |
 
 ## How It Works
 
@@ -204,6 +205,88 @@ docker build -t my-custom-runtime:latest -f Dockerfile.custom .
 command_line_docker_image: "my-custom-runtime:latest"
 ```
 
+### Sudo Variant (Runtime Package Installation)
+
+The sudo variant allows agents to install system packages at runtime inside their Docker container.
+
+**IMPORTANT: Build the image before first use:**
+```bash
+bash massgen/docker/build.sh --sudo
+```
+
+This builds `massgen/mcp-runtime-sudo:latest` with sudo access locally. (This image is not available on Docker Hub - you must build it yourself.)
+
+**Enable in config:**
+```yaml
+agent:
+  backend:
+    cwd: "workspace"
+    enable_mcp_command_line: true
+    command_line_execution_mode: "docker"
+    command_line_docker_enable_sudo: true  # Automatically uses sudo image
+```
+
+**What agents can do with sudo:**
+```bash
+# Install system packages at runtime
+sudo apt-get update && sudo apt-get install -y ffmpeg
+
+# Install additional Python packages
+sudo pip install tensorflow
+
+# Modify system configuration inside the container
+sudo apt-get install -y postgresql-client
+```
+
+**Security model - Is this safe?**
+
+**YES, it's still safe** because Docker container isolation is the primary security boundary:
+
+✅ **Container is fully isolated from your host:**
+- Sudo inside container ≠ sudo on your computer
+- Agent can only access mounted volumes (workspace, context paths)
+- Cannot access your host filesystem outside mounts
+- Cannot affect host processes or system configuration
+- Docker namespaces/cgroups provide strong isolation
+
+✅ **What sudo can and cannot do:**
+- ✅ Can: Install packages inside the container (apt, pip, npm)
+- ✅ Can: Modify container system configuration
+- ✅ Can: Read/write mounted workspace (same as without sudo)
+- ❌ Cannot: Access your host filesystem outside mounts
+- ❌ Cannot: Affect your host system
+- ❌ Cannot: Break out of the container (unless Docker vulnerability exists)
+
+ℹ️ **Note:**
+- Container escape vulnerabilities (CVEs in Docker/kernel) are extremely rare and quickly patched
+- Standard Docker security practices apply
+
+❌ **Don't do this (makes it unsafe):**
+- Enabling privileged mode (not exposed in MassGen, would need code changes)
+- Mounting sensitive host paths like `/`, `/etc`, `/usr`
+- Disabling security features like AppArmor/SELinux
+
+**When to use sudo variant vs custom images:**
+
+| Approach | Use When | Performance | Security |
+|----------|----------|-------------|----------|
+| **Sudo variant** | Need flexibility, unknown packages upfront, prototyping | Slower (runtime install) | Good (container isolated) |
+| **Custom image** | Know packages needed, production use, performance matters | Fast (pre-installed) | Best (minimal attack surface) |
+
+**Custom image example (recommended for production):**
+```dockerfile
+FROM massgen/mcp-runtime:latest
+USER root
+RUN apt-get update && apt-get install -y ffmpeg postgresql-client
+USER massgen
+```
+
+Build: `docker build -t my-runtime:latest .`
+
+Use: `command_line_docker_image: "my-runtime:latest"`
+
+**Bottom line:** The sudo variant is safe for most use cases because Docker container isolation is strong. Custom images are preferred for production because they're faster and have a smaller attack surface, but sudo is fine for development and prototyping.
+
 ## Security Features
 
 ### Filesystem Isolation

massgen/filesystem_manager/_code_execution_server.py

@@ -62,7 +62,7 @@ def _validate_path_access(path: Path, allowed_paths: List[Path]) -> None:
     raise ValueError(f"Path not in allowed directories: {path}")
 
 
-def _sanitize_command(command: str) -> None:
+def _sanitize_command(command: str, enable_sudo: bool = False) -> None:
     """
     Sanitize the command to prevent dangerous operations.
 
@@ -71,6 +71,7 @@ def _sanitize_command(command: str) -> None:
 
     Args:
         command: The command to sanitize
+        enable_sudo: Whether sudo is enabled (in Docker mode with sudo variant)
 
     Raises:
         ValueError: If dangerous command is detected
@@ -82,13 +83,20 @@ def _sanitize_command(command: str) -> None:
         (r"\bdd\b", "Use of 'dd' command is not allowed"),
         (r">\s*/dev/sd[a-z][1-9]?", "Overwriting disk blocks directly is not allowed"),
         (r":\(\)\{\s*:\|\:&\s*\};:", "Fork bombs are not allowed"),
-        # Additional safety patterns
-        (r"\bsudo\b", "Use of 'sudo' is not allowed"),
-        (r"\bsu\b", "Use of 'su' is not allowed"),
-        (r"\bchown\b", "Use of 'chown' is not allowed"),
-        (r"\bchmod\b", "Use of 'chmod' is not allowed"),
     ]
 
+    # Only check these patterns if sudo is NOT enabled
+    # When sudo is enabled (Docker mode with sudo variant), these are safe
+    if not enable_sudo:
+        dangerous_patterns.extend(
+            [
+                (r"\bsudo\b", "Use of 'sudo' is not allowed"),
+                (r"\bsu\b", "Use of 'su' is not allowed"),
+                (r"\bchown\b", "Use of 'chown' is not allowed"),
+                (r"\bchmod\b", "Use of 'chmod' is not allowed"),
+            ],
+        )
+
     for pattern, message in dangerous_patterns:
         if re.search(pattern, command):
             raise ValueError(f"Potentially dangerous command detected: {message}")
@@ -202,6 +210,12 @@ async def create_server() -> fastmcp.FastMCP:
         default=None,
         help="Agent ID (required for Docker mode to identify container)",
     )
+    parser.add_argument(
+        "--enable-sudo",
+        action="store_true",
+        default=False,
+        help="Enable sudo in Docker containers (disables sudo command sanitization checks)",
+    )
     args = parser.parse_args()
 
     # Create the FastMCP server
@@ -215,6 +229,7 @@ async def create_server() -> fastmcp.FastMCP:
     mcp.blocked_commands = args.blocked_commands  # Blacklist patterns
     mcp.execution_mode = args.execution_mode
     mcp.agent_id = args.agent_id
+    mcp.enable_sudo = args.enable_sudo
 
     # Initialize Docker client if Docker mode
     mcp.docker_client = None
@@ -294,7 +309,7 @@ async def create_server() -> fastmcp.FastMCP:
         try:
             # Basic command sanitization (dangerous patterns)
             try:
-                _sanitize_command(command)
+                _sanitize_command(command, enable_sudo=mcp.enable_sudo)
             except ValueError as e:
                 return {
                     "success": False,

massgen/filesystem_manager/_docker_manager.py

@@ -45,6 +45,7 @@ class DockerManager:
         network_mode: str = "none",
         memory_limit: Optional[str] = None,
         cpu_limit: Optional[float] = None,
+        enable_sudo: bool = False,
     ):
         """
         Initialize Docker manager.
@@ -54,6 +55,7 @@ class DockerManager:
             network_mode: Network mode (none/bridge/host)
             memory_limit: Memory limit (e.g., "2g", "512m")
             cpu_limit: CPU limit (e.g., 2.0 for 2 CPUs)
+            enable_sudo: Enable sudo access in containers (isolated from host system)
 
         Raises:
             RuntimeError: If Docker is not available or cannot connect
@@ -61,7 +63,20 @@ class DockerManager:
         if not DOCKER_AVAILABLE:
             raise RuntimeError("Docker Python library not available. Install with: pip install docker")
 
-        self.image = image
+        # If sudo is enabled and user is using default image, switch to sudo variant
+        self.enable_sudo = enable_sudo
+        if enable_sudo and image == "massgen/mcp-runtime:latest":
+            self.image = "massgen/mcp-runtime-sudo:latest"
+            logger.info(
+                "ℹ️ [Docker] Sudo access enabled in container (isolated from host) - using 'massgen/mcp-runtime-sudo:latest' image.",
+            )
+        elif enable_sudo:
+            logger.info(
+                "ℹ️ [Docker] Sudo access enabled in container (isolated from host) with custom image.",
+            )
+        else:
+            self.image = image
+
         self.network_mode = network_mode
         self.memory_limit = memory_limit
         self.cpu_limit = cpu_limit
@@ -103,6 +118,11 @@ class DockerManager:
                 self.client.images.pull(self.image)
                 logger.info(f"✅ [Docker] Successfully pulled image '{self.image}'")
             except DockerException as e:
+                # Special handling for sudo image - it's built locally, not pulled
+                if "mcp-runtime-sudo" in self.image:
+                    raise RuntimeError(
+                        f"Failed to pull Docker image '{self.image}': {e}\n" f"The sudo image must be built locally. Run:\n" f"    bash massgen/docker/build.sh --sudo",
+                    )
                 raise RuntimeError(f"Failed to pull Docker image '{self.image}': {e}")
 
     def create_container(

massgen/filesystem_manager/_filesystem_manager.py

@@ -55,7 +55,9 @@ class FilesystemManager:
         command_line_docker_memory_limit: Optional[str] = None,
         command_line_docker_cpu_limit: Optional[float] = None,
         command_line_docker_network_mode: str = "none",
+        command_line_docker_enable_sudo: bool = False,
         enable_audio_generation: bool = False,
+        enable_file_generation: bool = False,
     ):
         """
         Initialize FilesystemManager.
@@ -75,6 +77,7 @@ class FilesystemManager:
             command_line_docker_memory_limit: Memory limit for Docker containers (e.g., "2g")
             command_line_docker_cpu_limit: CPU limit for Docker containers (e.g., 2.0 for 2 CPUs)
             command_line_docker_network_mode: Network mode for Docker containers (none/bridge/host)
+            command_line_docker_enable_sudo: Enable sudo access in Docker containers (isolated from host system)
         """
         self.agent_id = None  # Will be set by orchestrator via setup_orchestration_paths
         self.enable_image_generation = enable_image_generation
@@ -86,6 +89,7 @@ class FilesystemManager:
         self.command_line_docker_memory_limit = command_line_docker_memory_limit
         self.command_line_docker_cpu_limit = command_line_docker_cpu_limit
         self.command_line_docker_network_mode = command_line_docker_network_mode
+        self.command_line_docker_enable_sudo = command_line_docker_enable_sudo
 
         # Initialize Docker manager if Docker mode enabled
         self.docker_manager = None
@@ -97,6 +101,7 @@ class FilesystemManager:
                 network_mode=command_line_docker_network_mode,
                 memory_limit=command_line_docker_memory_limit,
                 cpu_limit=command_line_docker_cpu_limit,
+                enable_sudo=command_line_docker_enable_sudo,
             )
         self.enable_audio_generation = enable_audio_generation
 
@@ -360,6 +365,10 @@ class FilesystemManager:
         if self.command_line_execution_mode == "docker" and self.agent_id:
             config["args"].extend(["--agent-id", self.agent_id])
 
+        # Add sudo flag for Docker mode
+        if self.command_line_execution_mode == "docker" and self.command_line_docker_enable_sudo:
+            config["args"].append("--enable-sudo")
+
         # Add command filters if specified
         if self.command_line_allowed_commands:
             config["args"].extend(["--allowed-commands"] + self.command_line_allowed_commands)

massgen/filesystem_manager/_path_permission_manager.py

@@ -90,6 +90,68 @@ class PathPermissionManager:
         "massgen_logs",
     ]
 
+    # Binary file extensions that should not be read by text-based tools
+    # These files should be handled by specialized tools (understand_image, understand_video, etc.)
+    BINARY_FILE_EXTENSIONS = {
+        # Images
+        ".jpg",
+        ".jpeg",
+        ".png",
+        ".gif",
+        ".bmp",
+        ".ico",
+        ".svg",
+        ".webp",
+        ".tiff",
+        ".tif",
+        # Videos
+        ".mp4",
+        ".avi",
+        ".mov",
+        ".mkv",
+        ".flv",
+        ".wmv",
+        ".webm",
+        ".m4v",
+        ".mpg",
+        ".mpeg",
+        # Audio
+        ".mp3",
+        ".wav",
+        ".ogg",
+        ".flac",
+        ".aac",
+        ".m4a",
+        ".wma",
+        # Archives
+        ".zip",
+        ".tar",
+        ".gz",
+        ".bz2",
+        ".7z",
+        ".rar",
+        ".xz",
+        # Executables and binaries
+        ".exe",
+        ".bin",
+        ".dll",
+        ".so",
+        ".dylib",
+        ".o",
+        ".a",
+        ".pyc",
+        ".class",
+        ".jar",
+        # Office documents (binary formats - use understand_file tool)
+        ".doc",  # Old Word (not supported by understand_file)
+        ".xls",  # Old Excel (not supported by understand_file)
+        ".ppt",  # Old PowerPoint (not supported by understand_file)
+        ".pdf",  # PDF (supported by understand_file with PyPDF2)
+        ".docx",  # Word (supported by understand_file with python-docx)
+        ".xlsx",  # Excel (supported by understand_file with openpyxl)
+        ".pptx",  # PowerPoint (supported by understand_file with python-pptx)
+    }
+
     def __init__(
         self,
         context_write_access_enabled: bool = False,
@@ -440,6 +502,12 @@ class PathPermissionManager:
             - allowed: Whether the tool call should proceed
             - reason: Explanation if blocked (None if allowed)
         """
+        # Check if read tool is trying to read binary files (images, videos, etc.)
+        if self._is_text_read_tool(tool_name):
+            binary_check_result = self._validate_binary_file_access(tool_name, tool_args)
+            if not binary_check_result[0]:
+                return binary_check_result
+
         # Track read operations for read-before-delete enforcement
         if self._is_read_tool(tool_name):
             self._track_read_operation(tool_name, tool_args)
@@ -495,6 +563,33 @@ class PathPermissionManager:
 
         return False
 
+    def _is_text_read_tool(self, tool_name: str) -> bool:
+        """
+        Check if a tool is a text-based read operation that should not access binary files.
+
+        These tools are designed for reading text files and should be blocked from
+        reading binary files (images, videos, audio, etc.) to prevent context pollution.
+
+        Tools that read text file contents:
+        - Read: Claude Code read tool
+        - read_text_file: MCP filesystem read tool
+        - read_file: Generic read operations
+        """
+        # Use lowercase for case-insensitive matching
+        tool_lower = tool_name.lower()
+
+        # Check if tool name contains any text read operation keywords
+        text_read_keywords = [
+            "read_text_file",  # MCP filesystem: read_text_file
+            "read_file",  # Generic read operations
+        ]
+
+        # Also check for exact "Read" match (Claude Code tool)
+        if tool_name == "Read":
+            return True
+
+        return any(keyword in tool_lower for keyword in text_read_keywords)
+
     def _is_read_tool(self, tool_name: str) -> bool:
         """
         Check if a tool is a read operation that should be tracked.
@@ -518,6 +613,59 @@ class PathPermissionManager:
 
         return any(keyword in tool_lower for keyword in read_keywords)
 
+    def _validate_binary_file_access(self, tool_name: str, tool_args: Dict[str, Any]) -> Tuple[bool, Optional[str]]:
+        """
+        Validate that text-based read tools are not trying to read binary files.
+
+        Binary files (images, videos, audio, etc.) should be handled by specialized tools
+        to prevent context pollution with binary data.
+
+        Args:
+            tool_name: Name of the tool being called
+            tool_args: Arguments passed to the tool
+
+        Returns:
+            Tuple of (allowed: bool, reason: Optional[str])
+            - allowed: False if trying to read binary file, True otherwise
+            - reason: Explanation if blocked (None if allowed)
+        """
+        # Extract file path from arguments
+        file_path = self._extract_file_path(tool_args)
+        if not file_path:
+            # Can't determine path - allow (tool may not access files)
+            return (True, None)
+
+        # Resolve path
+        try:
+            file_path_str = self._resolve_path_against_workspace(file_path)
+            path = Path(file_path_str)
+        except Exception:
+            # If path resolution fails, allow (will fail elsewhere if invalid)
+            return (True, None)
+
+        # Check file extension
+        file_extension = path.suffix.lower()
+        if file_extension in self.BINARY_FILE_EXTENSIONS:
+            # Determine appropriate tool suggestion based on file type
+            if file_extension in {".jpg", ".jpeg", ".png", ".gif", ".bmp", ".ico", ".svg", ".webp", ".tiff", ".tif"}:
+                suggestion = "For images, use understand_image tool"
+            elif file_extension in {".mp4", ".avi", ".mov", ".mkv", ".flv", ".wmv", ".webm", ".m4v", ".mpg", ".mpeg"}:
+                suggestion = "For videos, use understand_video tool"
+            elif file_extension in {".mp3", ".wav", ".ogg", ".flac", ".aac", ".m4a", ".wma"}:
+                suggestion = "For audio files, use generate_text_with_input_audio tool"
+            elif file_extension in {".pdf"}:
+                suggestion = "For PDF files, use understand_file tool"
+            elif file_extension in {".docx", ".xlsx", ".pptx"}:
+                suggestion = "For Office documents, use understand_file tool"
+            else:
+                suggestion = "Use appropriate specialized tool for this file type"
+
+            reason = f"Cannot read binary file '{path.name}' with {tool_name}. {suggestion}."
+            logger.warning(f"[PathPermissionManager] Blocked {tool_name} from reading binary file: {path}")
+            return (False, reason)
+
+        return (True, None)
+
     def _is_delete_tool(self, tool_name: str) -> bool:
         """
         Check if a tool is a delete operation.