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

massgen/config_builder.py

@@ -191,27 +191,27 @@ class ConfigBuilder:
         },
         "multimodal": {
             "name": "Multimodal Analysis",
-            "description": "Analyze images, audio, and video content",
+            "description": "Analyze images, audio, video, and documents",
             "recommended_agents": 2,
             "recommended_tools": ["image_understanding", "audio_understanding", "video_understanding"],
             "agent_types": "all",
-            "notes": "Different backends support different modalities",
+            "notes": "Combines custom tools + built-in backend capabilities",
             "info": """[bold cyan]Features auto-configured for this preset:[/bold cyan]
 
-  [green]✓[/green] [bold]Image Understanding[/bold]
-    • Analyze images, screenshots, charts
-    • OCR and text extraction
-    • Available for: OpenAI, Claude Code, Gemini, Azure OpenAI
-
-  [green]✓[/green] [bold]Audio Understanding[/bold] [dim](where supported)[/dim]
-    • Transcribe and analyze audio
-    • Available for: Claude, ChatCompletion
+  [green]✓[/green] [bold]Custom Multimodal Tools (New v0.1.3+)[/bold]
+    • understand_image - Analyze workspace images with gpt-4.1
+    • understand_audio - Transcribe and analyze audio files
+    • understand_video - Extract frames and analyze videos
+    • understand_file - Process documents (PDF, DOCX, XLSX, PPTX)
+    • Works with any backend, processes workspace files
 
-  [green]✓[/green] [bold]Video Understanding[/bold] [dim](where supported)[/dim]
-    • Analyze video content
-    • Available for: Claude, ChatCompletion, OpenAI
+  [green]✓[/green] [bold]Built-in Backend Capabilities[/bold] [dim](passive)[/dim]
+    • Image understanding via upload_files (OpenAI, Claude, Gemini, Azure)
+    • Audio understanding via upload_files (Claude, ChatCompletion)
+    • Video understanding via upload_files (Claude, ChatCompletion, OpenAI)
+    • Image/audio/video generation (where supported)
 
-[dim]Use this for:[/dim] Image analysis, screenshot interpretation, multimedia content analysis.""",
+[dim]Use this for:[/dim] Image analysis, audio transcription, video analysis, document processing.""",
         },
     }
 
@@ -617,6 +617,20 @@ class ConfigBuilder:
             # Build choices for questionary - organized with tool hints
             choices = []
 
+            # Add spacing before first option (using spaces to avoid line)
+            choices.append(questionary.Separator(" "))
+
+            # First option: Browse existing configs (most common for new users)
+            choices.append(
+                questionary.Choice(
+                    title="📦  Browse ready-to-use configs / examples",
+                    value="__browse_existing__",
+                ),
+            )
+            choices.append(questionary.Separator(" "))
+            choices.append(questionary.Separator("┄┄ or build from template ┄┄"))
+            choices.append(questionary.Separator(" "))
+
             # Define display with brief tool descriptions
             display_info = [
                 ("custom", "⚙️", "Custom Configuration", "Choose your own tools"),
@@ -643,12 +657,12 @@ class ConfigBuilder:
                             value=use_case_id,
                         ),
                     )
+
                 except Exception as e:
                     console.print(f"[warning]⚠️  Could not display use case: {e}[/warning]")
 
             # Add helpful context before the prompt
-            console.print("[dim]Choose a preset that matches your task. Each preset auto-configures tools and capabilities.[/dim]")
-            console.print("[dim]You can customize everything in later steps.[/dim]\n")
+            console.print("[dim]Browse ready-to-use configs, or pick a template to build your own.[/dim]\n")
 
             use_case_id = questionary.select(
                 "Select your use case:",
@@ -666,6 +680,10 @@ class ConfigBuilder:
             if use_case_id is None:
                 raise KeyboardInterrupt  # User cancelled, exit immediately
 
+            # Handle special value for browsing existing configs
+            if use_case_id == "__browse_existing__":
+                return "__browse_existing__"
+
             # Show selection with description
             selected_info = self.USE_CASES[use_case_id]
             console.print(f"\n✅ Selected: [green]{selected_info.get('name', use_case_id)}[/green]")
@@ -1521,6 +1539,83 @@ class ConfigBuilder:
 
                         console.print(f"✅ Enabled {len(selected_gen)} generation capability(ies)")
 
+            # Custom multimodal understanding tools (new in v0.1.3+)
+            # Available for ALL use cases - these are active tools that process workspace files
+            console.print()
+            console.print("[cyan]Custom Multimodal Understanding Tools (New in v0.1.3+):[/cyan]")
+            console.print("[dim]These tools let agents analyze workspace files using OpenAI's gpt-4.1 API:[/dim]")
+            console.print("[dim]  • Works with any backend (uses OpenAI for analysis)[/dim]")
+            console.print("[dim]  • Processes files agents generate or discover during execution[/dim]")
+            console.print("[dim]  • Returns structured JSON with detailed metadata[/dim]")
+            console.print("[dim]  • Requires OPENAI_API_KEY in your .env file[/dim]")
+
+            # Default to True for multimodal use case, False for others
+            default_add_mm = use_case == "multimodal"
+
+            if questionary.confirm("Add custom multimodal understanding tools?", default=default_add_mm).ask():
+                # Determine default selections based on use case
+                if use_case == "multimodal":
+                    # For multimodal preset, select all by default
+                    pass
+                elif use_case == "data_analysis":
+                    # For data analysis, suggest image and file tools
+                    pass
+                else:
+                    # For other use cases, none selected by default (let user choose)
+                    pass
+
+                if use_case == "multimodal":
+                    multimodal_tool_choices = [
+                        questionary.Choice("understand_image - Analyze images (PNG, JPEG, JPG)", value="understand_image", checked=True),
+                        questionary.Choice("understand_audio - Transcribe and analyze audio", value="understand_audio", checked=True),
+                        questionary.Choice("understand_video - Extract frames and analyze video", value="understand_video", checked=True),
+                        questionary.Choice("understand_file - Process documents (PDF, DOCX, XLSX, PPTX)", value="understand_file", checked=True),
+                    ]
+                elif use_case == "data_analysis":
+                    multimodal_tool_choices = [
+                        questionary.Choice("understand_image - Analyze images (PNG, JPEG, JPG)", value="understand_image", checked=True),
+                        questionary.Choice("understand_audio - Transcribe and analyze audio", value="understand_audio", checked=False),
+                        questionary.Choice("understand_video - Extract frames and analyze video", value="understand_video", checked=False),
+                        questionary.Choice("understand_file - Process documents (PDF, DOCX, XLSX, PPTX)", value="understand_file", checked=True),
+                    ]
+                else:
+                    multimodal_tool_choices = [
+                        questionary.Choice("understand_image - Analyze images (PNG, JPEG, JPG)", value="understand_image", checked=False),
+                        questionary.Choice("understand_audio - Transcribe and analyze audio", value="understand_audio", checked=False),
+                        questionary.Choice("understand_video - Extract frames and analyze video", value="understand_video", checked=False),
+                        questionary.Choice("understand_file - Process documents (PDF, DOCX, XLSX, PPTX)", value="understand_file", checked=False),
+                    ]
+
+                selected_mm_tools = questionary.checkbox(
+                    "Select custom multimodal tools (Space to select, Enter to confirm):",
+                    choices=multimodal_tool_choices,
+                    style=questionary.Style(
+                        [
+                            ("selected", "fg:cyan"),
+                            ("pointer", "fg:cyan bold"),
+                            ("highlighted", "fg:cyan"),
+                        ],
+                    ),
+                    use_arrow_keys=True,
+                ).ask()
+
+                if selected_mm_tools:
+                    # Initialize custom_tools list if not exists
+                    if "custom_tools" not in agent["backend"]:
+                        agent["backend"]["custom_tools"] = []
+
+                    # Add selected tools
+                    for tool_name in selected_mm_tools:
+                        tool_config = {
+                            "name": [tool_name],
+                            "category": "multimodal",
+                            "path": f"massgen/tool/_multimodal_tools/{tool_name}.py",
+                            "function": [tool_name],
+                        }
+                        agent["backend"]["custom_tools"].append(tool_config)
+
+                    console.print(f"✅ Added {len(selected_mm_tools)} custom multimodal tool(s)")
+
             # MCP servers (custom only)
             # Note: Filesystem is handled internally above, NOT as external MCP
             if "mcp" in provider_info.get("supports", []):
@@ -1807,12 +1902,18 @@ class ConfigBuilder:
                             "code_execution": "💻 Code execution",
                             "web_search": "🔍 Web search",
                             "mcp": "🔌 MCP servers",
+                            "image_understanding": "📷 Image understanding (backend capability)",
+                            "audio_understanding": "🎵 Audio understanding (backend capability)",
+                            "video_understanding": "🎬 Video understanding (backend capability)",
                         }.get(tool, tool)
                         console.print(f"    • {tool_display}")
 
                     if use_case == "coding_docker":
                         console.print("    • 🐳 Docker isolated execution")
 
+                    if use_case == "multimodal":
+                        console.print("    • 🎨 Custom multimodal tools (understand_image, understand_audio, understand_video, understand_file)")
+
                     console.print()
 
                 # Let users select models for each agent
@@ -2302,7 +2403,7 @@ class ConfigBuilder:
                 orchestrator_config = {}
             orchestrator_config["session_storage"] = "sessions"
             console.print()
-            console.print("  ✅ Multi-turn sessions enabled (supports persistent conversations with memory)")
+            console.print("  ✅ Multi-turn sessions enabled (supports persistent conversations)")
 
             # Planning Mode (for MCP irreversible actions) - only ask if MCPs are configured
             has_mcp = any(a.get("backend", {}).get("mcp_servers") for a in agents)
@@ -2321,6 +2422,30 @@ class ConfigBuilder:
                     console.print()
                     console.print("  ✅ Planning mode enabled - MCP tools will plan without executing during coordination")
 
+            # Orchestration Restart Feature
+            console.print()
+            console.print("  [dim]Orchestration Restart: Automatic quality checks with self-correction[/dim]")
+            console.print("  [dim]• Agent evaluates its own answer after coordination[/dim]")
+            console.print("  [dim]• Can restart with specific improvement instructions if incomplete[/dim]")
+            console.print("  [dim]• Each attempt gets isolated logs in attempt_1/, attempt_2/, etc.[/dim]")
+            console.print("  [dim]• Works with all backends (OpenAI, Claude, Gemini, Grok, etc.)[/dim]")
+            console.print("  [dim]• 0 = no restarts (default), 1-2 = recommended, 3 = maximum[/dim]")
+            console.print()
+
+            restart_input = Prompt.ask(
+                "  [prompt]Max orchestration restarts (0-3)[/prompt]",
+                choices=["0", "1", "2", "3"],
+                default="0",
+            )
+
+            max_restarts = int(restart_input)
+            if max_restarts > 0:
+                if "coordination" not in orchestrator_config:
+                    orchestrator_config["coordination"] = {}
+                orchestrator_config["coordination"]["max_orchestration_restarts"] = max_restarts
+                console.print()
+                console.print(f"  ✅ Orchestration restart enabled: up to {max_restarts} restart(s) allowed")
+
             # Voting Sensitivity - only ask for multi-agent setups
             if len(agents) > 1:
                 console.print()
@@ -2634,6 +2759,21 @@ class ConfigBuilder:
                     console.print("[warning]⚠️  No use case selected.[/warning]")
                     return None
 
+                # Handle special case: user wants to browse existing configs
+                if use_case == "__browse_existing__":
+                    console.print("\n[cyan]Opening config selector...[/cyan]\n")
+                    # Import here to avoid circular dependency
+                    from .cli import interactive_config_selector
+
+                    selected_config = interactive_config_selector()
+                    if selected_config:
+                        console.print(f"\n[green]✓ Selected config: {selected_config}[/green]\n")
+                        # Return the selected config as if it was created
+                        return (selected_config, None)
+                    else:
+                        console.print("\n[yellow]⚠️  No config selected[/yellow]\n")
+                        return None
+
                 # Step 2: Configure agents
                 agents = self.configure_agents(use_case, api_keys)
                 if not agents:
@@ -2652,7 +2792,12 @@ class ConfigBuilder:
                 filepath = self.review_and_save(agents, orchestrator_config)
 
                 if filepath:
-                    # Ask if user wants to run now
+                    # In default_mode (first-run), skip "Run now?" and go straight to interactive mode
+                    if self.default_mode:
+                        # Config already saved by review_and_save(), just return to launch interactive mode
+                        return (filepath, None)
+
+                    # In regular --init mode, ask if user wants to run now
                     run_choice = Confirm.ask("\n[prompt]Run MassGen with this configuration now?[/prompt]", default=True)
                     if run_choice is None:
                         raise KeyboardInterrupt  # User cancelled

massgen/configs/README.md

@@ -227,15 +227,73 @@ Most configurations use environment variables for API keys:so
 
 ## Release History & Examples
 
-### v0.1.2 - Latest
+### v0.1.4 - Latest
+**New Features:** Multimodal Generation Tools, Binary File Protection, Crawl4AI Integration
+
+**Configuration Files:**
+- `text_to_image_generation_single.yaml` / `text_to_image_generation_multi.yaml` - Image generation
+- `text_to_video_generation_single.yaml` / `text_to_video_generation_multi.yaml` - Video generation
+- `text_to_speech_generation_single.yaml` / `text_to_speech_generation_multi.yaml` - Audio generation
+- `text_to_file_generation_single.yaml` / `text_to_file_generation_multi.yaml` - Document generation
+- `crawl4ai_example.yaml` - Web scraping configuration
+
+**Documentation:**
+- `README_PYPI.md` - Standalone PyPI package documentation
+- `docs/dev_notes/release_checklist.md` - Release workflow guide
+- `docs/source/user_guide/protected_paths.rst` - Binary file protection documentation
+- `.github/workflows/docs-automation.yml` - Documentation CI/CD automation
+
+**Key Features:**
+- **Generation Tools**: Create images, videos, audio, and documents using OpenAI APIs
+- **Binary File Protection**: Automatic blocking prevents text tools from reading 40+ binary file types
+- **Web Scraping**: Crawl4AI integration for intelligent content extraction
+- **Enhanced Security**: Smart tool suggestions guide users to appropriate specialized tools
+
+**Try it:**
+```bash
+# Install or upgrade
+pip install --upgrade massgen
+
+# Generate an image from text
+massgen --config @examples/tools/custom_tools/multimodal_tools/text_to_image_generation_single \
+  "Please generate an image of a cat in space."
+
+# Generate a video from text
+massgen --config @examples/tools/custom_tools/multimodal_tools/text_to_video_generation_single \
+  "Generate a 4 seconds video with neon-lit alley at night, light rain, slow push-in, cinematic."
+
+# Generate documents (PDF, DOCX, etc.)
+massgen --config @examples/tools/custom_tools/multimodal_tools/text_to_file_generation_single \
+  "Please generate a comprehensive technical report about the latest developments in Large Language Models (LLMs)."
+```
+
+### v0.1.3
+**New Features:** Post-Evaluation Workflow, Custom Multimodal Understanding Tools, Docker Sudo Mode
+
+**Configuration Files:**
+- `understand_image.yaml`, `understand_audio.yaml`, `understand_video.yaml`, `understand_file.yaml`
+
+**Key Features:**
+- **Post-Evaluation Tools**: Submit and restart capabilities for winning agents
+- **Multimodal Understanding**: Analyze images, audio, video, and documents
+- **Docker Sudo Mode**: Execute privileged commands in containers
+
+**Try it:**
+```bash
+# Try multimodal image understanding
+massgen --config @examples/tools/custom_tools/multimodal_tools/understand_image \
+  "Please summarize the content in this image."
+```
+
+### v0.1.2
 **New Features:** Intelligent Planning Mode, Claude 4.5 Haiku Support, Grok Web Search Improvements
 
 **Configuration Files:**
-- `massgen/configs/tools/planning/` - 5 planning mode configurations with selective blocking
-- `massgen/configs/basic/multi/three_agents_default.yaml` - Updated with Grok-4-fast model
+- `configs/tools/planning/` - 5 planning mode configurations with selective blocking
+- `configs/basic/multi/three_agents_default.yaml` - Updated with Grok-4-fast model
 
 **Documentation:**
-- `docs/case_studies/INTELLIGENT_PLANNING_MODE.md` - Complete intelligent planning mode guide
+- `docs/dev_notes/intelligent_planning_mode.md` - Complete intelligent planning mode guide
 
 **Key Features:**
 - **Intelligent Planning Mode**: Automatic analysis of question irreversibility for dynamic MCP tool blocking
@@ -245,9 +303,6 @@ Most configurations use environment variables for API keys:so
 
 **Try it:**
 ```bash
-# Install or upgrade
-pip install --upgrade massgen
-
 # Try intelligent planning mode with MCP tools
 # (Please read the YAML file for required API keys: DISCORD_TOKEN, OPENAI_API_KEY, etc.)
 massgen --config @examples/tools/planning/five_agents_discord_mcp_planning_mode \
@@ -346,7 +401,7 @@ massgen --config @examples/tools/code-execution/docker_with_resource_limits \
 - `massgen/configs/basic/single/single_gpt4o_video_generation.yaml` - Video generation with OpenAI Sora-2
 
 **Case Study:**
-- [Universal Code Execution via MCP](../../docs/case_studies/universal-code-execution-mcp.md)
+- [Universal Code Execution via MCP](../../docs/source/examples/case_studies/universal-code-execution-mcp.md)
 
 **Key Features:**
 - Universal `execute_command` tool works across Claude, Gemini, OpenAI (Response API), and Chat Completions providers (Grok, ZAI, etc.)
@@ -419,7 +474,7 @@ massgen --config @examples/tools/filesystem/cc_gpt5_gemini_filesystem \
 - New `FileOperationTracker` class for read-before-delete enforcement
 - Enhanced PathPermissionManager with operation tracking methods
 
-**Case Study:** [MCP Planning Mode](../../docs/case_studies/mcp-planning-mode.md)
+**Case Study:** [MCP Planning Mode](../../docs/source/examples/case_studies/mcp-planning-mode.md)
 
 **Try it:**
 ```bash
@@ -446,7 +501,7 @@ massgen --config @examples/tools/planning/five_agents_twitter_mcp_planning_mode
 - New `ExternalAgentBackend` class bridging MassGen with external frameworks
 - Multiple code executor types: LocalCommandLineCodeExecutor, DockerCommandLineCodeExecutor, JupyterCodeExecutor, YepCodeCodeExecutor
 
-**Case Study:** [AG2 Framework Integration](../../docs/case_studies/ag2-framework-integration.md)
+**Case Study:** [AG2 Framework Integration](../../docs/source/examples/case_studies/ag2-framework-integration.md)
 
 **Try it:**
 ```bash
@@ -515,7 +570,7 @@ massgen --config @examples/tools/filesystem/gemini_gpt5nano_file_context_path \
 - Automatic `.massgen` directory management for persistent conversation context
 - Enhanced path permissions with `will_be_writable` flag and smart exclusion patterns
 
-**Case Study:** [Multi-Turn Filesystem Support](../../docs/case_studies/multi-turn-filesystem-support.md)
+**Case Study:** [Multi-Turn Filesystem Support](../../docs/source/examples/case_studies/multi-turn-filesystem-support.md)
 ```bash
 # Turn 1 - Initial creation
 Turn 1: Make a website about Bob Dylan
@@ -553,7 +608,7 @@ massgen --config @examples/basic/multi/two_qwen_vllm \
 - All configs now organized by provider & use case (basic/, providers/, tools/, teams/)
 - Use same configs as v0.0.21 for compatibility, but now with improved performance
 
-**Case Study:** [Advanced Filesystem with User Context Path Support](../../docs/case_studies/v0.0.21-v0.0.22-filesystem-permissions.md)
+**Case Study:** [Advanced Filesystem with User Context Path Support](../../docs/source/examples/case_studies/v0.0.21-v0.0.22-filesystem-permissions.md)
 ```bash
 # Multi-agent collaboration with granular filesystem permissions
 massgen --config @examples/tools/filesystem/gpt5mini_cc_fs_context_path "Enhance the website in massgen/configs/resources with: 1) A dark/light theme toggle with smooth transitions, 2) An interactive feature that helps users engage with the blog content (your choice - could be search, filtering by topic, reading time estimates, social sharing, reactions, etc.), and 3) Visual polish with CSS animations or transitions that make the site feel more modern and responsive. Use vanilla JavaScript and be creative with the implementation details."
@@ -599,7 +654,7 @@ massgen --config @examples/tools/mcp/gpt5_nano_mcp_example \
 
 ### v0.0.16
 **New Features:** Unified Filesystem Support with MCP Integration
-**Case Study:** [Cross-Backend Collaboration with Gemini MCP Filesystem](../../docs/case_studies/unified-filesystem-mcp-integration.md)
+**Case Study:** [Cross-Backend Collaboration with Gemini MCP Filesystem](../../docs/source/examples/case_studies/unified-filesystem-mcp-integration.md)
 ```bash
 # Gemini and Claude Code agents with unified filesystem via MCP
 massgen --config @examples/tools/mcp/gemini_mcp_filesystem_test_with_claude_code "Create a presentation that teaches a reinforcement learning algorithm and output it in LaTeX Beamer format. No figures should be added."
@@ -612,7 +667,7 @@ massgen --config @examples/tools/mcp/gemini_mcp_filesystem_test_with_claude_code
 
 ### v0.0.12 - v0.0.14
 **New Features:** Enhanced Logging and Workspace Management
-**Case Study:** [Claude Code Workspace Management with Comprehensive Logging](../../docs/case_studies/claude-code-workspace-management.md)
+**Case Study:** [Claude Code Workspace Management with Comprehensive Logging](../../docs/source/examples/case_studies/claude-code-workspace-management.md)
 ```bash
 # Multi-agent Claude Code collaboration with enhanced workspace isolation
 massgen --config @examples/tools/filesystem/claude_code_context_sharing "Create a website about a diverse set of fun facts about LLMs, placing the output in one index.html file"

massgen/configs/debug/restart_test_controlled.yaml

@@ -0,0 +1,60 @@
+# Two Agent Orchestration Restart Test Configuration (No Filesystem)
+# This configuration demonstrates the orchestration restart feature for self-correcting coordination
+# Uses debug_final_answer to force restart on first attempt for testing
+#
+# Setup Requirements:
+# 1. Set environment variable in .env file:
+#    OPENAI_API_KEY="your_openai_key"
+#
+# Example usage:
+# massgen --config @examples/configs/debug/restart_test_controlled.yaml "Describe two famous Beatles members: John Lennon and Paul McCartney. Include their birth year, role in the band, and notable contributions."
+#
+# Expected behavior:
+# - Attempt 1: Agents coordinate, final presentation shows debug override (incomplete answer)
+# - Post-evaluation detects incomplete answer and calls restart_orchestration()
+# - Restart banner displays with reason and instructions
+# - Attempt 2: Agents see restart context and produce complete answer
+# - Post-evaluation approves and calls submit()
+# - Inspection menu appears
+
+agents:
+  - id: "agent_a"
+    backend:
+      type: "openai"
+      model: "gpt-5-nano"
+      # type: "gemini"
+      # model: "gemini-2.5-flash"
+      # type: "grok"
+      # model: "grok-4-fast"
+      # type: "claude"
+      # model: "claude-sonnet-4-5-20250929"
+      # type: "claude_code"
+      # model: "claude-sonnet-4-5-20250929"
+      # cwd: "workspace1"
+
+  - id: "agent_b"
+    backend:
+      type: "openai"
+      model: "gpt-5-nano"
+
+orchestrator:
+  snapshot_storage: "snapshots"
+  agent_temporary_workspace: "temp_workspaces"
+
+  # Restart configuration
+  coordination:
+    max_orchestration_restarts: 2  # Allow up to 2 restarts (3 total attempts)
+
+  # DEBUG MODE: Override final answer on attempt 1 to simulate incomplete response
+  debug_final_answer: |
+    John Lennon was born in 1940 in Liverpool, England. He was a founding member
+    of The Beatles and served as rhythm guitarist and vocalist. He co-wrote many
+    of the band's greatest hits with Paul McCartney. After the Beatles disbanded,
+    he pursued a successful solo career and became known for his peace activism.
+
+  # Use lenient voting for faster coordination in debug mode
+  voting_sensitivity: "lenient"
+
+ui:
+  display_type: "rich_terminal"
+  logging_enabled: true

massgen/configs/debug/restart_test_controlled_filesystem.yaml

@@ -0,0 +1,73 @@
+# Two Agent Orchestration Restart Test Configuration with Filesystem
+# This configuration demonstrates the orchestration restart feature with MCP filesystem tools
+# Uses debug_final_answer to force restart on first attempt for testing file creation tasks
+#
+# Setup Requirements:
+# 1. Set environment variable in .env file:
+#    OPENAI_API_KEY="your_openai_key"
+# 2. Filesystem MCP servers will be automatically available via npx
+#
+# Example usage:
+# massgen --config @examples/configs/debug/restart_test_controlled_filesystem.yaml "Create three Python files: main.py with a hello() function, utils.py with a helper() function, and tests.py with a test_hello() function."
+#
+# Expected behavior:
+# - Attempt 1: Agents coordinate with planning mode (no file execution during coordination)
+# - Final presentation shows debug override claiming only main.py was created
+# - Post-evaluation uses MCP tools to verify files and detects missing files
+# - Calls restart_orchestration() with specific instructions
+# - Restart banner displays
+# - Attempt 2: Agents coordinate with restart instructions to create ALL files
+# - Post-evaluation verifies all files exist using MCP tools
+# - Calls submit() - Inspection menu appears
+
+agents:
+  - id: "agent_a"
+    backend:
+      type: "openai"
+      model: "gpt-5-nano"
+      # type: "gemini"
+      # model: "gemini-2.5-flash"
+      # type: "grok"
+      # model: "grok-4-fast"
+      # type: "claude"
+      # model: "claude-sonnet-4-5-20250929"
+      # type: "claude_code"
+      # model: "claude-sonnet-4-5-20250929"
+      cwd: "workspace1"
+
+  # - id: "agent_b"
+  #   backend:
+  #     type: "openai"
+  #     model: "gpt-5-nano"
+  #     cwd: "workspace2"
+
+orchestrator:
+  snapshot_storage: "snapshots"
+  agent_temporary_workspace: "temp_workspaces"
+
+  # Restart configuration
+  coordination:
+    max_orchestration_restarts: 2  # Allow up to 2 restarts (3 total attempts)
+
+  # DEBUG MODE: Override final answer on attempt 1 to simulate incomplete file creation
+  debug_final_answer: |
+    I created a hello.txt file.
+
+   #  file with the following content:
+
+   # ```python
+   # def hello():
+   #     print("Hello, World!")
+
+   # if __name__ == "__main__":
+   #     hello()
+   # ```
+
+  # The file has been created successfully.
+
+  # Use lenient voting for faster coordination in debug mode
+  voting_sensitivity: "lenient"
+
+ui:
+  display_type: "rich_terminal"
+  logging_enabled: true

massgen/configs/tools/code-execution/docker_with_sudo.yaml

@@ -0,0 +1,35 @@
+# Docker Isolation with Sudo Support
+# Run with: uv run python -m massgen.cli --config massgen/configs/tools/code-execution/docker_with_sudo.yaml "Write a factorial function and test it"
+# Expected behavior: Commands execute in isolated Docker container with sudo access for runtime package installation
+#
+# Prerequisites:
+#   1. Docker installed and running
+#   2. Build sudo image FIRST: bash massgen/docker/build.sh --sudo
+#
+# Security: Safe for most use cases - Docker container isolation prevents host access even with sudo.
+
+agent:
+  id: "docker_sudo_agent"
+  backend:
+    type: "openai"
+    model: "gpt-5-mini"
+    cwd: "workspace1"
+
+    # Enable command execution with Docker isolation and sudo
+    enable_mcp_command_line: true
+    command_line_execution_mode: "docker"
+    command_line_docker_enable_sudo: true  # Enables sudo in container
+
+    # Optional: Specify custom image (default auto-switches to sudo variant)
+    # command_line_docker_image: "massgen/mcp-runtime-sudo:latest"
+
+orchestrator:
+  snapshot_storage: "snapshots"
+  agent_temporary_workspace: "temp_workspaces"
+
+timeout_settings:
+  orchestrator_timeout_seconds: 180  # Docker startup adds ~5-10s overhead
+
+ui:
+  display_type: "rich_terminal"
+  logging_enabled: true

massgen/configs/tools/custom_tools/computer_use_browser_example.yaml

@@ -0,0 +1,56 @@
+# MassGen Configuration: Computer Use - Browser Automation
+#
+# This configuration is optimized for browser-based tasks using Playwright.
+#
+# Usage:
+#   massgen --config @examples/tools/custom_tools/computer_use_browser_example "Check the latest OpenAI news on bing.com"
+#
+# Prerequisites:
+#   1. Set OPENAI_API_KEY in your .env file
+#   2. Install Playwright: pip install playwright && playwright install
+
+agents:
+  - id: "browser_automation_agent"
+    backend:
+      type: "openai"
+      model: "computer-use-preview"
+      custom_tools:
+        - name: ["computer_use"]
+          category: "automation"
+          path: "massgen/tool/_computer_use/computer_use_tool.py"
+          function: ["computer_use"]
+          # Default parameters for browser automation
+          default_params:
+            environment: "browser"
+            display_width: 1280
+            display_height: 720
+            max_iterations: 30
+            include_reasoning: true
+
+    system_message: |
+      You are a browser automation specialist with access to the computer_use tool.
+
+      Your capabilities include:
+      - Web navigation and search
+      - Form filling and submission
+      - Data extraction from websites
+      - Multi-step web workflows
+      - Screenshot capture and analysis
+
+      When using the computer_use tool:
+      1. Provide clear, specific task descriptions
+      2. The tool operates in a browser environment (Playwright)
+      3. You'll receive screenshots after each action
+      4. Acknowledge safety warnings when they appear
+      5. Be patient - complex tasks may require multiple iterations
+
+      Best practices:
+      - Break complex tasks into simple steps
+      - Verify each step completed successfully before proceeding
+      - Use wait actions when pages are loading
+      - Be specific about what you're looking for on the page
+
+ui:
+  display_type: "detailed"
+  logging_enabled: true
+  show_screenshots: true