first version

.gitignore

@@ -0,0 +1,23 @@
+# Environment
+.env.*
+
+# Python
+__pycache__/
+*.py[cod]
+*.so
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+
+# IDE
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+.cursor/
+.env

README.md

@@ -1,14 +1,273 @@
 ---
 title: Fire Rescue Simulator Game
-emoji: 👁
+emoji: 🔥
 colorFrom: red
-colorTo: red
+colorTo: blue
 sdk: gradio
 sdk_version: 6.0.1
 app_file: app.py
 pinned: false
 license: mit
 short_description: AI Agent autonomously fights fires using MCP tools
+tags:
+- mcp-in-action-track-creative
+- mcp-1st-birthday
+- game
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🔥 Fire Rescue Simulator Game
+
+An AI-powered fire rescue simulation where an **autonomous agent** analyzes tactical situations and deploys firefighting units using **Model Context Protocol (MCP)** tools.
+
+---
+
+## 🎥 Demo Video
+
+[![Demo Video](https://img.shields.io/badge/▶️_Watch_Demo-YouTube-red?style=for-the-badge&logo=youtube)](https://youtu.be/YOUR_VIDEO_ID)
+
+> 📹 *Coming soon! Demo video will be added before submission deadline.*
+
+---
+
+## 🌟 Project Overview
+
+> *An interactive game where you watch AI Agent autonomously fight fires using MCP tools!*  
+> Take control, collaborate with AI, or let it run fully autonomous. Your choice!
+
+This project demonstrates how AI agents can leverage **MCP (Model Context Protocol)** tools to make autonomous decisions in real-time tactical scenarios. The AI Advisor:
+
+1. 📊 **Queries** the simulation state using MCP tools
+2. 🎯 **Analyzes** fire threats, building integrity, and unit coverage
+3. ⚡ **Executes** deployment decisions through MCP tool calls
+4. 🔄 **Adapts** strategy based on changing battlefield conditions
+
+### Key Highlights
+
+- **🤖 Autonomous AI Agent**: Watches the battlefield and makes tactical decisions without human intervention
+- **🔧 8 MCP Tools**: Rich set of tools for state queries, analysis, and unit deployment
+- **🎨 Beautiful Gradio 6 UI**: Real-time visualization with emoji-based grid map
+- **📊 Transparent Reasoning**: Watch AI's thought process in real-time
+- **🎮 Hybrid Control**: Toggle between full AI autonomy and manual control
+
+---
+
+## 🛠️ MCP Tools
+
+The Fire-Rescue MCP Server exposes **8 functional tools** for AI agents:
+
+### Core Operations
+
+| Tool | Description |
+|------|-------------|
+| `reset_scenario` | Initialize a new simulation with configurable parameters |
+| `get_world_state` | Get complete world state snapshot with emoji map |
+| `deploy_unit` | Deploy a firefighting unit at specified coordinates |
+| `move_unit` | Reposition an existing unit to a new location |
+| `remove_unit` | Remove a unit (frees slot for redeployment elsewhere) |
+| `step_simulation` | Advance simulation by N ticks |
+
+### Data Query & Analysis
+
+| Tool | Description |
+|------|-------------|
+| `find_idle_units` | Identify units not covering any active fires |
+| `find_uncovered_fires` | Find fires with no unit coverage |
+| `find_building_threats` | Detect fires threatening buildings |
+| `analyze_coverage` | Comprehensive coverage analysis data |
+
+---
+
+## 🔄 Architecture & Workflow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Gradio 6 Web UI                          │
+│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────┐  │
+│  │ Control Panel│  │ 10x10 Grid   │  │  AI Advisor Panel     │  │
+│  │ Start/Pause  │  │ 🌲🔥🚒🏢🚁   │  │  • Reasoning          │  │
+│  │ Reset/Config │  │ Click Deploy │  │  • Tool Calls         │  │
+│  └──────────────┘  └──────────────┘  │  • Recommendations    │  │
+│                                       └───────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      Background Service                          │
+│  ┌──────────────────┐    ┌────────────────────────────────────┐ │
+│  │ Simulation Engine │◄──►│         AI Advisor Agent          │ │
+│  │ • Fire spread     │    │ • HuggingFace Inference Provider  │ │
+│  │ • Unit behavior   │    │ • MCP Tool Invocation             │ │
+│  │ • Win/Lose logic  │    │ • Strategy Planning               │ │
+│  └──────────────────┘    └────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      MCP Server (FastMCP)                        │
+│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐  │
+│  │reset_scenario│ │get_world_   │ │deploy_unit  │ │move_unit  │  │
+│  └─────────────┘ │state        │ └─────────────┘ └───────────┘  │
+│  ┌─────────────┐ └─────────────┘ ┌─────────────┐ ┌───────────┐  │
+│  │step_        │ ┌─────────────┐ │find_uncov-  │ │find_build-│  │
+│  │simulation   │ │find_idle_   │ │ered_fires   │ │ing_threats│  │
+│  └─────────────┘ │units        │ └─────────────┘ └───────────┘  │
+│                  └─────────────┘ ┌─────────────────────────────┐ │
+│                                  │     analyze_coverage        │ │
+│                                  └─────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🧩 Core Components
+
+### 🤖 AI Advisor Agent (`agent.py`)
+
+- **Role**: Autonomous tactical advisor
+- **LLM**: HuggingFace Inference Provider (`openai/gpt-oss-120b`)
+- **Responsibilities**:
+  - Analyze battlefield state via MCP tools
+  - Generate deployment recommendations
+  - Execute strategies when auto-execute is enabled
+
+### 🎮 Simulation Engine (`simulation.py`)
+
+- **Role**: Core game logic
+- **Features**:
+  - 2D grid-based fire spread simulation
+  - Unit behavior (fire trucks & helicopters)
+  - Building integrity tracking
+  - Win/Lose condition evaluation
+
+### 🔧 MCP Server (`fire_rescue_mcp/mcp_server.py`)
+
+- **Role**: Expose simulation as MCP tools
+- **Framework**: FastMCP
+- **Tools**: 8 functional tools for state queries and actions
+
+### 🎨 Web Interface (`app.py`)
+
+- **Role**: User interface
+- **Framework**: Gradio 6
+- **Features**:
+  - Real-time emoji grid visualization
+  - AI reasoning panel with tool call history
+  - Interactive unit deployment
+  - Auto-execute toggle
+
+---
+
+## 🎯 Game Rules
+
+### Units
+
+| Unit | Symbol | Power | Range | Best For |
+|------|--------|-------|-------|----------|
+| Fire Truck | 🚒 | 40% | Covers 1 tile outward | High-intensity fires & building threats |
+| Helicopter | 🚁 | 25% | Covers 2 tiles outward | Wide area coverage |
+
+### Win/Lose Conditions
+
+- **🏆 Victory**: All fires extinguished (intensity < 10%)
+- **💀 Game Over**: 
+  - Building integrity drops below 50%
+  - Forest burn ratio exceeds 80%
+  - Time limit exceeded (200 ticks)
+
+### Map Legend
+
+| Symbol | Meaning |
+|--------|---------|
+| 🌲 | Forest |
+| 🏢 | Building |
+| 🔥 | Active Fire (≥10% intensity) |
+| 💨 | Smoke (<10% intensity) |
+| 🚒 | Fire Truck |
+| 🚁 | Helicopter |
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Python 3.10+
+- HuggingFace API Token (for AI Advisor)
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/ArkaiAriza/fire-rescue-mcp.git
+cd fire-rescue-mcp
+
+# Install with UV (recommended)
+uv sync
+
+# Or install with pip
+pip install -e .
+```
+
+### Configuration
+
+Set your HuggingFace token:
+
+```bash
+export HF_TOKEN=your-huggingface-token-here
+```
+
+Or create a `.env` file:
+
+```
+HF_TOKEN=your-huggingface-token-here
+```
+
+### Launch
+
+```bash
+# Start the Gradio web app
+uv run python app.py
+
+# Or run as module
+python -m app
+```
+
+Then open http://localhost:7860 in your browser.
+
+---
+
+## 📁 Project Structure
+
+```
+fire-rescue-mcp/
+├── app.py                    # Gradio web application (entry point)
+├── service.py                # Background simulation service
+├── agent.py                  # LLM advisor agent
+├── simulation.py             # Simulation engine (fire spread, unit behavior)
+├── models.py                 # Data structures (WorldState, Unit, Fire, etc.)
+├── prompts.yaml              # AI advisor prompts
+├── fire_rescue_mcp/          # MCP core package
+│   ├── __init__.py           # Package exports
+│   └── mcp_server.py         # MCP server with 8 tools
+├── pyproject.toml            # Project configuration
+├── requirements.txt          # Python dependencies
+└── README.md                 # This file
+```
+
+---
+
+## 🛠️ Technologies Used
+
+| Technology | Purpose |
+|------------|---------|
+| **Gradio 6** | Web UI framework |
+| **FastMCP** | MCP server implementation |
+| **HuggingFace Inference** | LLM provider for AI Advisor |
+| **UV** | Package management |
+| **Python 3.10+** | Core language |
+
+---
+
+## 📝 License
+
+This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

agent.py

@@ -0,0 +1,1280 @@
+"""
+Fire-Rescue - Multi-Stage LLM Advisor Agent
+
+Provides advisory recommendations based on world state analysis using a
+multi-stage approach: Assessment → Planning → Execution.
+
+The agent only suggests actions; it does not directly control units.
+All analysis is performed by the AI - no rule-based fallback.
+
+Uses HuggingFace Inference Provider API with openai/gpt-oss-120b model.
+"""
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+import yaml
+from openai import OpenAI
+
+# Load .env file if it exists
+try:
+    from dotenv import load_dotenv
+    env_path = Path(__file__).parent / ".env"
+    if env_path.exists():
+        load_dotenv(env_path)
+except ImportError:
+    pass  # dotenv not installed, rely on environment variables
+
+
+# =============================================================================
+# HuggingFace Inference Provider Configuration
+# =============================================================================
+
+# HuggingFace Inference Provider base URL (OpenAI-compatible)
+HF_INFERENCE_BASE_URL = "https://router.huggingface.co/v1"
+HF_DEFAULT_MODEL = "openai/gpt-oss-120b"
+
+def get_hf_token() -> str | None:
+    """
+    Get HuggingFace token from environment variable.
+    
+    Returns:
+        HF_TOKEN if available, None otherwise
+    """
+    return os.getenv("HF_TOKEN")
+
+
+# =============================================================================
+# Load Prompts from Configuration
+# =============================================================================
+
+def load_prompts() -> dict:
+    """Load prompts from prompts.yaml configuration file."""
+    prompts_path = Path(__file__).parent / "prompts.yaml"
+    if prompts_path.exists():
+        with open(prompts_path, "r", encoding="utf-8") as f:
+            return yaml.safe_load(f)
+    return {}
+
+PROMPTS_CONFIG = load_prompts()
+
+
+# =============================================================================
+# Data Models
+# =============================================================================
+
+@dataclass
+class Recommendation:
+    """A single deployment or move recommendation from the advisor."""
+    reason: str
+    suggested_unit_type: str
+    target_x: int
+    target_y: int
+    action: str = "deploy"  # "deploy", "move", or "remove"
+    source_x: int = -1  # For move action: source position
+    source_y: int = -1
+    
+    def to_dict(self) -> dict:
+        result = {
+            "reason": self.reason,
+            "suggested_unit_type": self.suggested_unit_type,
+            "target": {"x": self.target_x, "y": self.target_y},
+            "action": self.action
+        }
+        if self.action == "move":
+            result["source"] = {"x": self.source_x, "y": self.source_y}
+        return result
+
+
+@dataclass
+class AssessmentResult:
+    """Result from Stage 1: Assessment - analyzing the current situation."""
+    fire_count: int
+    high_intensity_fires: list  # fires > 70%
+    building_threats: list      # fires near buildings
+    uncovered_fires: list       # fires with no unit in range
+    unit_count: int
+    max_units: int
+    effective_units: list       # units in range of fires
+    ineffective_units: list     # units not covering any fire
+    coverage_ratio: float       # ratio of fires covered by units
+    threat_level: str           # CRITICAL / HIGH / MODERATE / LOW
+    summary: str
+    building_integrity: float
+    
+    def to_dict(self) -> dict:
+        return {
+            "fire_count": self.fire_count,
+            "high_intensity_fires": len(self.high_intensity_fires),
+            "building_threats": len(self.building_threats),
+            "uncovered_fires": len(self.uncovered_fires),
+            "unit_count": self.unit_count,
+            "max_units": self.max_units,
+            "effective_units": len(self.effective_units),
+            "ineffective_units": len(self.ineffective_units),
+            "coverage_ratio": round(self.coverage_ratio, 2),
+            "threat_level": self.threat_level,
+            "summary": self.summary,
+            "building_integrity": round(self.building_integrity, 2)
+        }
+
+
+@dataclass
+class PlanResult:
+    """Result from Stage 2: Planning - deciding the strategy."""
+    strategy: str               # "deploy_new" / "optimize_existing" / "balanced" / "monitor"
+    reasoning: str
+    deploy_count: int           # how many new units to deploy
+    reposition_units: list      # units to move (list of dicts with source and reason)
+    priority_targets: list      # fires to prioritize (sorted by priority)
+    
+    def to_dict(self) -> dict:
+        return {
+            "strategy": self.strategy,
+            "reasoning": self.reasoning,
+            "deploy_count": self.deploy_count,
+            "reposition_count": len(self.reposition_units),
+            "priority_targets": len(self.priority_targets)
+        }
+
+
+@dataclass
+class AdvisorResponse:
+    """Complete response from the advisor agent."""
+    summary: str
+    recommendations: list[Recommendation]
+    thinking: str = ""  # Chain of thought reasoning
+    analysis: str = ""  # Situation analysis
+    priority: str = ""  # Priority assessment
+    raw_response: Optional[str] = None
+    error: Optional[str] = None
+    # Multi-stage results
+    assessment: Optional[AssessmentResult] = None
+    plan: Optional[PlanResult] = None
+    
+    def to_dict(self) -> dict:
+        result = {
+            "summary": self.summary,
+            "recommendations": [r.to_dict() for r in self.recommendations],
+            "thinking": self.thinking,
+            "analysis": self.analysis,
+            "priority": self.priority
+        }
+        if self.assessment:
+            result["assessment"] = self.assessment.to_dict()
+        if self.plan:
+            result["plan"] = self.plan.to_dict()
+        return result
+
+
+@dataclass
+class CycleSummary:
+    """Stage 4 summary for a single advisor cycle."""
+    headline: str
+    threat_level: str
+    key_highlights: list[str]
+    risks: list[str]
+    next_focus: list[str]
+
+    def to_dict(self) -> dict:
+        return {
+            "headline": self.headline,
+            "threat_level": self.threat_level,
+            "key_highlights": self.key_highlights,
+            "risks": self.risks,
+            "next_focus": self.next_focus,
+        }
+
+
+@dataclass
+class AfterActionReport:
+    """Structured after-action report summarizing mission outcome."""
+    summary: str
+    strengths: list[str]
+    improvements: list[str]
+    next_actions: list[str]
+    outcome: str = ""
+    error: Optional[str] = None
+    charts: dict = field(default_factory=dict)
+    player_actions: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {
+            "summary": self.summary,
+            "strengths": self.strengths,
+            "improvements": self.improvements,
+            "next_actions": self.next_actions,
+            "outcome": self.outcome,
+            "error": self.error,
+            "charts": self.charts,
+            "player_actions": self.player_actions,
+        }
+
+
+# =============================================================================
+# Advisor Agent
+# =============================================================================
+
+class AdvisorAgent:
+    """
+    Multi-stage LLM-based advisor agent that analyzes world state and provides recommendations.
+    
+    Stage 1: ASSESS - Analyze the situation
+    Stage 2: PLAN - Decide strategy  
+    Stage 3: EXECUTE - Generate specific actions
+    
+    All analysis is performed by the AI model - no fallback logic.
+    Uses HuggingFace Inference Provider API.
+    """
+    
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: Optional[str] = None,
+    ):
+        """
+        Initialize the advisor agent.
+        
+        Args:
+            api_key: HuggingFace token (defaults to HF_TOKEN env var)
+            model: Model to use for inference (defaults to openai/gpt-oss-120b)
+        """
+        # Get HuggingFace token
+        self.api_key = api_key or get_hf_token()
+        self.base_url = HF_INFERENCE_BASE_URL
+        
+        # Load model config from prompts.yaml
+        model_config = PROMPTS_CONFIG.get("model", {})
+        
+        # Model priority: explicit param > prompts.yaml > default
+        yaml_model = model_config.get("default")
+        self.model = model or yaml_model or HF_DEFAULT_MODEL
+        
+        self.temperature = model_config.get("temperature")  # None if not set
+        self.max_completion_tokens = model_config.get("max_completion_tokens", 2000)
+        
+        # Initialize client
+        if self.api_key:
+            print(f"🤖 AI Advisor initialized with HuggingFace Inference API, model: {self.model}")
+            self.client = OpenAI(
+                api_key=self.api_key,
+                base_url=self.base_url
+            )
+        else:
+            self.client = None
+            print("⚠️ Warning: No HF_TOKEN found. AI analysis will not work.")
+    
+    # =========================================================================
+    # JSON Repair Helper
+    # =========================================================================
+    
+    def _try_repair_json(self, content: str) -> Optional[dict]:
+        """
+        Attempt to repair truncated JSON by closing open brackets/braces.
+        
+        Returns:
+            Repaired JSON dict, or None if repair failed
+        """
+        # Count open brackets and braces
+        open_braces = content.count('{') - content.count('}')
+        open_brackets = content.count('[') - content.count(']')
+        
+        # Check if we're in the middle of a string (odd number of unescaped quotes)
+        in_string = False
+        i = 0
+        while i < len(content):
+            if content[i] == '"' and (i == 0 or content[i-1] != '\\'):
+                in_string = not in_string
+            i += 1
+        
+        repaired = content
+        
+        # Close any open string
+        if in_string:
+            repaired += '"'
+        
+        # Close brackets and braces in reverse order of opening
+        # This is a simplified repair - close all brackets then all braces
+        repaired += ']' * open_brackets
+        repaired += '}' * open_braces
+        
+        try:
+            return json.loads(repaired)
+        except json.JSONDecodeError:
+            # Try more aggressive repair - find last valid JSON object
+            try:
+                # Try to find a partial valid structure
+                for end_pos in range(len(content), 0, -1):
+                    partial = content[:end_pos]
+                    open_b = partial.count('{') - partial.count('}')
+                    open_br = partial.count('[') - partial.count(']')
+                    attempt = partial + ']' * open_br + '}' * open_b
+                    try:
+                        return json.loads(attempt)
+                    except json.JSONDecodeError:
+                        continue
+            except Exception:
+                pass
+            return None
+    
+    # =========================================================================
+    # LLM Call Helper
+    # =========================================================================
+    
+    def _call_llm(self, system_prompt: str, user_message: str) -> Optional[dict]:
+        """
+        Make an LLM API call to HuggingFace Inference Provider and parse JSON response.
+        
+        Returns:
+            Parsed JSON dict, or None if failed
+        """
+        if not self.client:
+            print("Error: No API client available (HF_TOKEN not set)")
+            return None
+        
+        # Retry logic for rate limiting (429 errors)
+        max_retries = 3
+        retry_delay = 5  # seconds
+        
+        for attempt in range(max_retries):
+            try:
+                # Build API call parameters for HuggingFace Inference Provider
+                api_params = {
+                    "model": self.model,
+                    "messages": [
+                        {"role": "system", "content": system_prompt},
+                        {"role": "user", "content": user_message}
+                    ],
+                    "max_tokens": self.max_completion_tokens,
+                    "response_format": {"type": "json_object"}
+                }
+                
+                # Only add temperature if explicitly set
+                if self.temperature is not None:
+                    api_params["temperature"] = self.temperature
+                
+                response = self.client.chat.completions.create(**api_params)
+                
+                content = response.choices[0].message.content
+                finish_reason = response.choices[0].finish_reason
+                
+                # Check if response was truncated
+                if finish_reason == "length":
+                    print(f"⚠️ Warning: Response was truncated (hit token limit)")
+                
+                if content:
+                    # Try to parse JSON from the response
+                    # Handle potential markdown code blocks in response
+                    content = content.strip()
+                    if content.startswith("```json"):
+                        content = content[7:]
+                    if content.startswith("```"):
+                        content = content[3:]
+                    if content.endswith("```"):
+                        content = content[:-3]
+                    content = content.strip()
+                    
+                    try:
+                        return json.loads(content)
+                    except json.JSONDecodeError as e:
+                        # Try to repair truncated JSON
+                        print(f"⚠️ JSON parse error: {e}")
+                        print(f"   Raw content (first 500 chars): {content[:500]}...")
+                        repaired = self._try_repair_json(content)
+                        if repaired:
+                            print("✅ Successfully repaired truncated JSON")
+                            return repaired
+                        return None
+                return None
+                
+            except Exception as e:
+                error_str = str(e)
+                # Check for rate limiting (429) error
+                if "429" in error_str or "too_many_requests" in error_str.lower():
+                    if attempt < max_retries - 1:
+                        print(f"⚠️ Rate limited (429), retrying in {retry_delay}s... (attempt {attempt + 1}/{max_retries})")
+                        import time
+                        time.sleep(retry_delay)
+                        continue
+                    else:
+                        print(f"❌ Rate limited after {max_retries} attempts")
+                        return None
+                else:
+                    print(f"LLM call error: {e}")
+                    return None
+        
+        return None  # Should not reach here
+    
+    # =========================================================================
+    # Stage 1: Assessment
+    # =========================================================================
+    
+    def assess(self, world_state: dict) -> AssessmentResult:
+        """
+        Stage 1: Assess the current situation using AI.
+        """
+        assess_config = PROMPTS_CONFIG.get("assess", {})
+        system = assess_config.get("system", "")
+        output_format = assess_config.get("output_format", "")
+        
+        fires = world_state.get("fires", [])
+        units = world_state.get("units", [])
+        buildings = world_state.get("buildings", [])
+        building_integrity = world_state.get("building_integrity", 1.0)
+        max_units = world_state.get("max_units", 10)
+        
+        # Prepare detailed user message
+        user_message = f"""Current World State:
+- Grid size: {world_state.get("width", 10)}x{world_state.get("height", 10)}
+- Building Integrity: {building_integrity:.1%}
+- Max Units Allowed: {max_units}
+
+FIRES ({len(fires)} total):
+{json.dumps(fires, indent=2)}
+
+UNITS ({len(units)} deployed):
+{json.dumps(units, indent=2)}
+
+BUILDINGS ({len(buildings)} total):
+{json.dumps(buildings[:20], indent=2)}{"  (showing first 20)" if len(buildings) > 20 else ""}
+
+Remember:
+- Fire Truck effective range: covers 1 tile outward from its center
+- Helicopter effective range: covers 2 tiles outward from its center
+- A fire is UNCOVERED if no unit is within range
+- A unit is INEFFECTIVE if no fire is within its range
+
+Output format:
+{output_format}"""
+        
+        full_prompt = system + "\n\n" + output_format
+        response = self._call_llm(full_prompt, user_message)
+        
+        if not response:
+            # Return minimal assessment if AI fails
+            return AssessmentResult(
+                fire_count=len(fires),
+                high_intensity_fires=[f for f in fires if f.get("intensity", 0) > 0.7],
+                building_threats=[],
+                uncovered_fires=fires[:],  # Assume all uncovered if AI fails
+                unit_count=len(units),
+                max_units=max_units,
+                effective_units=[],
+                ineffective_units=units[:],  # Assume all ineffective if AI fails
+                coverage_ratio=0.0,
+                threat_level="HIGH",
+                summary="AI assessment unavailable - assuming high threat",
+                building_integrity=building_integrity
+            )
+        
+        try:
+            fire_analysis = response.get("fire_analysis", {})
+            unit_analysis = response.get("unit_analysis", {})
+            
+            # Parse uncovered fire positions
+            uncovered_positions = fire_analysis.get("uncovered_fire_positions", [])
+            uncovered_fires = []
+            for pos in uncovered_positions:
+                if isinstance(pos, list) and len(pos) >= 2:
+                    for f in fires:
+                        if f["x"] == pos[0] and f["y"] == pos[1]:
+                            uncovered_fires.append(f)
+                            break
+            
+            # Parse high intensity positions
+            high_positions = fire_analysis.get("high_intensity_positions", [])
+            high_intensity_fires = []
+            for pos in high_positions:
+                if isinstance(pos, list) and len(pos) >= 2:
+                    for f in fires:
+                        if f["x"] == pos[0] and f["y"] == pos[1]:
+                            high_intensity_fires.append(f)
+                            break
+            # Fallback to intensity check
+            if not high_intensity_fires:
+                high_intensity_fires = [f for f in fires if f.get("intensity", 0) > 0.7]
+            
+            # Parse building threat positions
+            building_threat_positions = fire_analysis.get("building_threat_positions", [])
+            building_threats = []
+            for pos in building_threat_positions:
+                if isinstance(pos, list) and len(pos) >= 2:
+                    for f in fires:
+                        if f["x"] == pos[0] and f["y"] == pos[1]:
+                            building_threats.append(f)
+                            break
+            
+            # Parse ineffective units
+            ineffective_positions = unit_analysis.get("ineffective_positions", [])
+            ineffective_units = []
+            for pos in ineffective_positions:
+                if isinstance(pos, list) and len(pos) >= 2:
+                    for u in units:
+                        if u["x"] == pos[0] and u["y"] == pos[1]:
+                            ineffective_units.append(u)
+                            break
+            
+            # Calculate effective units (all units not in ineffective list)
+            ineffective_set = set((u["x"], u["y"]) for u in ineffective_units)
+            effective_units = [u for u in units if (u["x"], u["y"]) not in ineffective_set]
+            
+            return AssessmentResult(
+                fire_count=fire_analysis.get("total_fires", len(fires)),
+                high_intensity_fires=high_intensity_fires,
+                building_threats=building_threats,
+                uncovered_fires=uncovered_fires,
+                unit_count=len(units),
+                max_units=max_units,
+                effective_units=effective_units,
+                ineffective_units=ineffective_units,
+                coverage_ratio=unit_analysis.get("coverage_ratio", 0.0),
+                threat_level=response.get("threat_level", "MODERATE"),
+                summary=response.get("summary", ""),
+                building_integrity=building_integrity
+            )
+        except Exception as e:
+            print(f"Error parsing AI assessment: {e}")
+            return AssessmentResult(
+                fire_count=len(fires),
+                high_intensity_fires=[],
+                building_threats=[],
+                uncovered_fires=fires[:],
+                unit_count=len(units),
+                max_units=max_units,
+                effective_units=[],
+                ineffective_units=units[:],
+                coverage_ratio=0.0,
+                threat_level="HIGH",
+                summary=f"Assessment parse error: {e}",
+                building_integrity=building_integrity
+            )
+    
+    # =========================================================================
+    # Stage 2: Planning
+    # =========================================================================
+    
+    def plan(self, world_state: dict, assessment: AssessmentResult) -> PlanResult:
+        """
+        Stage 2: Decide the strategy based on assessment using AI.
+        """
+        plan_config = PROMPTS_CONFIG.get("plan", {})
+        system = plan_config.get("system", "")
+        output_format = plan_config.get("output_format", "")
+        
+        fires = world_state.get("fires", [])
+        available_slots = assessment.max_units - assessment.unit_count
+        
+        # Sort fires by priority for context
+        buildings = world_state.get("buildings", [])
+        building_positions = set((b["x"], b["y"]) for b in buildings)
+        
+        def fire_priority(f):
+            near_building = any(
+                abs(f["x"] - bx) <= 1 and abs(f["y"] - by) <= 1
+                for bx, by in building_positions
+            )
+            return f.get("intensity", 0) + (1.0 if near_building else 0)
+        
+        priority_targets = sorted(fires, key=fire_priority, reverse=True)
+        
+        user_message = f"""Assessment Result:
+- Threat Level: {assessment.threat_level}
+- Fire Count: {assessment.fire_count}
+- High Intensity Fires: {len(assessment.high_intensity_fires)}
+- Building Threats: {len(assessment.building_threats)}
+- UNCOVERED Fires (no unit in range): {len(assessment.uncovered_fires)}
+- Coverage Ratio: {assessment.coverage_ratio:.1%}
+- Effective Units: {len(assessment.effective_units)}
+- INEFFECTIVE Units (not near any fire): {len(assessment.ineffective_units)}
+- Summary: {assessment.summary}
+
+Current Resources:
+- Units deployed: {assessment.unit_count} / {assessment.max_units}
+- Available slots: {available_slots}
+
+UNCOVERED Fires (PRIORITY - these need coverage!):
+{json.dumps([{"x": f["x"], "y": f["y"], "intensity": f["intensity"]} for f in assessment.uncovered_fires[:5]], indent=2)}
+
+INEFFECTIVE Units (SHOULD BE MOVED to cover fires!):
+{json.dumps([{"x": u["x"], "y": u["y"], "type": u["type"]} for u in assessment.ineffective_units], indent=2)}
+
+Priority Fires (top 5):
+{json.dumps([{"x": f["x"], "y": f["y"], "intensity": f["intensity"]} for f in priority_targets[:5]], indent=2)}
+
+REMEMBER: If there are uncovered fires AND ineffective units, you SHOULD reposition those units!
+
+Output format:
+{output_format}"""
+        
+        response = self._call_llm(system, user_message)
+        
+        if not response:
+            # Smart fallback: calculate deploy count based on situation
+            uncovered_count = len(assessment.uncovered_fires)
+            idle_count = len(assessment.ineffective_units)
+            fires_after_reposition = max(0, uncovered_count - idle_count)
+            building_threats = len(assessment.building_threats)
+            
+            # Smart deploy calculation
+            if building_threats > 0:
+                # Building emergency! Deploy enough to cover all building threats
+                smart_deploy = max(building_threats, fires_after_reposition)
+            elif uncovered_count <= 2:
+                # Few fires - deploy just enough
+                smart_deploy = fires_after_reposition
+            elif uncovered_count <= 5:
+                # Moderate fires - deploy to cover + small buffer
+                smart_deploy = fires_after_reposition + 1
+            else:
+                # Many fires - deploy more aggressively
+                smart_deploy = fires_after_reposition + 2
+            
+            smart_deploy = min(smart_deploy, available_slots)
+            
+            return PlanResult(
+                strategy="balanced" if assessment.ineffective_units else "deploy_new",
+                reasoning=f"AI planning unavailable - smart fallback: {uncovered_count} uncovered fires, repositioning {idle_count} idle units, deploying {smart_deploy} new",
+                deploy_count=smart_deploy,
+                reposition_units=assessment.ineffective_units[:],
+                priority_targets=priority_targets[:5]
+            )
+        
+        try:
+            # Parse units to reposition
+            reposition_data = response.get("units_to_reposition", [])
+            reposition_units = []
+            for item in reposition_data:
+                if isinstance(item, list) and len(item) >= 3:
+                    sx, sy, utype = item[0], item[1], item[2]
+                    for u in assessment.ineffective_units:
+                        if u["x"] == sx and u["y"] == sy:
+                            reposition_units.append(u)
+                            break
+            
+            # If reposition_needed but no specific units, use all ineffective
+            if response.get("reposition_needed", False) and not reposition_units:
+                reposition_units = assessment.ineffective_units[:]
+            
+            # Map priority_fire_indices to actual fires
+            priority_indices = response.get("priority_fire_indices", [0, 1, 2])
+            selected_targets = []
+            for i in priority_indices:
+                if isinstance(i, int) and i < len(priority_targets):
+                    selected_targets.append(priority_targets[i])
+            
+            if not selected_targets:
+                selected_targets = priority_targets[:5]
+            
+            return PlanResult(
+                strategy=response.get("strategy", "balanced"),
+                reasoning=response.get("reasoning", ""),
+                deploy_count=response.get("deploy_count", 0),
+                reposition_units=reposition_units,
+                priority_targets=selected_targets
+            )
+        except Exception as e:
+            print(f"Error parsing AI plan: {e}")
+            # Smart fallback: calculate deploy count based on situation
+            uncovered_count = len(assessment.uncovered_fires)
+            idle_count = len(assessment.ineffective_units)
+            fires_after_reposition = max(0, uncovered_count - idle_count)
+            building_threats = len(assessment.building_threats)
+            
+            # Smart deploy calculation
+            if building_threats > 0:
+                smart_deploy = max(building_threats, fires_after_reposition)
+            elif uncovered_count <= 2:
+                smart_deploy = fires_after_reposition
+            else:
+                smart_deploy = fires_after_reposition + 1
+            
+            smart_deploy = min(smart_deploy, available_slots)
+            
+            return PlanResult(
+                strategy="balanced",
+                reasoning=f"Plan parse error: {e} - using smart fallback",
+                deploy_count=smart_deploy,
+                reposition_units=assessment.ineffective_units[:],
+                priority_targets=priority_targets[:5]
+            )
+    
+    # =========================================================================
+    # Stage 3: Execution
+    # =========================================================================
+    
+    def execute(
+        self, 
+        world_state: dict, 
+        assessment: AssessmentResult, 
+        plan: PlanResult
+    ) -> list[Recommendation]:
+        """
+        Stage 3: Generate specific deployment/move recommendations using AI.
+        """
+        # Skip if strategy is monitor
+        if plan.strategy == "monitor":
+            return []
+        
+        execute_config = PROMPTS_CONFIG.get("execute", {})
+        system = execute_config.get("system", "")
+        output_format = execute_config.get("output_format", "")
+        
+        fires = world_state.get("fires", [])
+        units = world_state.get("units", [])
+        buildings = world_state.get("buildings", [])
+        width = world_state.get("width", 10)
+        height = world_state.get("height", 10)
+        
+        user_message = f"""Assessment:
+- Threat Level: {assessment.threat_level}
+- Summary: {assessment.summary}
+- Uncovered Fires: {len(assessment.uncovered_fires)}
+- Effective Units: {len(assessment.effective_units)}
+- Ineffective Units: {len(assessment.ineffective_units)}
+
+Plan:
+- Strategy: {plan.strategy}
+- Reasoning: {plan.reasoning}
+- Deploy Count: {plan.deploy_count}
+- Reposition Needed: {len(plan.reposition_units) > 0}
+
+World State:
+- Grid: {width}x{height}
+
+UNCOVERED FIRES (PRIORITY TARGETS - these need units!):
+{json.dumps([{"x": f["x"], "y": f["y"], "intensity": f["intensity"]} for f in assessment.uncovered_fires[:5]], indent=2)}
+
+INEFFECTIVE UNITS (MOVE THESE to uncovered fires!):
+{json.dumps([{"x": u["x"], "y": u["y"], "type": u["type"]} for u in plan.reposition_units[:5]], indent=2)}
+
+All Fire positions: {json.dumps([(f["x"], f["y"], round(f["intensity"], 2)) for f in fires[:15]])}
+All Unit positions: {json.dumps([(u["x"], u["y"], u["type"]) for u in units])}
+Building positions: {json.dumps([(b["x"], b["y"]) for b in buildings[:15]])}
+
+INSTRUCTIONS:
+1. FIRST generate MOVE actions for ineffective units → move them to uncovered fires
+2. THEN generate DEPLOY actions if more units needed
+3. Max 4 recommendations total
+4. Remember: deploy ADJACENT to fire (1-2 cells away), not ON the fire
+
+Output format:
+{output_format}"""
+        
+        response = self._call_llm(system, user_message)
+        
+        if not response:
+            # Generate basic recommendations if AI fails
+            return self._generate_fallback_recommendations(world_state, assessment, plan)
+        
+        try:
+            recommendations = []
+            raw_recs = response.get("recommendations", [])
+            
+            # Get blocked positions
+            fire_positions = set((f["x"], f["y"]) for f in fires)
+            unit_positions = set((u["x"], u["y"]) for u in units)
+            building_positions = set((b["x"], b["y"]) for b in buildings)
+            used_positions = set()
+            
+            for rec in raw_recs[:4]:  # Limit to 4
+                action = rec.get("action", "deploy")
+                unit_type = rec.get("unit_type", "fire_truck")
+                target = rec.get("target", {})
+                target_x = target.get("x", 0)
+                target_y = target.get("y", 0)
+                reason = rec.get("reason", "AI recommendation")
+                
+                # Validate target position
+                pos = (target_x, target_y)
+                if pos in fire_positions or pos in building_positions or pos in used_positions:
+                    # Try to find valid nearby position
+                    valid_pos = self._find_deploy_position(
+                        target_x, target_y, world_state,
+                        exclude_positions=used_positions | unit_positions
+                    )
+                    if valid_pos:
+                        target_x, target_y = valid_pos
+                    else:
+                        continue
+                
+                used_positions.add((target_x, target_y))
+                
+                if action == "move":
+                    source = rec.get("source", {})
+                    source_x = source.get("x", -1)
+                    source_y = source.get("y", -1)
+                    
+                    # Validate source position has a unit
+                    if (source_x, source_y) not in unit_positions:
+                        continue
+                    
+                    recommendations.append(Recommendation(
+                        reason=reason,
+                        suggested_unit_type=unit_type,
+                        target_x=target_x,
+                        target_y=target_y,
+                        action="move",
+                        source_x=source_x,
+                        source_y=source_y
+                    ))
+                elif action == "remove":
+                    # Remove action: remove unit at position
+                    position = rec.get("position", {})
+                    pos_x = position.get("x", target_x)
+                    pos_y = position.get("y", target_y)
+                    unit_type = rec.get("unit_type", "fire_truck")
+                    
+                    # Validate position has a unit
+                    if (pos_x, pos_y) not in unit_positions:
+                        continue
+                    
+                    recommendations.append(Recommendation(
+                        reason=reason,
+                        suggested_unit_type=unit_type,
+                        target_x=pos_x,
+                        target_y=pos_y,
+                        action="remove"
+                    ))
+                else:
+                    recommendations.append(Recommendation(
+                        reason=reason,
+                        suggested_unit_type=unit_type,
+                        target_x=target_x,
+                        target_y=target_y,
+                        action="deploy"
+                    ))
+            
+            return recommendations
+        except Exception as e:
+            print(f"Error parsing AI execution: {e}")
+            return self._generate_fallback_recommendations(world_state, assessment, plan)
+
+    def summarize(
+        self,
+        world_state: dict,
+        assessment: AssessmentResult,
+        plan: PlanResult,
+        recommendations: list[Recommendation],
+        advisor_response: AdvisorResponse,
+    ) -> CycleSummary:
+        """Stage 4: Summarize the cycle results using AI."""
+        summary_config = PROMPTS_CONFIG.get("summary", {})
+        system = summary_config.get("system", "")
+        output_format = summary_config.get("output_format", "")
+
+        fires = world_state.get("fires", [])
+        units = world_state.get("units", [])
+        tick = world_state.get("tick", 0)
+        status = world_state.get("status", "running")
+
+        rec_blocks = []
+        for idx, rec in enumerate(recommendations, 1):
+            block = {
+                "index": idx,
+                "action": rec.action,
+                "unit_type": rec.suggested_unit_type,
+                "target": {"x": rec.target_x, "y": rec.target_y},
+                "source": {"x": rec.source_x, "y": rec.source_y} if rec.action == "move" else None,
+                "reason": rec.reason,
+            }
+            rec_blocks.append(block)
+
+        user_message = f"""Tick: {tick} | Status: {status}
+Threat Level: {assessment.threat_level} | Building Integrity: {assessment.building_integrity:.0%}
+Fires: {assessment.fire_count} | Uncovered Fires: {len(assessment.uncovered_fires)}
+Idle Units: {len(assessment.ineffective_units)} | Total Units: {assessment.unit_count}/{assessment.max_units}
+
+Stage 1 Summary:
+{assessment.summary}
+
+Stage 2 Strategy:
+- Strategy: {plan.strategy}
+- Reasoning: {plan.reasoning}
+- Deploy Count: {plan.deploy_count}
+- Reposition Units: {len(plan.reposition_units)}
+
+Stage 3 Recommendations:
+{json.dumps(rec_blocks[:5], indent=2)}
+
+World Snapshot (first 5 fires / units):
+Fires -> {json.dumps(fires[:5], indent=2)}
+Units -> {json.dumps(units[:5], indent=2)}
+
+OUTPUT FORMAT:
+{output_format}
+"""
+
+        response = self._call_llm(system, user_message)
+        if not response:
+            return CycleSummary(
+                headline=advisor_response.summary if advisor_response else "Cycle summary unavailable",
+                threat_level=assessment.threat_level,
+                key_highlights=[advisor_response.analysis or "Analysis unavailable."],
+                risks=["Summary model unavailable."],
+                next_focus=["Review building-adjacent fires manually."],
+            )
+
+        def _coerce_items(value, fallback):
+            if isinstance(value, list):
+                cleaned = [str(item).strip() for item in value if str(item).strip()]
+                return cleaned or fallback
+            if isinstance(value, str) and value.strip():
+                return [value.strip()]
+            return fallback
+
+        headline = str(response.get("headline", advisor_response.summary if advisor_response else "Cycle summary")).strip()
+        threat_level = str(response.get("threat_level", assessment.threat_level or "MODERATE")).strip()
+        key_highlights = _coerce_items(response.get("key_highlights"), [advisor_response.analysis or "Highlights unavailable."])
+        risks = _coerce_items(response.get("risks"), ["No risks provided."])
+        next_focus = _coerce_items(response.get("next_focus"), ["Maintain coverage on building threats."])
+
+        return CycleSummary(
+            headline=headline or "Cycle summary",
+            threat_level=threat_level or (assessment.threat_level or "MODERATE"),
+            key_highlights=key_highlights,
+            risks=risks,
+            next_focus=next_focus,
+        )
+    
+    def _generate_fallback_recommendations(
+        self,
+        world_state: dict,
+        assessment: AssessmentResult,
+        plan: PlanResult
+    ) -> list[Recommendation]:
+        """Generate SMART recommendations when AI fails - prioritize buildings, deploy efficiently!"""
+        recommendations = []
+        units = world_state.get("units", [])
+        buildings = world_state.get("buildings", [])
+        unit_positions = set((u["x"], u["y"]) for u in units)
+        building_positions = set((b["x"], b["y"]) for b in buildings)
+        used_positions = set()
+        
+        # Helper: check if fire threatens building
+        def threatens_building(fire):
+            for bx, by in building_positions:
+                if abs(fire["x"] - bx) + abs(fire["y"] - by) <= 2:
+                    return True
+            return False
+        
+        # Sort uncovered fires: building threats FIRST, then by intensity
+        priority_fires = sorted(
+            assessment.uncovered_fires,
+            key=lambda f: (-int(threatens_building(f)), -f.get("intensity", 0))
+        )
+        
+        # Count building threats
+        building_threat_count = sum(1 for f in priority_fires if threatens_building(f))
+        
+        # Move ALL ineffective units to priority fires (this is free optimization!)
+        for i, unit in enumerate(plan.reposition_units):
+            if i >= len(priority_fires):
+                break
+            
+            target_fire = priority_fires[i]
+            deploy_pos = self._find_deploy_position(
+                target_fire["x"], target_fire["y"], world_state,
+                exclude_positions=used_positions | unit_positions - {(unit["x"], unit["y"])}
+            )
+            
+            if deploy_pos:
+                used_positions.add(deploy_pos)
+                is_building_threat = threatens_building(target_fire)
+                recommendations.append(Recommendation(
+                    reason=f"{'🏢 BUILDING THREAT! ' if is_building_threat else ''}Move to cover fire at ({target_fire['x']}, {target_fire['y']})",
+                    suggested_unit_type=unit["type"],
+                    target_x=deploy_pos[0],
+                    target_y=deploy_pos[1],
+                    action="move",
+                    source_x=unit["x"],
+                    source_y=unit["y"]
+                ))
+        
+        # SMART deploy calculation: only deploy what we actually need
+        available_slots = assessment.max_units - assessment.unit_count
+        remaining_fires = priority_fires[len(recommendations):]
+        remaining_building_threats = sum(1 for f in remaining_fires if threatens_building(f))
+        
+        # Calculate smart deploy count
+        if remaining_building_threats > 0:
+            # Building emergency! Deploy enough to cover ALL building threats
+            smart_deploy_count = max(remaining_building_threats, min(len(remaining_fires), available_slots))
+        elif len(remaining_fires) <= 2:
+            # Few fires - deploy just enough
+            smart_deploy_count = len(remaining_fires)
+        elif len(remaining_fires) <= 5:
+            # Moderate fires - deploy to cover + small buffer
+            smart_deploy_count = min(len(remaining_fires) + 1, available_slots)
+        else:
+            # Many fires - deploy more but not all
+            smart_deploy_count = min(len(remaining_fires), available_slots)
+        
+        # Deploy to remaining uncovered fires (up to smart_deploy_count)
+        for i, fire in enumerate(remaining_fires[:smart_deploy_count]):
+            deploy_pos = self._find_deploy_position(
+                fire["x"], fire["y"], world_state,
+                exclude_positions=used_positions | unit_positions
+            )
+            
+            if deploy_pos:
+                used_positions.add(deploy_pos)
+                is_building_threat = threatens_building(fire)
+                # Use fire_truck for building threats and high intensity (40% power)
+                unit_type = "fire_truck" if is_building_threat or fire.get("intensity", 0) > 0.5 else "helicopter"
+                recommendations.append(Recommendation(
+                    reason=f"{'🏢 BUILDING THREAT! ' if is_building_threat else ''}Deploy to cover fire at ({fire['x']}, {fire['y']})",
+                    suggested_unit_type=unit_type,
+                    target_x=deploy_pos[0],
+                    target_y=deploy_pos[1],
+                    action="deploy"
+                ))
+        
+        return recommendations[:4]  # Cap at 4 for UI display
+
+    # =========================================================================
+    # After-Action Report
+    # =========================================================================
+
+    def generate_after_action_report(self, context: dict) -> AfterActionReport:
+        """
+        Build an after-action report using Assessment / Planning / Execution transcripts.
+        """
+        after_action_config = PROMPTS_CONFIG.get("after_action", {})
+        system = after_action_config.get("system", "")
+        output_format = after_action_config.get("output_format", "")
+
+        outcome = context.get("outcome", "unknown")
+        default_summary = context.get("summary_text") or f"Mission outcome: {outcome}"
+        report = AfterActionReport(
+            summary=default_summary,
+            strengths=[],
+            improvements=[],
+            next_actions=[],
+            outcome=outcome,
+        )
+        report.charts = {
+            "metrics": context.get("chart_points") or [],
+            "threat_levels": context.get("threat_history") or [],
+            "action_density": context.get("action_history") or [],
+        }
+        report.player_actions = context.get("player_actions_context") or {}
+
+        if not self.client:
+            report.error = "Missing HF_TOKEN – unable to generate AI after-action report."
+            return report
+
+        def _section(title: str, body: str) -> str:
+            if not body:
+                return f"{title}\n(no data available)\n"
+            return f"{title}\n{body}\n"
+
+        header_lines = [
+            f"Mission Outcome: {context.get('outcome_label', outcome)}",
+            f"Tick: {context.get('tick', 0)}",
+            f"Fires Remaining: {context.get('fires_remaining', 0)}",
+            f"Units Active: {context.get('units_active', 0)}",
+            f"Building Integrity: {context.get('building_integrity_percent', 'N/A')}",
+        ]
+
+        mission_summary = context.get("summary_text", "")
+        if mission_summary:
+            header_lines.append(f"Mission Summary: {mission_summary}")
+
+        cycle_summaries = context.get("cycle_summaries") or []
+        if cycle_summaries:
+            summary_lines = []
+            for entry in cycle_summaries:
+                tick = entry.get("tick", "?")
+                headline = entry.get("headline", "No headline")
+                threat = entry.get("threat_level", "N/A")
+                highlights = entry.get("key_highlights") or []
+                risks = entry.get("risks") or []
+                next_focus = entry.get("next_focus") or []
+                block = [
+                    f"- [Tick {tick}] {headline} (Threat: {threat})",
+                ]
+                if highlights:
+                    block.append("  • Highlights: " + "; ".join(highlights))
+                if risks:
+                    block.append("  • Risks: " + "; ".join(risks))
+                if next_focus:
+                    block.append("  • Next Focus: " + "; ".join(next_focus))
+                summary_lines.append("\n".join(block))
+            history_block = "\n".join(summary_lines)
+        else:
+            history_block = "- No prior cycles captured."
+
+        user_sections = [
+            "Mission Status Summary:",
+            "\n".join(header_lines),
+            "",
+            _section("Stage 1 · Assessment", context.get("assessment_md", "")),
+            _section("Stage 2 · Planning", context.get("planning_md", "")),
+            _section("Stage 3 · Execution", context.get("execution_md", "")),
+            _section("Player Manual Actions", context.get("player_actions_md", "")),
+            "Historical Cycle Summaries:",
+            history_block,
+        ]
+
+        if output_format:
+            user_sections.append("Please reply strictly using the JSON schema below:")
+            user_sections.append(output_format)
+
+        user_message = "\n\n".join(user_sections)
+
+        response = self._call_llm(system or "You are a mission debrief analyst.", user_message)
+        if not response:
+            report.error = "Failed to retrieve AI response."
+            return report
+
+        def _coerce_list(value) -> list[str]:
+            if isinstance(value, list):
+                return [str(item).strip() for item in value if str(item).strip()]
+            if isinstance(value, str) and value.strip():
+                return [value.strip()]
+            return []
+
+        report.summary = str(response.get("summary", report.summary)).strip() or report.summary
+        report.strengths = _coerce_list(response.get("strengths"))
+        report.improvements = _coerce_list(response.get("improvements"))
+        report.next_actions = _coerce_list(response.get("next_actions"))
+
+        if not (report.strengths or report.improvements or report.next_actions):
+            report.error = "AI response did not contain any usable sections."
+
+        return report
+    
+    # =========================================================================
+    # Main Entry Point
+    # =========================================================================
+    
+    def analyze(self, world_state: dict) -> AdvisorResponse:
+        """
+        Main entry point: Run multi-stage analysis pipeline.
+        
+        Stage 1: Assessment - Analyze the situation
+        Stage 2: Planning - Decide strategy
+        Stage 3: Execution - Generate specific actions
+        """
+        # Stage 1: Assessment
+        assessment = self.assess(world_state)
+        
+        # Stage 2: Planning
+        plan = self.plan(world_state, assessment)
+        
+        # Stage 3: Execution
+        recommendations = self.execute(world_state, assessment, plan)
+        
+        # Build thinking summary
+        thinking_parts = [
+            f"📊 Scanning {assessment.fire_count} active fires...",
+        ]
+        if assessment.uncovered_fires:
+            thinking_parts.append(f"🚨 ALERT: {len(assessment.uncovered_fires)} fire(s) with NO coverage!")
+        if assessment.building_threats:
+            thinking_parts.append(f"🏢 {len(assessment.building_threats)} fire(s) threatening buildings!")
+        if assessment.ineffective_units:
+            thinking_parts.append(f"🔄 {len(assessment.ineffective_units)} idle unit(s) should be repositioned")
+        thinking_parts.append(f"🎯 Strategy: {plan.strategy.upper()} - {plan.reasoning}")
+        
+        # Generate summary based on threat level
+        priority_emoji = {
+            "CRITICAL": "🔴",
+            "HIGH": "🟠",
+            "MODERATE": "🟡",
+            "LOW": "🟢"
+        }
+        emoji = priority_emoji.get(assessment.threat_level, "⚪")
+        
+        if assessment.threat_level == "CRITICAL":
+            summary = f"{emoji} CRITICAL: {assessment.summary}. Immediate action required!"
+        elif assessment.threat_level == "HIGH":
+            summary = f"{emoji} HIGH: {assessment.summary}. Rapid response needed."
+        elif assessment.threat_level == "MODERATE":
+            summary = f"{emoji} MODERATE: {assessment.summary}. Tactical deployment advised."
+        else:
+            summary = f"{emoji} LOW: {assessment.summary}. Monitoring situation."
+        
+        return AdvisorResponse(
+            summary=summary,
+            recommendations=recommendations,
+            thinking="\n".join(thinking_parts),
+            analysis=f"{assessment.fire_count} fires | {assessment.unit_count}/{assessment.max_units} units | {assessment.building_integrity:.0%} building integrity",
+            priority=assessment.threat_level,
+            assessment=assessment,
+            plan=plan
+        )
+    
+    # =========================================================================
+    # Helper Methods
+    # =========================================================================
+    
+    def _find_deploy_position(
+        self, 
+        fire_x: int, 
+        fire_y: int, 
+        world_state: dict,
+        exclude_positions: set = None
+    ) -> tuple[int, int] | None:
+        """
+        Find a valid deployment position adjacent to a fire.
+        Units cannot deploy on burning cells, so we find the nearest empty cell.
+        """
+        if exclude_positions is None:
+            exclude_positions = set()
+            
+        fires = world_state.get("fires", [])
+        units = world_state.get("units", [])
+        buildings = world_state.get("buildings", [])
+        width = world_state.get("width", 10)
+        height = world_state.get("height", 10)
+        
+        fire_positions = set((f["x"], f["y"]) for f in fires)
+        unit_positions = set((u["x"], u["y"]) for u in units)
+        building_positions = set((b["x"], b["y"]) for b in buildings)
+        
+        # Check positions at increasing distances
+        for distance in [1, 2, 3]:
+            candidates = []
+            for dx in range(-distance, distance + 1):
+                for dy in range(-distance, distance + 1):
+                    if abs(dx) != distance and abs(dy) != distance:
+                        continue
+                    
+                    nx, ny = fire_x + dx, fire_y + dy
+                    
+                    # Check bounds
+                    if not (0 <= nx < width and 0 <= ny < height):
+                        continue
+                    
+                    # Skip invalid positions
+                    if (nx, ny) in fire_positions:
+                        continue
+                    if (nx, ny) in unit_positions:
+                        continue
+                    if (nx, ny) in building_positions:
+                        continue
+                    if (nx, ny) in exclude_positions:
+                        continue
+                    
+                    # Valid candidate
+                    dist_to_fire = abs(nx - fire_x) + abs(ny - fire_y)
+                    candidates.append((nx, ny, dist_to_fire))
+            
+            if candidates:
+                candidates.sort(key=lambda c: c[2])
+                return (candidates[0][0], candidates[0][1])
+        
+        return None
+
+
+# Backward compatibility
+def _fallback_analyze(self, world_state: dict) -> AdvisorResponse:
+    """Fallback method for service.py compatibility."""
+    return self.analyze(world_state)
+
+# Add method to class
+AdvisorAgent._fallback_analyze = _fallback_analyze

app.py

@@ -0,0 +1,1865 @@
+"""
+Fire-Rescue MCP - Gradio Application
+
+Main entry point for the Hugging Face Space deployment.
+Provides Gradio UI for simulation control and visualization.
+"""
+
+import html
+import gradio as gr
+from typing import Optional
+
+from service import get_service, SimulationService
+
+
+# =============================================================================
+# Grid Visualization (Clickable)
+# =============================================================================
+
+def get_cell_info(state: dict, x: int, y: int) -> tuple[str, str]:
+    """Get cell display info (emoji, css class)."""
+    fires = {(f["x"], f["y"]): f["intensity"] for f in state.get("fires", [])}
+    units = {(u["x"], u["y"]): u["type"] for u in state.get("units", [])}
+    buildings = {(b["x"], b["y"]) for b in state.get("buildings", [])}
+    
+    # Default: forest
+    content = "🌲"
+    bg_color = "#1b4332"
+    
+    # Building (from dynamic positions)
+    if (x, y) in buildings:
+        content = "🏢"
+        bg_color = "#495057"
+    
+    # Fire - show intensity level with different visuals
+    if (x, y) in fires:
+        intensity = fires[(x, y)]
+        # Display fire intensity as percentage
+        pct = int(intensity * 100)
+        
+        if intensity >= 0.9:
+            # Extreme fire - inferno
+            content = f"🔥{pct}"
+            bg_color = "#7f1d1d"  # Very dark red
+        elif intensity >= 0.7:
+            # High fire
+            content = f"🔥{pct}"
+            bg_color = "#b91c1c"  # Dark red
+        elif intensity >= 0.5:
+            # Medium-high fire
+            content = f"🔥{pct}"
+            bg_color = "#dc2626"  # Red
+        elif intensity >= 0.3:
+            # Medium fire
+            content = f"🔥{pct}"
+            bg_color = "#ea580c"  # Orange-red
+        elif intensity >= 0.1:
+            # Low fire
+            content = f"🔥{pct}"
+            bg_color = "#f97316"  # Orange
+        else:
+            # Smoldering / almost out
+            content = f"💨{pct}"
+            bg_color = "#fbbf24"  # Yellow-orange
+    
+    # Unit (overwrites fire display)
+    if (x, y) in units:
+        unit_type = units[(x, y)]
+        content = "🚒" if unit_type == "fire_truck" else "🚁"
+        bg_color = "#0077b6"
+    
+    return content, bg_color
+
+
+def render_status_html(state: dict, is_thinking: bool = False, thinking_stage: int = 0) -> str:
+    """Render simulation status as compact HTML bar."""
+    if state.get("status") == "idle":
+        return "<div class='status-compact'>🎮 Click Start to begin</div>"
+    
+    tick = state.get("tick", 0)
+    status = state.get("status", "unknown")
+    building = state.get("building_integrity", 1.0)
+    fires = len(state.get("fires", []))
+    units = len(state.get("units", []))
+    
+    status_colors = {
+        "running": "#4ade80",
+        "success": "#22d3ee", 
+        "fail": "#f87171"
+    }
+    status_color = status_colors.get(status, "#888")
+    health_color = "#4ade80" if building > 0.6 else "#fbbf24" if building > 0.5 else "#f87171"
+    fire_color = "#22d3ee" if fires == 0 else "#f87171"
+    
+    thinking_html = ""
+    if is_thinking:
+        stage_info = {
+            1: ("📊", "Assessing"),
+            2: ("🎯", "Planning"),
+            3: ("⚡", "Executing"),
+            4: ("🧭", "Summarizing"),
+        }
+        icon, label = stage_info.get(thinking_stage, ("🤔", "Thinking"))
+        thinking_html = f"""
+        <div class="status-item ai-thinking-inline">
+            <span class="ai-pulse">{icon}</span>
+            <span class="ai-label">AI</span>
+            <strong>{label}...</strong>
+        </div>
+        """
+    
+    html = f"""
+    <div class="status-compact">
+        <div class="status-item">
+            <span>⏱️</span>
+            <strong>{tick}</strong>
+        </div>
+        <div class="status-item">
+            <span class="status-badge" style="background: {status_color};">{status.upper()}</span>
+        </div>
+        <div class="status-item status-health">
+            <span>🏢</span>
+            <div class="progress-mini">
+                <div style="background: {health_color}; width: {building*100}%; height: 100%;"></div>
+            </div>
+            <span style="color: {health_color}; font-weight: bold;">{building:.0%}</span>
+        </div>
+        <div class="status-item">
+            <span>🔥</span>
+            <strong style="color: {fire_color};">{fires}</strong>
+        </div>
+        <div class="status-item">
+            <span>🚒</span>
+            <strong>{units}</strong>
+        </div>
+        {thinking_html}
+    </div>
+    """
+    return html
+
+
+def _chat_signature(messages: list[dict]) -> tuple:
+    """Create a hashable signature for chatbot messages (role, content, metadata)."""
+    signature = []
+    for msg in messages or []:
+        metadata = msg.get("metadata") or {}
+        metadata_tuple = tuple(sorted(metadata.items()))
+        signature.append(
+            (
+                msg.get("role", "assistant"),
+                msg.get("content", ""),
+                metadata_tuple,
+            )
+        )
+    return tuple(signature)
+
+
+def render_compact_status(state: dict) -> str:
+    """Render a compact horizontal status bar."""
+    if state.get("status") == "idle":
+        return """
+        <div class="status-bar">
+            <div class="status-item">
+                <span style="color: #888;">🎮 Click Start to begin simulation</span>
+            </div>
+        </div>
+        """
+    
+    tick = state.get("tick", 0)
+    status = state.get("status", "unknown")
+    building = state.get("building_integrity", 1.0)
+    fires = len(state.get("fires", []))
+    units = len(state.get("units", []))
+    
+    # Status colors
+    status_colors = {
+        "running": "#4ade80",
+        "success": "#22d3ee", 
+        "fail": "#f87171"
+    }
+    status_color = status_colors.get(status, "#888")
+    health_color = "#4ade80" if building > 0.6 else "#fbbf24" if building > 0.5 else "#f87171"
+    fire_color = "#22d3ee" if fires == 0 else "#f87171"
+    
+    html = f"""
+    <div class="status-bar">
+        <div class="status-item">
+            <span>⏱️ Tick:</span>
+            <strong>{tick}</strong>
+        </div>
+        <div class="status-item">
+            <span class="status-badge" style="background: {status_color}; color: #000;">{status.upper()}</span>
+        </div>
+        <div class="status-item">
+            <span>🏢</span>
+            <div class="progress-mini">
+                <div style="background: {health_color}; width: {building*100}%; height: 100%;"></div>
+            </div>
+            <span style="color: {health_color}; font-weight: bold;">{building:.0%}</span>
+        </div>
+        <div class="status-item">
+            <span>🔥</span>
+            <span style="color: {fire_color}; font-weight: bold;">{fires}</span>
+        </div>
+        <div class="status-item">
+            <span>🚒 {units}</span>
+        </div>
+    </div>
+    """
+    return html
+
+
+def render_ai_thinking_toast(is_thinking: bool, thinking_stage: int) -> str:
+    """Render AI thinking toast notification (iOS-style)."""
+    if not is_thinking:
+        return ""
+    
+    stage_info = {
+        1: ("📊", "Stage 1: Assessment", "Querying MCP tools & analyzing situation..."),
+        2: ("🎯", "Stage 2: Planning", "Formulating tactical strategy..."),
+        3: ("⚡", "Stage 3: Execution", "Generating MCP deployment commands..."),
+        4: ("🧭", "Stage 4: Summary", "Consolidating per-cycle findings..."),
+    }
+    
+    icon, title, subtitle = stage_info.get(thinking_stage, ("🤔", "AI Thinking", "Processing..."))
+    
+    return f"""
+    <div class="ai-toast-container">
+        <div class="ai-toast">
+            <div class="ai-toast-icon">{icon}</div>
+            <div class="ai-toast-content">
+                <div class="ai-toast-title">{title}</div>
+                <div class="ai-toast-subtitle">{subtitle}</div>
+            </div>
+            <div class="ai-toast-spinner"></div>
+        </div>
+    </div>
+    """
+
+
+def render_game_result(status: str, report_payload: Optional[dict] = None) -> str:
+    """Render game result popup with after-action report."""
+    if status not in {"success", "fail"}:
+        return ""
+    
+    report_payload = report_payload or {}
+    outcome_config = {
+        "success": {
+            "icon": "🎉",
+            "title": "VICTORY!",
+            "color": "#22d3ee",
+            "subtitle": "All fires extinguished!",
+        },
+        "fail": {
+            "icon": "💀",
+            "title": "GAME OVER",
+            "color": "#f87171",
+            "subtitle": "Building integrity dropped below 50%.",
+        },
+    }[status]
+    
+    def _render_report_cards(title: str, items, css_class: str) -> str:
+        normalized = []
+        for item in items or []:
+            text = str(item).strip()
+            if text:
+                normalized.append(html.escape(text))
+        if not normalized:
+            return ""
+        bullets = "".join(f"<li>{value}</li>" for value in normalized)
+        icon = ""
+        label = html.escape(title)
+        parts = title.split(" ", 1)
+        if len(parts) == 2 and not parts[0].isalnum():
+            icon = html.escape(parts[0])
+            label = html.escape(parts[1])
+        icon_html = f"<span class='report-card-icon'>{icon}</span>" if icon else ""
+        return f"""
+        <div class="report-card {css_class}">
+            <div class="report-card-header">
+                {icon_html}
+                <div class="report-card-title">{label}</div>
+            </div>
+            <div class="report-card-body">
+                <ul>{bullets}</ul>
+            </div>
+        </div>
+        """
+
+    def _render_chart_card(
+        points: list[dict],
+        value_key: str,
+        title: str,
+        color: str,
+        value_formatter=None,
+        axis_formatter=None,
+    ) -> str:
+        if not points:
+            return ""
+        series = []
+        for pt in points:
+            tick = pt.get("tick")
+            value = pt.get(value_key)
+            if value is None or tick is None:
+                continue
+            try:
+                value = float(value)
+            except (TypeError, ValueError):
+                continue
+            series.append((tick, value, pt))
+        if not series:
+            return ""
+        values = [item[1] for item in series]
+        min_v = min(values)
+        max_v = max(values)
+        span = max(max_v - min_v, 1e-6)
+        coords = []
+        for idx, (_, value, _) in enumerate(series):
+            x = 0 if len(series) == 1 else (idx / (len(series) - 1)) * 100
+            if max_v == min_v:
+                y = 30
+            else:
+                y = 60 - ((value - min_v) / span) * 60
+            coords.append(f"{x:.2f},{y:.2f}")
+        last_tick, last_value, last_point = series[-1]
+        display_value = (
+            value_formatter(last_value, last_point)
+            if value_formatter
+            else f"{last_value:.0f}"
+        )
+        axis_format = axis_formatter or (lambda v: f"{v:.0f}")
+        axis_top_label = axis_format(max_v)
+        axis_bottom_label = axis_format(min_v)
+        first_tick = series[0][0]
+        last_coord = coords[-1].split(",")
+        return f"""
+        <div class="report-chart-card">
+            <div class="chart-title">{title}</div>
+            <div class="mini-chart">
+                <svg viewBox="0 0 100 60" preserveAspectRatio="none">
+                    <polyline points="{' '.join(coords)}" fill="none" stroke="{color}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+                    <circle cx="{last_coord[0]}" cy="{last_coord[1]}" r="2.5" fill="{color}" />
+                </svg>
+            </div>
+            <div class="chart-axis-values">
+                <span>{axis_top_label}</span>
+                <span>{axis_bottom_label}</span>
+            </div>
+            <div class="chart-x-axis">
+                <span>Tick {int(first_tick)}</span>
+                <span>Tick {int(last_tick)}</span>
+            </div>
+            <div class="chart-meta">
+                <span>Tick {int(last_tick)}</span>
+                <span class="chart-value" style="color: {color};">{display_value}</span>
+            </div>
+        </div>
+        """
+
+    def _render_chart_section(charts_payload) -> str:
+        if not charts_payload:
+            return ""
+        if isinstance(charts_payload, list):
+            metric_points = charts_payload
+            threat_points = []
+        else:
+            metric_points = charts_payload.get("metrics") or []
+            threat_points = charts_payload.get("threat_levels") or []
+        fire_chart = _render_chart_card(
+            metric_points,
+            "fires",
+            "🔥 Fire Load",
+            "#f97316",
+            lambda v, _: f"{int(round(v))} fires",
+            lambda v: f"{int(round(v))} fires",
+        )
+        unit_chart = _render_chart_card(
+            metric_points,
+            "units",
+            "🚒 Units Deployed",
+            "#38bdf8",
+            lambda v, pt: f"{int(round(v))}/{int(pt.get('max_units', 0) or 0)} units",
+            lambda v: f"{int(round(v))} units",
+        )
+        integrity_chart = _render_chart_card(
+            metric_points,
+            "building_integrity",
+            "🏢 Building Integrity",
+            "#4ade80",
+            lambda v, _: f"{max(0, min(1, v)) * 100:.0f}%",
+            lambda v: f"{max(0, min(1, v)) * 100:.0f}%",
+        )
+        threat_chart = _render_threat_chart(threat_points)
+        charts = "".join(filter(None, [fire_chart, unit_chart, integrity_chart, threat_chart]))
+        if not charts:
+            return ""
+        return f"""
+        <div class="report-chart-grid">
+            {charts}
+        </div>
+        """
+
+    def _render_player_actions_block(payload: Optional[dict]) -> str:
+        if not payload:
+            return ""
+        summary = html.escape(payload.get("summary", "") or "Player has not performed any manual actions this run.")
+        counts = payload.get("counts") or {}
+        chips = []
+        chip_meta = [
+            ("deploy_unit", "🚒 Deploy Units"),
+            ("remove_unit", "♻️ Remove Units"),
+            ("add_fire", "🔥 Ignite Fires"),
+        ]
+        for key, label in chip_meta:
+            value = counts.get(key, 0) or 0
+            try:
+                value = int(value)
+            except (TypeError, ValueError):
+                value = 0
+            chip_class = "" if value > 0 else "muted"
+            chips.append(f"<span class='player-action-chip {chip_class}'>{label}: {value}</span>")
+        chips_html = "".join(chips)
+        return f"""
+        <div class="player-actions-block">
+            <div class="player-actions-header">🙋 Player Manual Actions</div>
+            <p class="player-actions-summary">{summary}</p>
+            <div class="player-actions-chips">{chips_html}</div>
+        </div>
+        """
+
+    def _render_threat_chart(points: list[dict]) -> str:
+        if not points:
+            return ""
+        threat_map = {"CRITICAL": 4, "HIGH": 3, "MODERATE": 2, "LOW": 1}
+        normalized = []
+        for entry in points:
+            tick = entry.get("tick")
+            if tick is None:
+                continue
+            level = (entry.get("threat_level") or "").upper()
+            value = entry.get("value")
+            if value is None:
+                value = threat_map.get(level, 0)
+            normalized.append({
+                "tick": tick,
+                "threat_value": value,
+                "threat_label": entry.get("threat_level", level.title()),
+            })
+        if not normalized:
+            return ""
+        reverse_map = {v: k.title() for k, v in threat_map.items()}
+        def format_label(val):
+            return reverse_map.get(int(round(val)), f"{val:.0f}")
+        return _render_chart_card(
+            normalized,
+            "threat_value",
+            "🧭 Threat Level",
+            "#c084fc",
+            lambda v, pt: pt.get("threat_label", format_label(v)),
+            format_label,
+        )
+
+    
+    after_action_status = report_payload.get("status", "idle")
+    report = report_payload.get("report", {}) or {}
+    
+    if after_action_status == "pending":
+        report_section = """
+        <div class="result-report pending">
+            <div class="report-spinner"></div>
+            <div class="report-text">
+                <strong>AI battle report is being generated...</strong>
+                <p>The AI is consolidating Stage 4 cycle summaries and mission metrics into the final report.</p>
+            </div>
+        </div>
+        """
+    elif after_action_status == "ready" and report:
+        summary = html.escape(report.get("summary", ""))
+        charts_html = _render_chart_section(report.get("charts") or [])
+        player_actions_html = _render_player_actions_block(report.get("player_actions"))
+        strengths = _render_report_cards("✅ What Went Well", report.get("strengths", []), "positive")
+        improvements = _render_report_cards("⚠️ Needs Improvement", report.get("improvements", []), "risk")
+        actions = _render_report_cards("🛠 Actionable Suggestions", report.get("next_actions", []), "action")
+        cards = strengths + improvements + actions
+        if not cards:
+            cards = "<p class='report-empty'>AI has not provided any concrete items yet.</p>"
+        report_section = f"""
+        <div class="result-report ready">
+            <div class="result-report-header">
+                <span>AI Battle Report</span>
+                <span class="report-badge">Complete</span>
+            </div>
+            <p class="report-summary">{summary}</p>
+            {charts_html}
+            {player_actions_html}
+            <div class="report-card-grid">{cards}</div>
+        </div>
+        """
+    elif after_action_status == "error":
+        error_msg = html.escape(report_payload.get("error") or "AI report generation failed.")
+        report_section = f"""
+        <div class="result-report error">
+            <div class="result-report-header">
+                <span>AI Battle Report</span>
+                <span class="report-badge danger">Error</span>
+            </div>
+            <p class="report-error">⚠️ {error_msg}</p>
+        </div>
+        """
+    else:
+        report_section = """
+        <div class="result-report idle">
+            <p>Waiting for the AI to finish the battle analysis...</p>
+        </div>
+        """
+    
+    return f"""
+    <div class="game-result-overlay" id="result-overlay">
+        <div class="game-result-box">
+            <div class="result-icon" style="color: {outcome_config['color']};">{outcome_config['icon']}</div>
+            <div class="result-title" style="color: {outcome_config['color']};">{outcome_config['title']}</div>
+            <div class="result-subtitle">{outcome_config['subtitle']}</div>
+            {report_section}
+            <button class="result-ok-btn" onclick="document.getElementById('result-overlay').style.display='none'">OK</button>
+        </div>
+    </div>
+    """
+
+
+# =============================================================================
+# Gradio Event Handlers
+# =============================================================================
+
+def _get_combined_advisor_messages(service) -> list[dict]:
+    """Return history + current advisor messages as one list."""
+    history = service.get_advisor_history_chat_messages() or []
+    current = service.get_advisor_chat_messages() or []
+    combined = history + current
+    if not combined:
+        return [{
+            "role": "assistant",
+            "content": "No AI analysis yet. Press **Start** to begin the advisor cycle."
+        }]
+    return combined
+
+def start_or_resume_simulation(fire_count: int, fire_intensity: float, building_count: int, max_units: int, seed: Optional[int]):
+    """Handle Start/Resume button click."""
+    service = get_service()
+    
+    # Check if there's a paused simulation to resume
+    if service.is_paused():
+        state = service.resume()
+    else:
+        # Start new simulation
+        _reset_advisor_display_cache()
+        actual_seed = int(seed) if seed and seed > 0 else None
+        state = service.start(
+            seed=actual_seed, 
+            fire_count=int(fire_count), 
+            fire_intensity=fire_intensity,
+            building_count=int(building_count),
+            max_units=int(max_units)
+        )
+    
+    # Generate button updates
+    updates = get_all_button_updates(state)
+    
+    # Get thinking state
+    is_thinking = service.is_thinking()
+    thinking_stage = service.get_thinking_stage()
+    
+    return [
+        gr.Timer(active=True),  # Start the timer
+        gr.Timer(active=False),  # Ensure report poller is off initially
+        render_game_result(state.get("status", ""), state.get("after_action_report")),
+        _get_combined_advisor_messages(service),
+        service.get_event_log_text(),
+        gr.update(interactive=False),  # start btn
+        gr.update(interactive=True),   # pause btn
+        render_status_html(state, is_thinking, thinking_stage),
+    ] + updates
+
+
+def pause_simulation():
+    """Handle Pause button click."""
+    service = get_service()
+    state = service.pause()
+    
+    updates = get_all_button_updates(state)
+    
+    return [
+        gr.Timer(active=False),  # Stop the timer
+        gr.Timer(active=False),
+        render_game_result(state.get("status", ""), state.get("after_action_report")),
+        _get_combined_advisor_messages(service),
+        service.get_event_log_text(),
+        gr.update(interactive=True),   # start btn (can resume)
+        gr.update(interactive=False),  # pause btn
+        render_status_html(state),
+    ] + updates
+
+
+def reset_simulation(fire_count: int, fire_intensity: float, building_count: int, max_units: int, seed: Optional[int]):
+    """Handle Reset button click."""
+    service = get_service()
+    _reset_advisor_display_cache()
+    actual_seed = int(seed) if seed and seed > 0 else None
+    state = service.reset(
+        seed=actual_seed, 
+        fire_count=int(fire_count), 
+        fire_intensity=fire_intensity,
+        building_count=int(building_count),
+        max_units=int(max_units)
+    )
+    
+    updates = get_all_button_updates(state)
+    
+    return [
+        gr.Timer(active=False),  # Stop the timer
+        gr.Timer(active=False),
+        "",  # Clear result popup
+        _get_combined_advisor_messages(service),
+        service.get_event_log_text(),
+        gr.update(interactive=True),
+        gr.update(interactive=False),
+        render_status_html(state),
+    ] + updates
+
+
+def deploy_at_cell(x: int, y: int, selection: str):
+    """Deploy unit or fire at specific cell, or remove if unit already exists there."""
+    service = get_service()
+    
+    # Get thinking state
+    is_thinking = service.is_thinking()
+    thinking_stage = service.get_thinking_stage()
+    
+    # Only allow deployment when simulation is actively running (not paused)
+    if not service.is_running():
+        gr.Warning("⚠️ Please start the simulation first!")
+        state = service.get_state()
+        updates = get_all_button_updates(state)
+        return [
+            render_game_result(state.get("status", ""), state.get("after_action_report")),
+            _get_combined_advisor_messages(service),
+            service.get_event_log_text(),
+            render_status_html(state, is_thinking, thinking_stage),
+        ] + updates
+    
+    # Handle fire placement
+    if selection == "🔥 Fire":
+        result = service.add_fire(x, y, intensity=0.5)
+        if result.get("status") != "ok":
+            error_msg = result.get("message", "Unknown error")
+            gr.Warning(f"⚠️ {error_msg}")
+    # Check if there's already a unit at this position
+    elif service.has_unit_at(x, y):
+        # Remove the existing unit
+        result = service.remove_unit(x, y)
+    else:
+        # Deploy new unit
+        unit_type_key = "fire_truck" if selection == "🚒 Truck" else "helicopter"
+        result = service.deploy_unit(unit_type_key, x, y, "player")
+        
+        # Show warning notification only on failure
+        if result.get("status") != "ok":
+            error_msg = result.get("message", "Unknown error")
+            gr.Warning(f"⚠️ {error_msg}")
+    
+    state = service.get_state()
+    updates = get_all_button_updates(state)
+    
+    # Refresh thinking state after action
+    is_thinking = service.is_thinking()
+    thinking_stage = service.get_thinking_stage()
+    
+    return [
+        render_game_result(state.get("status", ""), state.get("after_action_report")),
+        _get_combined_advisor_messages(service),
+        service.get_event_log_text(),
+        render_status_html(state, is_thinking, thinking_stage),
+    ] + updates
+
+
+def poll_after_action_report():
+    """Poll after-action report status independently of the main simulation timer."""
+    service = get_service()
+    state = service.get_state()
+    status = state.get("status", "idle")
+    report_payload = state.get("after_action_report")
+    after_action_status = (report_payload or {}).get("status", "idle")
+    
+    report_timer_update = gr.update()
+    if status not in ["success", "fail"] or after_action_status != "pending":
+        report_timer_update = gr.Timer(active=False)
+    
+    return [
+        report_timer_update,
+        render_game_result(status, report_payload),
+    ]
+
+
+def get_all_button_updates(state: dict) -> list:
+    """Generate updates for all grid buttons."""
+    updates = []
+    for y in range(10):
+        for x in range(10):
+            content, bg_color = get_cell_info(state, x, y)
+            updates.append(gr.update(value=content))
+    return updates
+
+
+# Cache for preventing unnecessary UI updates (flicker prevention)
+_last_status_html = None
+_last_advisor_signature = ()
+_history_messages_cache: list[dict] = []
+_current_cycle_messages_cache: list[dict] = []
+
+
+def _reset_advisor_display_cache():
+    """Clear cached advisor/chatbot renders (prevents stale history after reset)."""
+    global _last_advisor_signature, _history_messages_cache, _current_cycle_messages_cache, _last_status_html
+    _last_advisor_signature = ()
+    _history_messages_cache = []
+    _current_cycle_messages_cache = []
+    _last_status_html = None
+
+
+def refresh_display():
+    """
+    Single timer refresh (every 1 second).
+    Uses unified change tracking to update only changed components.
+    """
+    service = get_service()
+    
+    # Get all changes in one call
+    changes = service.get_changed_components()
+    state = changes["state"]
+    status = state.get("status", "idle")
+    report_payload_state = state.get("after_action_report") or {}
+    after_action_status = report_payload_state.get("status", "idle")
+    
+    # Get AI thinking state
+    is_thinking = service.is_thinking()
+    thinking_stage = service.get_thinking_stage()
+    
+    # Timer control - stop when game ends
+    timer_update = gr.update()
+    if status in ["success", "fail"]:
+        timer_update = gr.Timer(active=False)
+
+    report_timer_update = gr.Timer(active=False)
+    if status in ["success", "fail"] and after_action_status == "pending":
+        report_timer_update = gr.Timer(active=True)
+    
+    # Result popup - only when state changes
+    if changes["result_changed"]:
+        result_state = changes["result_state"]
+        payload = changes.get("result_payload") or {}
+        report_payload = payload.get("after_action")
+        result_popup = render_game_result(result_state, report_payload)
+    else:
+        result_popup = gr.update()
+    
+    # Advisor display (chatbot) showing combined history + current cycle
+    global _last_advisor_signature, _history_messages_cache, _current_cycle_messages_cache
+    if changes["history_changed"]:
+        history_messages = changes.get("advisor_history")
+        if history_messages is not None:
+            _history_messages_cache = history_messages
+    current_cycle_messages = changes.get("advisor_messages")
+    if current_cycle_messages is not None:
+        _current_cycle_messages_cache = current_cycle_messages
+    combined_messages = (_history_messages_cache or []) + (_current_cycle_messages_cache or [])
+    if combined_messages:
+        signature = _chat_signature(combined_messages)
+        if signature != _last_advisor_signature:
+            _last_advisor_signature = signature
+            advisor_display = gr.update(value=combined_messages)
+        else:
+            advisor_display = gr.skip()
+    else:
+        advisor_display = gr.skip()
+    
+    # Event log - only when content changes
+    event_log = changes["event_log"] if changes["event_log_changed"] else gr.update()
+    
+    # Buttons - only when state changes
+    if changes["buttons_changed"]:
+        start_enabled, pause_enabled = changes["button_states"]
+        start_btn_update = gr.update(interactive=start_enabled)
+        pause_btn_update = gr.update(interactive=pause_enabled)
+    else:
+        start_btn_update = gr.update()
+        pause_btn_update = gr.update()
+    
+    # Status bar - use cache to prevent flicker (only update when content changes)
+    global _last_status_html
+    new_status_html = render_status_html(state, is_thinking, thinking_stage)
+    if new_status_html == _last_status_html:
+        status_html_update = gr.skip()
+    else:
+        _last_status_html = new_status_html
+        status_html_update = new_status_html
+    
+    # Grid buttons - only update if changed
+    if changes["grid_changed"]:
+        updates = get_all_button_updates(state)
+    else:
+        updates = [gr.update() for _ in range(100)]
+    
+    return [
+        timer_update,
+        report_timer_update,
+        result_popup,
+        advisor_display,
+        event_log,
+        start_btn_update,
+        pause_btn_update,
+        status_html_update,
+    ] + updates
+
+
+# =============================================================================
+# Gradio UI Definition
+# =============================================================================
+
+CUSTOM_CSS = """
+    .advisor-chatbot {
+        border: 1px solid var(--progress-bg);
+        border-radius: 12px;
+        background: var(--status-bg);
+        padding: 4px;
+    }
+    
+    .advisor-chatbot .wrap {
+        background: transparent !important;
+    }
+    
+    .advisor-chatbot .top-panel,
+    .advisor-chatbot .icon-button-wrapper {
+        display: none !important;
+    }
+    
+    .advisor-chatbot .message {
+        font-family: "JetBrains Mono", "SFMono-Regular", ui-monospace, monospace !important;
+        font-size: 13px !important;
+        line-height: 1.5 !important;
+        color: var(--status-text);
+    }
+    
+    .advisor-chatbot .message .metadata-title {
+        font-weight: 600;
+    }
+    
+    /* Theme-aware CSS variables */
+    :root {
+        --status-bg: #f8fafc;
+        --status-text: #1e293b;
+        --status-muted: #64748b;
+        --progress-bg: #e2e8f0;
+    }
+    
+    /* Dark mode overrides */
+    .dark {
+        --status-bg: #1a1a2e;
+        --status-text: #ffffff;
+        --status-muted: #94a3b8;
+        --progress-bg: #333333;
+    }
+    
+    /* Fixed size grid buttons - force square shape */
+    .grid-btn {
+        width: 52px !important;
+        height: 52px !important;
+        min-width: 52px !important;
+        min-height: 52px !important;
+        max-width: 52px !important;
+        max-height: 52px !important;
+        padding: 0 !important;
+        font-size: 16px !important;
+        border-radius: 5px !important;
+        margin: 1px !important;
+        flex-shrink: 0 !important;
+        flex-grow: 0 !important;
+        line-height: 52px !important;
+        box-sizing: border-box !important;
+        font-weight: bold !important;
+        text-shadow: 1px 1px 2px rgba(0,0,0,0.5) !important;
+    }
+    
+    /* Coordinate label - same size as grid-btn but transparent */
+    .coord-label {
+        width: 52px !important;
+        height: 52px !important;
+        min-width: 52px !important;
+        min-height: 52px !important;
+        max-width: 52px !important;
+        max-height: 52px !important;
+        padding: 0 !important;
+        font-size: 14px !important;
+        font-weight: bold !important;
+        border-radius: 5px !important;
+        margin: 1px !important;
+        flex-shrink: 0 !important;
+        flex-grow: 0 !important;
+        line-height: 52px !important;
+        box-sizing: border-box !important;
+        background: transparent !important;
+        border: none !important;
+        color: #888 !important;
+        cursor: default !important;
+        pointer-events: none !important;
+    }
+    
+    /* Fixed row layout - prevent wrapping, tight spacing */
+    .grid-row {
+        display: flex !important;
+        flex-wrap: nowrap !important;
+        gap: 0 !important;
+        align-items: center !important;
+        margin: 0 !important;
+        padding: 0 !important;
+        min-height: 0 !important;
+        line-height: 1 !important;
+    }
+    
+    /* Override Gradio's default row gap */
+    .grid-row.row {
+        gap: 0 !important;
+    }
+    
+    .grid-row > div {
+        flex-shrink: 0 !important;
+        flex-grow: 0 !important;
+        margin: 0 !important;
+        padding: 0 !important;
+    }
+    
+    /* Ensure button containers have no extra spacing */
+    .grid-row > div > button {
+        margin: 1px !important;
+    }
+    
+    /* Override Gradio column gap for grid container */
+    .grid-container {
+        gap: 0 !important;
+        row-gap: 0 !important;
+        column-gap: 0 !important;
+    }
+    
+    .grid-container.column {
+        gap: 0 !important;
+        row-gap: 0 !important;
+        column-gap: 0 !important;
+    }
+    
+    /* Target any parent column that contains grid-row */
+    div.column:has(.grid-row) {
+        gap: 0 !important;
+        row-gap: 0 !important;
+        column-gap: 0 !important;
+    }
+    
+    .log-box textarea {
+        font-family: "JetBrains Mono", "SFMono-Regular", ui-monospace, monospace !important;
+        font-size: 13px !important;
+    }
+    
+    /* Theme-aware legend box */
+    .legend-box {
+        background: var(--status-bg);
+        padding: 10px;
+        border-radius: 8px;
+        color: var(--status-text);
+        border: 1px solid var(--progress-bg);
+    }
+    
+    .status-panel {
+        background: var(--status-bg);
+        border: 1px solid var(--progress-bg);
+        border-radius: 12px;
+        padding: 12px;
+        color: var(--status-text);
+    }
+    
+    .status-panel .status-compact {
+        margin: 0;
+    }
+    
+    /* Subtitle styling */
+    .subtitle {
+        color: var(--status-muted) !important;
+        font-size: 14px !important;
+        margin-top: -8px !important;
+        margin-bottom: 12px !important;
+    }
+    
+    /* AI Advisor highlight styling */
+    .ai-advisor-panel {
+        background: linear-gradient(135deg, rgba(59, 130, 246, 0.1), rgba(147, 51, 234, 0.1));
+        border: 2px solid rgba(99, 102, 241, 0.3);
+        border-radius: 12px;
+        padding: 16px;
+    }
+    
+    .dark .ai-advisor-panel {
+        background: linear-gradient(135deg, rgba(59, 130, 246, 0.15), rgba(147, 51, 234, 0.15));
+        border-color: rgba(99, 102, 241, 0.4);
+    }
+    
+    /* Accordion styling - more compact */
+    .gradio-accordion {
+        margin-bottom: 8px !important;
+    }
+    
+    /* Control buttons row spacing */
+    .control-buttons-row {
+        margin-top: 16px !important;
+    }
+    
+    /* How to play inline styling */
+    .how-to-play {
+        background: var(--status-bg);
+        border: 1px solid var(--progress-bg);
+        border-radius: 8px;
+        padding: 12px 16px !important;
+        margin: 8px 0 !important;
+        font-size: 14px;
+    }
+    
+    .how-to-play p {
+        margin: 4px 0 !important;
+    }
+    
+    /* Main heading styling */
+    h1 {
+        margin-bottom: 4px !important;
+    }
+    
+    h2 {
+        margin-top: 12px !important;
+        margin-bottom: 8px !important;
+    }
+    
+    /* Section spacing */
+    .section-gap {
+        margin-top: 16px !important;
+    }
+    
+    /* Compact status bar */
+    .status-bar {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 12px;
+        padding: 10px 16px;
+        background: var(--status-bg);
+        border-radius: 8px;
+        font-size: 14px;
+        align-items: center;
+        border: 1px solid var(--progress-bg);
+    }
+    
+    .status-bar .status-item {
+        display: flex;
+        align-items: center;
+        gap: 6px;
+    }
+    
+    .status-bar .status-badge {
+        padding: 2px 8px;
+        border-radius: 4px;
+        font-weight: bold;
+        font-size: 12px;
+    }
+    
+    .status-bar .progress-mini {
+        width: 80px;
+        height: 6px;
+        background: var(--progress-bg);
+        border-radius: 3px;
+        overflow: hidden;
+    }
+    
+    /* Compact status bar */
+    .status-compact {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 12px;
+        padding: 8px 14px;
+        background: var(--status-bg);
+        border-radius: 8px;
+        font-size: 14px;
+        align-items: center;
+        border: 1px solid var(--progress-bg);
+    }
+    
+    .status-compact .status-item {
+        display: flex;
+        align-items: center;
+        gap: 5px;
+    }
+    
+    .status-compact .status-badge {
+        padding: 2px 8px;
+        border-radius: 4px;
+        font-weight: bold;
+        font-size: 11px;
+        color: #000;
+    }
+    
+    .status-compact .status-health {
+        flex: 1;
+        min-width: 120px;
+    }
+    
+    .status-compact .progress-mini {
+        flex: 1;
+        min-width: 60px;
+        max-width: 100px;
+        height: 8px;
+        background: var(--progress-bg);
+        border-radius: 4px;
+        overflow: hidden;
+    }
+    
+    /* AI Thinking indicator in status bar */
+    .status-compact .ai-thinking-inline {
+        background: linear-gradient(135deg, rgba(99, 102, 241, 0.2), rgba(147, 51, 234, 0.2));
+        padding: 4px 10px;
+        border-radius: 6px;
+        border: 1px solid rgba(99, 102, 241, 0.4);
+        animation: ai-glow 1.5s ease-in-out infinite;
+    }
+    
+    .status-compact .ai-label {
+        font-weight: bold;
+        margin-right: 4px;
+        color: #a78bfa;
+    }
+    
+    .status-compact .ai-pulse {
+        animation: pulse-icon 1s ease-in-out infinite;
+    }
+    
+    @keyframes ai-glow {
+        0%, 100% { box-shadow: 0 0 5px rgba(99, 102, 241, 0.3); }
+        50% { box-shadow: 0 0 15px rgba(99, 102, 241, 0.6); }
+    }
+    
+    @keyframes pulse-icon {
+        0%, 100% { transform: scale(1); }
+        50% { transform: scale(1.2); }
+    }
+    
+    /* Win/Lose overlay */
+    .game-result-overlay {
+        position: fixed;
+        top: 0;
+        left: 0;
+        width: 100%;
+        height: 100%;
+        display: flex;
+        justify-content: center;
+        align-items: center;
+        background: rgba(0,0,0,0.7);
+        z-index: 9999;
+    }
+    
+    .game-result-box {
+        background: var(--status-bg);
+        padding: 32px 40px;
+        border-radius: 20px;
+        text-align: center;
+        animation: popup 0.3s ease-out;
+        width: min(90%, 90%);
+        max-height: 90vh;
+        overflow-y: auto;
+        box-shadow: 0 30px 80px rgba(0, 0, 0, 0.45);
+    }
+
+    .result-icon {
+        font-size: 60px;
+        margin-bottom: 12px;
+    }
+
+    .result-title {
+        font-size: 36px;
+        font-weight: 800;
+        letter-spacing: 1px;
+    }
+
+    .result-subtitle {
+        font-size: 18px;
+        color: var(--status-muted);
+        margin-bottom: 24px;
+    }
+
+    .result-report {
+        background: rgba(15, 23, 42, 0.6);
+        border: 1px solid rgba(255, 255, 255, 0.08);
+        border-radius: 16px;
+        padding: 20px 24px;
+        margin-bottom: 24px;
+        text-align: left;
+    }
+
+    .result-report-header {
+        display: flex;
+        justify-content: space-between;
+        align-items: center;
+        font-weight: 600;
+        margin-bottom: 12px;
+    }
+
+    .report-badge {
+        font-size: 12px;
+        text-transform: uppercase;
+        letter-spacing: 0.5px;
+        padding: 4px 10px;
+        border-radius: 999px;
+        background: rgba(56, 189, 248, 0.15);
+        color: #22d3ee;
+        border: 1px solid rgba(34, 211, 238, 0.3);
+    }
+
+    .report-badge.danger {
+        background: rgba(248, 113, 113, 0.15);
+        color: #f87171;
+        border-color: rgba(248, 113, 113, 0.4);
+    }
+
+    .result-report.ready {
+        background: rgba(23, 27, 45, 0.9);
+    }
+
+    .result-report.pending,
+    .result-report.error {
+        display: flex;
+        align-items: center;
+        gap: 16px;
+    }
+
+    .report-spinner {
+        width: 32px;
+        height: 32px;
+        border: 3px solid rgba(255, 255, 255, 0.2);
+        border-top-color: #22d3ee;
+        border-radius: 50%;
+        animation: report-spin 0.8s linear infinite;
+    }
+
+    @keyframes report-spin {
+        to { transform: rotate(360deg); }
+    }
+
+    .report-summary {
+        font-size: 16px;
+        margin-bottom: 16px;
+        color: var(--status-text);
+    }
+
+    .player-actions-block {
+        background: rgba(15, 23, 42, 0.75);
+        border: 1px dashed rgba(248, 250, 252, 0.2);
+        border-radius: 14px;
+        padding: 16px 18px;
+        margin-bottom: 18px;
+    }
+
+    .player-actions-header {
+        font-weight: 700;
+        letter-spacing: 0.08em;
+        text-transform: uppercase;
+        font-size: 13px;
+        color: #facc15;
+        margin-bottom: 6px;
+    }
+
+    .player-actions-summary {
+        margin: 0 0 12px 0;
+        color: var(--status-text);
+        font-size: 14px;
+    }
+
+    .player-actions-chips {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 8px;
+        margin-bottom: 12px;
+    }
+
+    .player-action-chip {
+        padding: 4px 10px;
+        border-radius: 999px;
+        border: 1px solid rgba(248, 113, 113, 0.35);
+        background: rgba(248, 113, 113, 0.08);
+        font-size: 12px;
+        color: #fed7aa;
+        letter-spacing: 0.03em;
+    }
+
+    .player-action-chip.muted {
+        opacity: 0.4;
+    }
+
+    .player-actions-list {
+        list-style: none;
+        margin: 0;
+        padding: 0;
+        display: flex;
+        flex-direction: column;
+        gap: 8px;
+    }
+
+    .player-actions-list li {
+        display: flex;
+        justify-content: space-between;
+        gap: 12px;
+        padding: 8px 12px;
+        border-radius: 10px;
+        border: 1px solid rgba(148, 163, 184, 0.2);
+        background: rgba(15, 23, 42, 0.9);
+        font-size: 13px;
+    }
+
+    .player-actions-list .action-tick {
+        font-weight: 600;
+        color: #38bdf8;
+    }
+
+    .player-actions-list .action-desc {
+        flex: 1;
+        text-align: right;
+        color: #e2e8f0;
+    }
+
+    .player-actions-empty {
+        margin: 0;
+        font-size: 13px;
+        color: var(--status-muted);
+        text-align: center;
+    }
+
+    .report-card-grid {
+        display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+        gap: 18px;
+    }
+
+    @media (min-width: 1100px) {
+        .report-card-grid {
+            grid-template-columns: repeat(3, minmax(0, 1fr));
+        }
+    }
+
+    .report-card {
+        background: rgba(15, 23, 42, 0.8);
+        border-radius: 16px;
+        padding: 18px;
+        border: 1px solid rgba(255, 255, 255, 0.08);
+        display: flex;
+        flex-direction: column;
+        gap: 12px;
+        min-height: 220px;
+    }
+
+    .report-card-header {
+        display: flex;
+        align-items: center;
+        gap: 12px;
+        text-transform: uppercase;
+        letter-spacing: 0.08em;
+        font-size: 13px;
+        font-weight: 700;
+        color: #e2e8f0;
+    }
+
+    .report-card-icon {
+        font-size: 22px;
+        line-height: 1;
+    }
+
+    .report-card-title {
+        flex: 1;
+    }
+
+    .report-card-body {
+        flex: 1;
+    }
+
+    .report-card ul {
+        list-style: disc;
+        margin: 0 0 0 18px;
+        padding: 0;
+        color: var(--status-text);
+        line-height: 1.45;
+    }
+
+    .report-card ul li {
+        margin-bottom: 6px;
+    }
+
+    .report-chart-grid {
+        margin-top: 20px;
+        display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+        gap: 16px;
+    }
+
+    .report-chart-card {
+        background: rgba(13, 20, 35, 0.85);
+        border-radius: 14px;
+        padding: 14px 16px 18px;
+        border: 1px solid rgba(255, 255, 255, 0.08);
+        display: flex;
+        flex-direction: column;
+        gap: 8px;
+    }
+
+    .mini-chart {
+        width: 100%;
+        height: 80px;
+    }
+
+    .mini-chart svg {
+        width: 100%;
+        height: 80px;
+    }
+
+    .chart-title {
+        font-size: 13px;
+        font-weight: 600;
+        color: #cbd5f5;
+        letter-spacing: 0.04em;
+        text-transform: uppercase;
+    }
+
+    .chart-meta {
+        display: flex;
+        justify-content: space-between;
+        font-size: 12px;
+        color: var(--status-muted);
+    }
+
+    .chart-value {
+        font-weight: 700;
+    }
+    
+    .chart-axis-values,
+    .chart-x-axis {
+        display: flex;
+        justify-content: space-between;
+        font-size: 11px;
+        color: var(--status-muted);
+    }
+    
+    .chart-axis-values {
+        margin-top: 4px;
+    }
+    
+    .chart-x-axis {
+        margin-top: 6px;
+    }
+    
+
+    .report-card.positive {
+        border-color: rgba(34, 197, 94, 0.3);
+    }
+
+    .report-card.risk {
+        border-color: rgba(248, 113, 113, 0.35);
+    }
+
+    .report-card.action {
+        border-color: rgba(59, 130, 246, 0.35);
+    }
+
+    .report-error {
+        color: #f87171;
+        margin: 0;
+    }
+
+    .report-empty {
+        color: var(--status-muted);
+        margin: 0;
+    }
+
+    .result-ok-btn {
+        width: 100%;
+        padding: 14px 0;
+        border: none;
+        border-radius: 999px;
+        background: linear-gradient(90deg, #22d3ee, #3b82f6);
+        color: #0f172a;
+        font-weight: 700;
+        font-size: 16px;
+        cursor: pointer;
+        transition: transform 0.2s ease, box-shadow 0.2s ease;
+    }
+
+    .result-ok-btn:hover {
+        transform: translateY(-1px);
+        box-shadow: 0 10px 25px rgba(34, 211, 238, 0.3);
+    }
+
+    .report-text p {
+        margin: 4px 0 0 0;
+        color: var(--status-muted);
+    }
+    
+    @keyframes popup {
+        from { transform: scale(0.8); opacity: 0; }
+        to { transform: scale(1); opacity: 1; }
+    }
+    
+    /* AI Thinking indicator animation */
+    .ai-thinking {
+        background: linear-gradient(90deg, rgba(99, 102, 241, 0.2), rgba(147, 51, 234, 0.2));
+        border-radius: 6px;
+        padding: 4px 10px !important;
+        animation: thinking-pulse 1.5s ease-in-out infinite;
+    }
+    
+    .thinking-indicator {
+        color: #a855f7;
+        font-weight: bold;
+        font-size: 13px;
+    }
+    
+    .dark .thinking-indicator {
+        color: #c084fc;
+    }
+    
+    @keyframes thinking-pulse {
+        0%, 100% { opacity: 1; background: linear-gradient(90deg, rgba(99, 102, 241, 0.2), rgba(147, 51, 234, 0.2)); }
+        50% { opacity: 0.7; background: linear-gradient(90deg, rgba(99, 102, 241, 0.4), rgba(147, 51, 234, 0.4)); }
+    }
+    
+    /* iOS-style AI Thinking Toast */
+    .ai-toast-container {
+        position: absolute;
+        top: 10px;
+        left: 50%;
+        transform: translateX(-50%);
+        z-index: 100;
+        animation: toast-slide-in 0.3s ease-out;
+    }
+    
+    .ai-toast {
+        display: flex;
+        align-items: center;
+        gap: 12px;
+        background: rgba(30, 30, 40, 0.95);
+        backdrop-filter: blur(20px);
+        -webkit-backdrop-filter: blur(20px);
+        border-radius: 16px;
+        padding: 12px 18px;
+        box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3), 
+                    0 0 0 1px rgba(255, 255, 255, 0.1);
+        min-width: 280px;
+    }
+    
+    .ai-toast-icon {
+        font-size: 28px;
+        line-height: 1;
+    }
+    
+    .ai-toast-content {
+        flex: 1;
+    }
+    
+    .ai-toast-title {
+        color: #ffffff;
+        font-weight: 600;
+        font-size: 15px;
+        margin-bottom: 2px;
+    }
+    
+    .ai-toast-subtitle {
+        color: rgba(255, 255, 255, 0.6);
+        font-size: 13px;
+    }
+    
+    .ai-toast-spinner {
+        width: 20px;
+        height: 20px;
+        border: 2px solid rgba(255, 255, 255, 0.2);
+        border-top-color: #a855f7;
+        border-radius: 50%;
+        animation: toast-spin 0.8s linear infinite;
+    }
+    
+    @keyframes toast-slide-in {
+        from {
+            opacity: 0;
+            transform: translateX(-50%) translateY(-20px);
+        }
+        to {
+            opacity: 1;
+            transform: translateX(-50%) translateY(0);
+        }
+    }
+    
+    @keyframes toast-spin {
+        to { transform: rotate(360deg); }
+    }
+    
+    /* Grid wrapper for toast positioning */
+    .grid-wrapper {
+        position: relative;
+    }
+"""
+
+
+def create_app() -> gr.Blocks:
+    """Create the Gradio application."""
+    
+    with gr.Blocks() as app:
+        # Inject CSS via HTML style tag (most compatible method)
+        gr.HTML(f"<style>{CUSTOM_CSS}</style>")
+        
+        # Header with title and instructions
+        gr.Markdown("# 🔥 Fire Rescue Simulator Game")
+        gr.Markdown("*An interactive game where you watch AI Agent autonomously fight fires using MCP tools!*")
+        gr.Markdown("""
+**🎮 How to Play:**
+- Click **Start**
+- **Auto-Execute** is optional: turn it OFF to fully control every action manually.
+- Watch AI's process: **Reasoning → Planning → Execution → Summary**
+- Select placement action:
+  - 🚒 **Fire Truck:** High power (40%), covers 1 tile outward from its center — best for intense fires & building threats
+  - 🚁 **Helicopter:** Wide coverage (25%), covers 2 tiles outward from its center — best for large-area control
+- **Settings & Controls:** Use the panel below to quickly tune scenario difficulty (fires, buildings, units, randomness) before sending the team in
+
+**🏆 Win:** Extinguish all fires | **💀 Lose:** Building ≤ 50%
+        """, elem_classes=["how-to-play"])
+        
+        # Collapsible Controls Section
+        with gr.Accordion("⚙️ Settings & Controls", open=False):
+            with gr.Row():
+                with gr.Column(scale=1):
+                    fire_count = gr.Slider(
+                        minimum=1, maximum=30, value=15, step=1,
+                        label="🔥 Initial Fire Count",
+                        info="Number of fire starting points (1-25)"
+                    )
+                with gr.Column(scale=1):
+                    fire_intensity = gr.Slider(
+                        minimum=0.2, maximum=0.9, value=0.6, step=0.05,
+                        label="🌡️ Fire Intensity",
+                        info="Initial fire strength (0.2-0.9)"
+                    )
+            with gr.Row():
+                with gr.Column(scale=1):
+                    building_count = gr.Slider(
+                        minimum=1, maximum=35, value=20, step=1,
+                        label="🏢 Building Count",
+                        info="Number of buildings (connected cluster)"
+                    )
+                with gr.Column(scale=1):
+                    max_units = gr.Slider(
+                        minimum=1, maximum=20, value=10, step=1,
+                        label="🚒 Max Units",
+                        info="Maximum deployable units (1-20)"
+                    )
+            with gr.Row():
+                with gr.Column(scale=1):
+                    seed_input = gr.Number(
+                        value=0, label="Random Seed (0 = random)", precision=0
+                    )
+        
+        
+        # Control buttons - always visible
+        with gr.Row(elem_classes=["control-buttons-row"]):
+            start_btn = gr.Button("▶️ Start", variant="primary", scale=1)
+            pause_btn = gr.Button("⏸️ Pause", variant="stop", interactive=False, scale=1)
+            reset_btn = gr.Button("🔄 Reset", scale=1)
+        
+        # Game result popup (hidden by default)
+        result_popup = gr.HTML(value="", visible=True)
+        
+        # Store grid buttons for updates
+        grid_buttons = []
+        
+        # Main content: AI Advisor (left) + Simulation Grid (right)
+        with gr.Row(elem_classes=["section-gap"]):
+            # Left column: AI Advisor - THE STAR OF THE SHOW
+            with gr.Column(scale=2, min_width=300):
+                service = get_service()
+                advisor_interval_ticks = getattr(service, "advisor_interval", 10)
+                tick_interval_seconds = getattr(service, "tick_interval", 1.0)
+                advisor_interval_seconds = advisor_interval_ticks * tick_interval_seconds
+                if isinstance(advisor_interval_seconds, float) and advisor_interval_seconds.is_integer():
+                    advisor_interval_display = int(advisor_interval_seconds)
+                else:
+                    advisor_interval_display = round(advisor_interval_seconds, 1)
+                gr.Markdown(
+                    f"## 🤖 AI Tactical Advisor · (refreshes ~every {advisor_interval_display} seconds)"
+                )
+                auto_execute_toggle = gr.Checkbox(
+                    label="🎮 Auto-Execute",
+                    value=True,
+                    info="Automatically execute AI recommendations",
+                )
+                
+                advisor_initial_messages = _get_combined_advisor_messages(service)
+                
+                with gr.Accordion("📜 AI Analysis History", open=True):
+                    gr.Markdown(
+                        "⚠️ **Heads-up**: This timeline refreshes whenever a new AI cycle starts. "
+                        "Hit `Pause` first if you want to read the full reasoning without it updating mid-run. "
+                        "All completed cycles remain in this view—just scroll to review earlier ticks."
+                    )
+                    advisor_display = gr.Chatbot(
+                        value=advisor_initial_messages,
+                        height=500,
+                        render_markdown=True,
+                        show_label=False,
+                        layout="panel",
+                        elem_classes=["advisor-chatbot"],
+                        avatar_images=(None, None),
+                    )
+                
+                # Collapsible Event Log
+                with gr.Accordion("📋 Event Log & Deploy Status", open=False):
+                    event_log_display = gr.Textbox(
+                        value="No events yet...",
+                        label="Events",
+                        lines=5,
+                        max_lines=10,
+                        interactive=False,
+                        elem_classes=["log-box"]
+                    )
+            
+            # Right column: Simulation Grid
+            with gr.Column(scale=2):
+                gr.Markdown("## 🗺️ Simulation Grid")
+                
+                # Click to place selector
+                with gr.Row():
+                    place_selector = gr.Radio(
+                        choices=["🚒 Truck", "🚁 Heli", "🔥 Fire"],
+                        value="🚒 Truck",
+                        label="Click Map to Place",
+                        scale=2
+                    )
+                
+                # Legend
+                gr.HTML("""
+                <div class="legend-box">
+                    <span style="margin-right: 15px;">🌲 Forest</span>
+                    <span style="margin-right: 15px;">🏢 Building</span>
+                    <span style="margin-right: 15px;">🔥 Fire</span>
+                    <span style="margin-right: 15px;">💨 Smoke</span>
+                    <span style="margin-right: 15px;">🚒 Truck</span>
+                    <span>🚁 Heli</span>
+                </div>
+                """)
+                
+                # Status display with progress bars - below legend (includes AI thinking indicator)
+                status_display = gr.HTML(
+                    value=render_status_html({"status": "idle"}),
+                    elem_classes=["status-panel"]
+                )
+                
+                # Grid container with no gap
+                with gr.Column(elem_classes=["grid-container"]):
+                    # X-axis labels (top row)
+                    with gr.Row(elem_classes=["grid-row"]):
+                        # Empty corner
+                        gr.Button(value="", elem_classes=["coord-label"], interactive=False, min_width=52)
+                        # X coordinates 0-9
+                        for x in range(10):
+                            gr.Button(value=str(x), elem_classes=["coord-label"], interactive=False, min_width=52)
+                    
+                    # Grid buttons with Y-axis labels
+                    for y in range(10):
+                        with gr.Row(elem_classes=["grid-row"]):
+                            # Y-axis label
+                            gr.Button(value=str(y), elem_classes=["coord-label"], interactive=False, min_width=52)
+                            # Grid cells
+                            for x in range(10):
+                                btn = gr.Button(
+                                    value="🌲",
+                                    elem_classes=["grid-btn"],
+                                    min_width=52,
+                                )
+                                grid_buttons.append((x, y, btn))
+        
+        # Timers: main simulation refresh + after-action poller
+        timer = gr.Timer(value=1.0, active=False)
+        report_timer = gr.Timer(value=1.0, active=False)
+        
+        # Collect all button outputs for updates
+        all_buttons = [btn for (_, _, btn) in grid_buttons]
+        
+        # Event handlers for simulation controls
+        start_btn.click(
+            fn=start_or_resume_simulation,
+            inputs=[fire_count, fire_intensity, building_count, max_units, seed_input],
+            outputs=[timer, report_timer, result_popup, advisor_display, event_log_display, start_btn, pause_btn, status_display] + all_buttons
+        )
+        
+        pause_btn.click(
+            fn=pause_simulation,
+            inputs=[],
+            outputs=[timer, report_timer, result_popup, advisor_display, event_log_display, start_btn, pause_btn, status_display] + all_buttons
+        )
+        
+        reset_btn.click(
+            fn=reset_simulation,
+            inputs=[fire_count, fire_intensity, building_count, max_units, seed_input],
+            outputs=[timer, report_timer, result_popup, advisor_display, event_log_display, start_btn, pause_btn, status_display] + all_buttons
+        )
+        
+        # Event handlers for grid buttons (click to place)
+        for x, y, btn in grid_buttons:
+            btn.click(
+                fn=lambda sel, _x=x, _y=y: deploy_at_cell(_x, _y, sel),
+                inputs=[place_selector],
+                outputs=[result_popup, advisor_display, event_log_display, status_display] + all_buttons
+            )
+        
+        # Timer tick handler - updates all components with change tracking
+        timer.tick(
+            fn=refresh_display,
+            outputs=[timer, report_timer, result_popup, advisor_display, event_log_display, start_btn, pause_btn, status_display] + all_buttons
+        )
+        
+        report_timer.tick(
+            fn=poll_after_action_report,
+            outputs=[report_timer, result_popup]
+        )
+        
+        # Auto-execute toggle handler
+        def on_auto_execute_toggle(enabled: bool):
+            service = get_service()
+            service.set_auto_execute(enabled)
+            # No return value needed since outputs=[]
+        
+        auto_execute_toggle.change(
+            fn=on_auto_execute_toggle,
+            inputs=[auto_execute_toggle],
+            outputs=[]
+        )
+    
+    return app
+
+
+def launch_simple():
+    """Launch simple Gradio app (for HF Spaces / local development)."""
+    gradio_app = create_app()
+    gradio_app.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        ssr_mode=False,  # Disable SSR for better compatibility
+        footer_links=["gradio", "settings"],  # Hide API docs button
+    )
+
+
+# For Hugging Face Spaces - must be named 'demo' for HF Spaces auto-detection
+demo = create_app()
+
+if __name__ == "__main__":
+    launch_simple()

fire_rescue_mcp/__init__.py

@@ -0,0 +1,13 @@
+"""
+Fire-Rescue MCP Server
+
+Pure MCP layer - provides tools for external LLM clients to interact with the simulation.
+"""
+
+from .mcp_server import mcp, run_server
+
+__version__ = "0.3.0"
+__all__ = [
+    "mcp",
+    "run_server",
+]

fire_rescue_mcp/mcp_server.py

@@ -0,0 +1,706 @@
+"""
+Fire-Rescue MCP Server
+
+Provides MCP tools for fire rescue simulation.
+MCP tools only return DATA - all decisions are made by AI.
+
+Core Operations:
+- reset_scenario: Initialize a new simulation
+- get_world_state: Get current world state snapshot
+- deploy_unit: Deploy a firefighting unit
+- move_unit: Move an existing unit to a new position
+- step_simulation: Advance simulation by ticks
+
+Data Query Tools:
+- find_idle_units: Get units not covering any fires
+- find_uncovered_fires: Get fires with no unit coverage
+- find_building_threats: Get fires near buildings
+- analyze_coverage: Get comprehensive coverage data
+"""
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from models import CellType, UnitType
+from simulation import SimulationEngine, SimulationConfig
+
+# Create FastMCP server instance
+mcp = FastMCP("Fire-Rescue Simulation")
+
+# Shared simulation engine instance
+_engine: Optional[SimulationEngine] = None
+
+# Unit effective ranges (matching SimulationConfig, Chebyshev/square distance)
+FIRE_TRUCK_RANGE = 1  # Square coverage radius (includes 8 neighbors)
+HELICOPTER_RANGE = 2  # Square coverage radius (extends two cells in all directions)
+
+
+def get_engine() -> SimulationEngine:
+    """Get or create the simulation engine singleton."""
+    global _engine
+    if _engine is None:
+        _engine = SimulationEngine()
+    return _engine
+
+
+def _get_unit_effective_range(unit_type: str) -> int:
+    """Get the effective range for a unit type (for coverage analysis)."""
+    if unit_type == "fire_truck":
+        return FIRE_TRUCK_RANGE
+    elif unit_type == "helicopter":
+        return HELICOPTER_RANGE
+    return 2  # Default
+
+
+def _calculate_distance(x1: int, y1: int, x2: int, y2: int) -> int:
+    """Calculate Chebyshev distance (square radius) between two points."""
+    return max(abs(x1 - x2), abs(y1 - y2))
+
+
+def _is_in_range(ux: int, uy: int, fx: int, fy: int, unit_type: str) -> bool:
+    """Check if a fire position is within unit's effective range."""
+    effective_range = _get_unit_effective_range(unit_type)
+    return _calculate_distance(ux, uy, fx, fy) <= effective_range
+
+
+def generate_emoji_map(engine: SimulationEngine) -> str:
+    """
+    Generate an emoji-based visualization of the current world state.
+    
+    Legend (matching Gradio UI):
+    - 🌲 Forest (no fire)
+    - 🏢 Building (no fire)
+    - 🔥 Fire (intensity >= 10%)
+    - 💨 Smoke (smoldering, intensity < 10%)
+    - 🚒 Fire Truck
+    - 🚁 Helicopter
+    """
+    if engine.world is None:
+        return "No map available"
+    
+    world = engine.world
+    
+    # Create unit position lookup
+    unit_positions = {}
+    for unit in world.units:
+        key = (unit.x, unit.y)
+        if key not in unit_positions:
+            unit_positions[key] = []
+        unit_positions[key].append(unit.unit_type.value)
+    
+    # Build the map with coordinates
+    lines = []
+    
+    # Header with X coordinates
+    header = "   " + "".join(f"{x:2}" for x in range(world.width))
+    lines.append(header)
+    
+    for y in range(world.height):
+        row_chars = []
+        for x in range(world.width):
+            cell = world.grid[y][x]
+            pos = (x, y)
+            
+            # Priority: Units > Fire > Terrain
+            if pos in unit_positions:
+                if "fire_truck" in unit_positions[pos]:
+                    row_chars.append("🚒")
+                else:
+                    row_chars.append("🚁")
+            elif cell.fire_intensity > 0:
+                # Show fire intensity (matching Gradio: >=10% = fire, <10% = smoke)
+                if cell.fire_intensity >= 0.1:
+                    row_chars.append("🔥")
+                else:
+                    row_chars.append("💨")
+            else:
+                # Show terrain
+                if cell.cell_type == CellType.BUILDING:
+                    row_chars.append("🏢")
+                elif cell.cell_type == CellType.FOREST:
+                    row_chars.append("🌲")
+                else:
+                    row_chars.append("⬜")
+        
+        lines.append(f"{y:2} " + "".join(row_chars))
+    
+    # Add legend (matching Gradio UI)
+    lines.append("")
+    lines.append("Legend: 🌲Forest 🏢Building 🔥Fire 💨Smoke 🚒Truck 🚁Heli")
+    
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def reset_scenario(
+    seed: Optional[int] = None,
+    fire_count: int = 10,
+    fire_intensity: float = 0.5,
+    building_count: int = 20,
+    max_units: int = 10
+) -> dict:
+    """
+    Reset and initialize a new fire rescue simulation scenario.
+    
+    Args:
+        seed: Random seed for reproducibility (optional)
+        fire_count: Number of initial fire points (1-25, default: 10)
+        fire_intensity: Initial fire intensity (0.2-0.9, default: 0.5)
+        building_count: Number of buildings to place (1-35, default: 20)
+        max_units: Maximum deployable units (1-20, default: 10)
+    
+    Returns:
+        Status, summary, and emoji map of the initial state
+    """
+    engine = get_engine()
+    
+    world = engine.reset(
+        seed=seed, 
+        fire_count=fire_count,
+        fire_intensity=fire_intensity,
+        building_count=building_count,
+        max_units=max_units
+    )
+    fires = world.get_fires()
+    
+    return {
+        "status": "ok",
+        "tick": world.tick,
+        "grid_size": f"{world.width}x{world.height}",
+        "initial_fires": len(fires),
+        "buildings": len(world.building_positions),
+        "max_units": world.max_units,
+        "max_ticks": world.max_ticks,
+        "emoji_map": generate_emoji_map(engine)
+    }
+
+
+@mcp.tool()
+def get_world_state() -> dict:
+    """
+    Get the current world state snapshot with emoji map visualization.
+    
+    Returns complete state of the simulation including:
+    - Current tick number
+    - Emoji map showing the battlefield visually
+    - Fire locations and intensities
+    - Deployed units and their positions
+    - Building integrity and forest burn ratio
+    - Recent events
+    
+    The emoji_map provides a visual overview:
+    🌲 Forest | 🏢 Building | 🔥 Fire (>=10%) | 💨 Smoke (<10%)
+    🚒 Fire Truck | 🚁 Helicopter
+    """
+    engine = get_engine()
+    
+    if engine.world is None:
+        return {
+            "status": "error",
+            "message": "Simulation not initialized. Call reset_scenario first."
+        }
+    
+    state = engine.get_state()
+    state["emoji_map"] = generate_emoji_map(engine)
+    
+    return state
+
+
+@mcp.tool()
+def deploy_unit(
+    unit_type: str,
+    x: int,
+    y: int,
+    source: str = "player"
+) -> dict:
+    """
+    Deploy a firefighting unit at the specified position.
+    
+    Args:
+        unit_type: Type of unit - "fire_truck" or "helicopter"
+        x: X coordinate (0 to grid_width-1)
+        y: Y coordinate (0 to grid_height-1)
+        source: Who initiated the deployment - "player", "player_accept", "auto_accept_ai"
+    
+    Returns:
+        Status and details of the deployed unit
+    """
+    engine = get_engine()
+    return engine.deploy_unit(unit_type, x, y, source)
+
+
+@mcp.tool()
+def step_simulation(ticks: int = 1) -> dict:
+    """
+    Advance the simulation by the specified number of ticks.
+    
+    Args:
+        ticks: Number of ticks to advance (default: 1)
+    
+    Returns:
+        Current world state with emoji map after advancing
+    """
+    engine = get_engine()
+    
+    if engine.world is None:
+        return {
+            "status": "error",
+            "message": "Simulation not initialized. Call reset_scenario first."
+        }
+    
+    for _ in range(ticks):
+        engine.step()
+    
+    state = engine.get_state()
+    state["emoji_map"] = generate_emoji_map(engine)
+    
+    return state
+
+
+@mcp.tool()
+def move_unit(
+    source_x: int,
+    source_y: int,
+    target_x: int,
+    target_y: int
+) -> dict:
+    """
+    Move an existing unit from source position to target position.
+    Useful for repositioning idle units to cover uncovered fires.
+    
+    Args:
+        source_x: Current X coordinate of the unit
+        source_y: Current Y coordinate of the unit
+        target_x: New X coordinate to move to
+        target_y: New Y coordinate to move to
+    
+    Returns:
+        Status and details of the move operation
+    """
+    engine = get_engine()
+    
+    if engine.world is None:
+        return {
+            "status": "error",
+            "message": "Simulation not initialized. Call reset_scenario first."
+        }
+    
+    # Find unit at source position
+    unit_to_move = None
+    for unit in engine.world.units:
+        if unit.x == source_x and unit.y == source_y:
+            unit_to_move = unit
+            break
+    
+    if unit_to_move is None:
+        return {
+            "status": "error",
+            "message": f"No unit found at source position ({source_x}, {source_y})"
+        }
+    
+    unit_type = unit_to_move.unit_type.value
+    
+    # Remove unit from source
+    remove_result = engine.remove_unit_at(source_x, source_y)
+    if remove_result.get("status") != "ok":
+        return {
+            "status": "error",
+            "message": f"Failed to remove unit: {remove_result.get('message')}"
+        }
+    
+    # Deploy unit at target
+    deploy_result = engine.deploy_unit(unit_type, target_x, target_y, "ai_move")
+    if deploy_result.get("status") != "ok":
+        # Restore unit at original position
+        engine.deploy_unit(unit_type, source_x, source_y, "ai_restore")
+        return {
+            "status": "error",
+            "message": f"Failed to deploy at target: {deploy_result.get('message')}. Unit restored to original position."
+        }
+    
+    return {
+        "status": "ok",
+        "unit_type": unit_type,
+        "source": {"x": source_x, "y": source_y},
+        "target": {"x": target_x, "y": target_y},
+        "message": f"Moved {unit_type} from ({source_x}, {source_y}) to ({target_x}, {target_y})"
+    }
+
+
+@mcp.tool()
+def remove_unit(
+    x: int,
+    y: int
+) -> dict:
+    """
+    Remove an existing unit at the specified position.
+    Use this to free up a deployment slot, then deploy_unit to place a new unit elsewhere.
+    
+    Args:
+        x: X coordinate of the unit to remove
+        y: Y coordinate of the unit to remove
+    
+    Returns:
+        Status and details of the removed unit
+    
+    Example use cases:
+    - Remove ineffective truck, then deploy helicopter at better position
+    - Free up deployment slot when unit is no longer needed
+    - Reposition unit: remove_unit + deploy_unit at new location
+    """
+    engine = get_engine()
+    
+    if engine.world is None:
+        return {
+            "status": "error",
+            "message": "Simulation not initialized. Call reset_scenario first."
+        }
+    
+    # Find unit at position
+    unit_to_remove = None
+    for unit in engine.world.units:
+        if unit.x == x and unit.y == y:
+            unit_to_remove = unit
+            break
+    
+    if unit_to_remove is None:
+        return {
+            "status": "error",
+            "message": f"No unit found at position ({x}, {y})"
+        }
+    
+    removed_unit_type = unit_to_remove.unit_type.value
+    
+    # Remove the unit
+    remove_result = engine.remove_unit_at(x, y)
+    if remove_result.get("status") != "ok":
+        return {
+            "status": "error",
+            "message": f"Failed to remove unit: {remove_result.get('message')}"
+        }
+    
+    return {
+        "status": "ok",
+        "removed_unit_type": removed_unit_type,
+        "position": {"x": x, "y": y},
+        "message": f"Removed {removed_unit_type} at ({x}, {y}). You can now deploy a new unit."
+    }
+
+
+@mcp.tool()
+def find_idle_units() -> dict:
+    """
+    Find units that are not covering any fires (idle/ineffective units).
+    
+    An idle unit is one where NO fires exist within its effective range:
+    - Fire Truck effective range: 2 cells
+    - Helicopter effective range: 3 cells
+    
+    Returns:
+        List of idle units and effective units with their positions
+    """
+    engine = get_engine()
+    
+    if engine.world is None:
+        return {
+            "status": "error",
+            "message": "Simulation not initialized. Call reset_scenario first."
+        }
+    
+    world = engine.world
+    fires = world.get_fires()
+    fire_positions = [(f.x, f.y, f.intensity) for f in fires]
+    
+    idle_units = []
+    effective_units = []
+    
+    for unit in world.units:
+        unit_type = unit.unit_type.value
+        has_fire_in_range = False
+        
+        # Check if any fire is within this unit's effective range
+        for fx, fy, intensity in fire_positions:
+            if _is_in_range(unit.x, unit.y, fx, fy, unit_type):
+                has_fire_in_range = True
+                break
+        
+        unit_info = {
+            "x": unit.x,
+            "y": unit.y,
+            "type": unit_type,
+            "effective_range": _get_unit_effective_range(unit_type)
+        }
+        
+        if has_fire_in_range:
+            effective_units.append(unit_info)
+        else:
+            idle_units.append(unit_info)
+    
+    return {
+        "status": "ok",
+        "idle_units": idle_units,
+        "idle_count": len(idle_units),
+        "effective_units": effective_units,
+        "effective_count": len(effective_units),
+        "total_units": len(world.units)
+    }
+
+
+@mcp.tool()
+def find_uncovered_fires() -> dict:
+    """
+    Find fires that have NO unit coverage.
+    
+    An uncovered fire is one where NO unit is within effective range:
+    - Fire Truck range: 2 cells
+    - Helicopter range: 3 cells
+    
+    Returns:
+        List of uncovered fires with their positions, intensity, and building threat status
+    """
+    engine = get_engine()
+    
+    if engine.world is None:
+        return {
+            "status": "error",
+            "message": "Simulation not initialized. Call reset_scenario first."
+        }
+    
+    world = engine.world
+    fires = world.get_fires()
+    units = world.units
+    building_positions = set(world.building_positions)
+    
+    uncovered_fires = []
+    covered_fires = []
+    
+    for fire in fires:
+        is_covered = False
+        
+        # Check if any unit covers this fire
+        for unit in units:
+            unit_type = unit.unit_type.value
+            if _is_in_range(unit.x, unit.y, fire.x, fire.y, unit_type):
+                is_covered = True
+                break
+        
+        # Check if fire threatens any building (within 2 cells)
+        threatens_building = False
+        for bx, by in building_positions:
+            if _calculate_distance(fire.x, fire.y, bx, by) <= 2:
+                threatens_building = True
+                break
+        
+        fire_info = {
+            "x": fire.x,
+            "y": fire.y,
+            "intensity": round(fire.intensity, 2),
+            "threatens_building": threatens_building
+        }
+        
+        if is_covered:
+            covered_fires.append(fire_info)
+        else:
+            uncovered_fires.append(fire_info)
+    
+    return {
+        "status": "ok",
+        "uncovered_fires": uncovered_fires,
+        "uncovered_count": len(uncovered_fires),
+        "covered_fires": covered_fires,
+        "covered_count": len(covered_fires),
+        "total_fires": len(fires),
+        "coverage_ratio": round(len(covered_fires) / len(fires), 2) if fires else 1.0
+    }
+
+
+@mcp.tool()
+def find_building_threats() -> dict:
+    """
+    Find fires that are threatening buildings (within 2 cells of any building).
+    
+    Returns:
+        List of building-threatening fires with their positions, threatened buildings, and coverage status
+    """
+    engine = get_engine()
+    
+    if engine.world is None:
+        return {
+            "status": "error",
+            "message": "Simulation not initialized. Call reset_scenario first."
+        }
+    
+    world = engine.world
+    fires = world.get_fires()
+    units = world.units
+    building_positions = set(world.building_positions)
+    
+    building_threats = []
+    
+    for fire in fires:
+        # Check if fire threatens any building
+        threatened_buildings = []
+        for bx, by in building_positions:
+            dist = _calculate_distance(fire.x, fire.y, bx, by)
+            if dist <= 2:
+                threatened_buildings.append({"x": bx, "y": by, "distance": dist})
+        
+        if not threatened_buildings:
+            continue
+        
+        # Check if this fire is covered
+        is_covered = False
+        covering_unit = None
+        for unit in units:
+            unit_type = unit.unit_type.value
+            if _is_in_range(unit.x, unit.y, fire.x, fire.y, unit_type):
+                is_covered = True
+                covering_unit = {"x": unit.x, "y": unit.y, "type": unit_type}
+                break
+        
+        building_threats.append({
+            "fire": {"x": fire.x, "y": fire.y, "intensity": round(fire.intensity, 2)},
+            "threatened_buildings": threatened_buildings,
+            "is_covered": is_covered,
+            "covering_unit": covering_unit
+        })
+    
+    uncovered_threats = [t for t in building_threats if not t["is_covered"]]
+    
+    return {
+        "status": "ok",
+        "building_threats": building_threats,
+        "total_threats": len(building_threats),
+        "uncovered_threats": len(uncovered_threats),
+        "building_integrity": round(world.building_integrity, 2)
+    }
+
+
+@mcp.tool()
+def analyze_coverage() -> dict:
+    """
+    Get comprehensive coverage analysis data.
+    
+    This tool combines information from multiple analyses:
+    - Idle units (not covering any fire)
+    - Uncovered fires (no unit in range)
+    - Building threats (fires near buildings)
+    - High intensity fires
+    
+    Returns:
+        Comprehensive data about fires, units, and coverage status
+    """
+    engine = get_engine()
+    
+    if engine.world is None:
+        return {
+            "status": "error",
+            "message": "Simulation not initialized. Call reset_scenario first."
+        }
+    
+    world = engine.world
+    fires = world.get_fires()
+    units = world.units
+    building_positions = set(world.building_positions)
+    
+    # Analyze fires
+    fire_analysis = {
+        "total": len(fires),
+        "high_intensity": [],  # >70%
+        "building_threats": [],  # within 2 cells of building
+        "uncovered": []  # no unit in range
+    }
+    
+    # Analyze units
+    unit_analysis = {
+        "total": len(units),
+        "max_units": world.max_units,
+        "available_slots": world.max_units - len(units),
+        "idle": [],  # no fire in range
+        "effective": []  # has fire in range
+    }
+    
+    # Process fires
+    for fire in fires:
+        fire_info = {"x": fire.x, "y": fire.y, "intensity": round(fire.intensity, 2)}
+        
+        # High intensity check
+        if fire.intensity > 0.7:
+            fire_analysis["high_intensity"].append(fire_info)
+        
+        # Building threat check
+        for bx, by in building_positions:
+            if _calculate_distance(fire.x, fire.y, bx, by) <= 2:
+                fire_analysis["building_threats"].append(fire_info)
+                break
+        
+        # Coverage check
+        is_covered = False
+        for unit in units:
+            if _is_in_range(unit.x, unit.y, fire.x, fire.y, unit.unit_type.value):
+                is_covered = True
+                break
+        if not is_covered:
+            fire_analysis["uncovered"].append(fire_info)
+    
+    # Process units
+    fire_positions = [(f.x, f.y) for f in fires]
+    for unit in units:
+        unit_info = {"x": unit.x, "y": unit.y, "type": unit.unit_type.value}
+        
+        has_fire = False
+        for fx, fy in fire_positions:
+            if _is_in_range(unit.x, unit.y, fx, fy, unit.unit_type.value):
+                has_fire = True
+                break
+        
+        if has_fire:
+            unit_analysis["effective"].append(unit_info)
+        else:
+            unit_analysis["idle"].append(unit_info)
+    
+    # Calculate coverage ratio
+    coverage_ratio = 1.0
+    if fires:
+        covered_count = len(fires) - len(fire_analysis["uncovered"])
+        coverage_ratio = covered_count / len(fires)
+    
+    return {
+        "status": "ok",
+        "building_integrity": round(world.building_integrity, 2),
+        "coverage_ratio": round(coverage_ratio, 2),
+        "fire_analysis": {
+            "total_fires": fire_analysis["total"],
+            "high_intensity_count": len(fire_analysis["high_intensity"]),
+            "high_intensity_fires": fire_analysis["high_intensity"],
+            "building_threat_count": len(fire_analysis["building_threats"]),
+            "building_threat_fires": fire_analysis["building_threats"],
+            "uncovered_count": len(fire_analysis["uncovered"]),
+            "uncovered_fires": fire_analysis["uncovered"]
+        },
+        "unit_analysis": {
+            "deployed": unit_analysis["total"],
+            "max_units": unit_analysis["max_units"],
+            "available_slots": unit_analysis["available_slots"],
+            "idle_count": len(unit_analysis["idle"]),
+            "idle_units": unit_analysis["idle"],
+            "effective_count": len(unit_analysis["effective"]),
+            "effective_units": unit_analysis["effective"]
+        },
+        "emoji_map": generate_emoji_map(engine)
+    }
+
+
+def run_server():
+    """Run the MCP server with stdio transport."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    run_server()

models.py

@@ -0,0 +1,356 @@
+"""
+Fire-Rescue - Data Models
+
+Defines core data structures for the fire rescue simulation.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+import random
+
+
+class UnitType(str, Enum):
+    """Types of firefighting units available."""
+    FIRE_TRUCK = "fire_truck"
+    HELICOPTER = "helicopter"
+
+
+class CellType(str, Enum):
+    """Types of terrain cells in the grid."""
+    EMPTY = "empty"
+    BUILDING = "building"
+    FOREST = "forest"
+
+
+class SimulationStatus(str, Enum):
+    """Status of the simulation."""
+    IDLE = "idle"
+    RUNNING = "running"
+    SUCCESS = "success"
+    FAIL = "fail"
+
+
+class FireLevel(str, Enum):
+    """Initial fire intensity levels."""
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+@dataclass
+class Fire:
+    """Represents a fire cell in the grid."""
+    x: int
+    y: int
+    intensity: float  # 0.0 to 1.0
+    
+    def to_dict(self) -> dict:
+        return {
+            "x": self.x,
+            "y": self.y,
+            "intensity": round(self.intensity, 2)
+        }
+
+
+@dataclass
+class Unit:
+    """Represents a firefighting unit."""
+    id: str
+    unit_type: UnitType
+    owner: str  # "player" or "ai"
+    x: int
+    y: int
+    cooldown: int = 0  # Ticks until next action
+    
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "type": self.unit_type.value,
+            "owner": self.owner,
+            "x": self.x,
+            "y": self.y
+        }
+
+
+@dataclass
+class Event:
+    """Represents a simulation event."""
+    tick: int
+    event_type: str
+    details: dict = field(default_factory=dict)
+    
+    def to_dict(self) -> dict:
+        return {
+            "tick": self.tick,
+            "type": self.event_type,
+            **self.details
+        }
+
+
+@dataclass
+class Cell:
+    """Represents a cell in the grid."""
+    x: int
+    y: int
+    cell_type: CellType
+    fire_intensity: float = 0.0  # 0.0 = no fire, 1.0 = max fire
+    damage: float = 0.0  # Accumulated damage (0.0 to 1.0)
+    
+    def is_on_fire(self) -> bool:
+        return self.fire_intensity > 0.0
+    
+    def is_destroyed(self) -> bool:
+        return self.damage >= 1.0
+
+
+@dataclass
+class WorldState:
+    """
+    Represents the complete state of the simulation world.
+    Uses a 2D grid system.
+    """
+    width: int
+    height: int
+    tick: int = 0
+    status: SimulationStatus = SimulationStatus.IDLE
+    
+    # Grid cells
+    grid: list[list[Cell]] = field(default_factory=list)
+    
+    # Units on the field
+    units: list[Unit] = field(default_factory=list)
+    
+    # Recent events for logging
+    recent_events: list[Event] = field(default_factory=list)
+    
+    # Global metrics
+    building_integrity: float = 1.0  # Average building health (0.0 to 1.0)
+    forest_burn_ratio: float = 0.0   # Percentage of forest burned (0.0 to 1.0)
+    
+    # Configuration
+    max_ticks: int = 200
+    max_units: int = 10
+    seed: Optional[int] = None
+    
+    # Building positions (for dynamic placement)
+    building_positions: list[tuple[int, int]] = field(default_factory=list)
+    
+    # Unit ID counter
+    _unit_counter: int = 0
+    
+    def initialize_grid(
+        self, 
+        seed: Optional[int] = None, 
+        fire_count: int = 4,
+        fire_intensity: float = 0.6,
+        building_count: int = 16
+    ):
+        """
+        Initialize the grid with terrain and initial fires.
+        
+        Args:
+            seed: Random seed for reproducibility
+            fire_count: Number of initial fire points (1-25)
+            fire_intensity: Initial fire intensity (0.0-1.0)
+            building_count: Number of buildings to place (1-25)
+        """
+        if seed is not None:
+            random.seed(seed)
+            self.seed = seed
+        
+        # Clamp values to valid ranges
+        fire_count = max(1, min(25, fire_count))
+        fire_intensity = max(0.0, min(1.0, fire_intensity))
+        building_count = max(1, min(25, building_count))
+        
+        # Generate random building positions (connected cluster)
+        self.building_positions = self._generate_building_positions(building_count)
+        building_set = set(self.building_positions)
+        
+        self.grid = []
+        for y in range(self.height):
+            row = []
+            for x in range(self.width):
+                # Default to forest
+                cell_type = CellType.FOREST
+                
+                # Place buildings at generated positions
+                if (x, y) in building_set:
+                    cell_type = CellType.BUILDING
+                
+                row.append(Cell(x=x, y=y, cell_type=cell_type))
+            self.grid.append(row)
+        
+        # Place initial fires
+        fires_placed = 0
+        attempts = 0
+        max_attempts = 100
+        
+        while fires_placed < fire_count and attempts < max_attempts:
+            x = random.randint(0, self.width - 1)
+            y = random.randint(0, self.height - 1)
+            
+            # Only place fire on forest initially (not buildings)
+            cell = self.grid[y][x]
+            if cell.cell_type == CellType.FOREST and cell.fire_intensity == 0:
+                cell.fire_intensity = fire_intensity
+                fires_placed += 1
+            
+            attempts += 1
+    
+    def _generate_building_positions(self, count: int) -> list[tuple[int, int]]:
+        """
+        Generate random building positions ensuring connectivity.
+        
+        Buildings grow as a connected cluster from a random starting point.
+        At least 2 buildings will be adjacent (if count >= 2).
+        """
+        if count <= 0:
+            return []
+        
+        positions = []
+        
+        # Start with a random position (avoid edges for better growth)
+        start_x = random.randint(2, self.width - 3)
+        start_y = random.randint(2, self.height - 3)
+        positions.append((start_x, start_y))
+        
+        if count == 1:
+            return positions
+        
+        # Grow the cluster by adding adjacent cells
+        directions = [(-1, 0), (1, 0), (0, -1), (0, 1)]  # 4-directional adjacency
+        
+        while len(positions) < count:
+            # Get all possible adjacent positions to existing buildings
+            candidates = set()
+            for (px, py) in positions:
+                for dx, dy in directions:
+                    nx, ny = px + dx, py + dy
+                    # Check bounds and not already a building
+                    if 0 <= nx < self.width and 0 <= ny < self.height:
+                        if (nx, ny) not in positions:
+                            candidates.add((nx, ny))
+            
+            if not candidates:
+                # No more valid positions (unlikely but handle it)
+                break
+            
+            # Randomly select one candidate
+            new_pos = random.choice(list(candidates))
+            positions.append(new_pos)
+        
+        return positions
+    
+    def get_cell(self, x: int, y: int) -> Optional[Cell]:
+        """Get cell at position, returns None if out of bounds."""
+        if 0 <= x < self.width and 0 <= y < self.height:
+            return self.grid[y][x]
+        return None
+    
+    def get_fires(self) -> list[Fire]:
+        """Get list of all active fires."""
+        fires = []
+        for row in self.grid:
+            for cell in row:
+                if cell.is_on_fire():
+                    fires.append(Fire(x=cell.x, y=cell.y, intensity=cell.fire_intensity))
+        return fires
+    
+    def generate_unit_id(self, unit_type: UnitType) -> str:
+        """Generate a unique unit ID."""
+        self._unit_counter += 1
+        prefix = "truck" if unit_type == UnitType.FIRE_TRUCK else "heli"
+        return f"{prefix}_{self._unit_counter}"
+    
+    def add_unit(self, unit_type: UnitType, x: int, y: int, source: str) -> Optional[Unit]:
+        """Add a new unit to the world. Returns None if limit reached or position invalid."""
+        if len(self.units) >= self.max_units:
+            return None
+        
+        if not (0 <= x < self.width and 0 <= y < self.height):
+            return None
+        
+        # Check cell conditions - cannot deploy on fire or buildings
+        cell = self.get_cell(x, y)
+        if cell is None:
+            return None
+        
+        # Cannot deploy on burning cells
+        if cell.fire_intensity > 0:
+            return None
+        
+        # Cannot deploy on buildings
+        if cell.cell_type == CellType.BUILDING:
+            return None
+        
+        unit = Unit(
+            id=self.generate_unit_id(unit_type),
+            unit_type=unit_type,
+            owner="player",
+            x=x,
+            y=y
+        )
+        self.units.append(unit)
+        
+        # Record event
+        self.recent_events.append(Event(
+            tick=self.tick,
+            event_type="deploy_unit",
+            details={
+                "by": source,
+                "unit_type": unit_type.value,
+                "x": x,
+                "y": y
+            }
+        ))
+        
+        # Keep only recent events (last 20)
+        if len(self.recent_events) > 20:
+            self.recent_events = self.recent_events[-20:]
+        
+        return unit
+    
+    def calculate_metrics(self):
+        """Recalculate global metrics (building damage ratio)."""
+        total_buildings = 0
+        burning_buildings = 0
+        
+        for row in self.grid:
+            for cell in row:
+                if cell.cell_type == CellType.BUILDING:
+                    total_buildings += 1
+                    # Building is burning if it has fire on it
+                    if cell.fire_intensity > 0:
+                        burning_buildings += 1
+        
+        # Building integrity: ratio of non-burning buildings
+        if total_buildings > 0:
+            self.building_integrity = (total_buildings - burning_buildings) / total_buildings
+        else:
+            self.building_integrity = 1.0
+        
+        # Store total buildings for reference
+        self._total_buildings = total_buildings
+        self._burning_buildings = burning_buildings
+        
+        # Forest burn ratio is no longer used (replaced by active fires count)
+        self.forest_burn_ratio = 0.0
+    
+    def to_dict(self) -> dict:
+        """Serialize world state to dictionary."""
+        return {
+            "tick": self.tick,
+            "status": self.status.value,
+            "width": self.width,
+            "height": self.height,
+            "fires": [f.to_dict() for f in self.get_fires()],
+            "units": [u.to_dict() for u in self.units],
+            "building_integrity": round(self.building_integrity, 2),
+            "forest_burn_ratio": round(self.forest_burn_ratio, 2),
+            "recent_events": [e.to_dict() for e in self.recent_events[-5:]],
+            "buildings": [{"x": x, "y": y} for x, y in self.building_positions],
+            "max_units": self.max_units,
+        }
+

prompts.yaml

@@ -0,0 +1,378 @@
+# Fire-Rescue AI Agent Prompts Configuration
+# Multi-stage analysis: ASSESS → PLAN → EXECUTE
+# 
+# MCP Tools Available for Analysis:
+# - analyze_coverage(): Get comprehensive tactical analysis
+# - find_idle_units(): Find units not covering any fires
+# - find_uncovered_fires(): Find fires with no unit coverage
+# - find_building_threats(): Find fires threatening buildings (within 2 cells)
+# - move_unit(source_x, source_y, target_x, target_y): Reposition a unit
+# - deploy_unit(unit_type, x, y): Deploy new unit
+# - remove_unit(x, y): Remove a unit (then deploy_unit elsewhere)
+
+assess:
+  system: |
+    You are a SMART fire rescue tactical analyst. ASSESS the battlefield CAREFULLY!
+    
+    🎯 WIN/LOSE CONDITIONS (CRITICAL):
+    - ❌ LOSE: Building integrity drops below 50%
+    - ✅ WIN: ALL fires extinguished
+    
+    ⚠️ KEY PRINCIPLE: SMART DEPLOYMENT!
+    - Analyze the situation FIRST before deciding how many units to deploy
+    - Don't deploy more than necessary - be efficient!
+    - BUT ensure all building threats and critical fires ARE covered!
+    - Balance: enough units to control the situation, not wasteful overkill
+    
+    📡 MCP TOOLS AVAILABLE:
+    - `find_building_threats()` → 🏢 HIGHEST PRIORITY! Fires within 2 cells of buildings
+    - `find_uncovered_fires()` → Fires with NO unit coverage
+    - `find_idle_units()` → Units NOT covering fires (REPOSITION these first!)
+    - `analyze_coverage()` → Comprehensive tactical analysis
+    
+    CRITICAL ANALYSIS PRIORITIES (IN ORDER):
+    
+    1. **🏢 BUILDINGS FIRST - ALWAYS! (HIGHEST PRIORITY)**
+       - Use `find_building_threats()` to identify fires near buildings
+       - Building-adjacent fires cause DIRECT damage → triggers GAME OVER!
+       - ANY fire within 2 cells of a building = EMERGENCY
+       - These MUST be covered - non-negotiable!
+    
+    2. **🔥 FIRE COVERAGE - SMART ANALYSIS**
+       - Use `find_uncovered_fires()` to find fires needing units
+       - Count how many fires are uncovered vs how many units we have
+       - Consider: Can we reposition idle units FIRST before deploying new?
+       - Fire Truck: Covers 1 tile outward from its center (all 8 neighbors), power 40% — BEST for building threats & high intensity!
+       - Helicopter: Covers 2 tiles outward from its center, power 25% — great for area coverage & HARD-TO-REACH fires!
+       
+       🚁 **HELICOPTER ADVANTAGE - USE WHEN:**
+       - Fire is SURROUNDED by buildings/obstacles (trucks can't reach center)
+       - Fire persists despite multiple trucks nearby (need longer range)
+       - Fire is in a confined area where trucks can't get close enough
+       - A helicopter covering 2 tiles outward can reach fires that trucks (1-tile reach) cannot!
+    
+    3. **🔄 UNIT OPTIMIZATION (DO THIS FIRST!)**
+       - Use `find_idle_units()` to find wasted units
+       - IDLE units should be repositioned BEFORE deploying new units
+       - This is FREE optimization - doesn't use deployment slots!
+    
+    4. **Threat Level Determination**
+       - CRITICAL: ANY uncovered building threat OR building integrity <60%
+       - HIGH: 2+ building threats OR building integrity <80%
+       - MODERATE: 3+ uncovered fires OR any high-intensity fire
+       - LOW: All fires covered AND buildings safe
+    
+    You MUST respond in valid JSON format only.
+  
+  output_format: |
+    {
+      "fire_analysis": {
+        "total_fires": <number>,
+        "high_intensity_count": <number>,
+        "high_intensity_positions": [[x,y], ...],
+        "building_threat_count": <number>,
+        "building_threat_positions": [[x,y], ...],
+        "uncovered_fire_count": <number>,
+        "uncovered_fire_positions": [[x,y], ...]
+      },
+      "unit_analysis": {
+        "total_units": <number>,
+        "effective_count": <number>,
+        "ineffective_count": <number>,
+        "ineffective_positions": [[x,y,type], ...],
+        "coverage_ratio": <0.0-1.0>
+      },
+      "threat_level": "CRITICAL" | "HIGH" | "MODERATE" | "LOW",
+      "summary": "Brief 1-2 sentence assessment"
+    }
+
+plan:
+  system: |
+    You are a SMART fire rescue tactical planner. Analyze the situation and deploy EFFICIENTLY!
+    
+    🎯 WIN/LOSE CONDITIONS:
+    - ❌ LOSE: Building integrity drops below 50%
+    - ✅ WIN: ALL fires extinguished
+    
+    ⚠️ SMART DEPLOYMENT PRINCIPLE:
+    - Analyze the battlefield FIRST, then decide how many units to deploy
+    - DON'T deploy more units than necessary - be efficient!
+    - BUT don't be too conservative either - cover all threats!
+    - Key question: "How many units do I NEED to control this situation?"
+    - MASS FIRE RULE: If uncovered fires >=4 or the board is lighting up fast, DEFAULT to deploying extra units immediately (fill available slots if needed!) before the fire spreads further.
+    
+    📡 MCP TOOLS:
+    - `find_building_threats()` → 🏢 HIGHEST PRIORITY! Must cover these!
+    - `find_uncovered_fires()` → Fires needing coverage
+    - `find_idle_units()` → Units to reposition first
+    - `analyze_coverage()` → Full tactical view
+    
+    STRATEGIC PRIORITIES (STRICT ORDER):
+    
+    1. **🏢 BUILDINGS = SURVIVAL (ALWAYS FIRST!)**
+       - Building threats = EXISTENTIAL DANGER
+       - Cover ALL building-adjacent fires BEFORE anything else!
+       - Always deploy or reposition units hugging these burning buildings (adjacent or the closest legal tile) before touching any other fire.
+       - Use Fire Trucks for building threats (40% power = faster extinguish)
+    
+    2. **🔄 REPOSITION IDLE UNITS FIRST**
+       - Idle units are WASTED resources - use them!
+       - Move EVERY idle unit to stand 1 cell away from an active fire (prioritize building threats!)
+       - Never leave a unit sitting on an empty cell with no nearby fire.
+       - If idle_units > 0 AND uncovered_fires > 0 → REPOSITION!
+       - If idle_units > uncovered_fires, immediately REMOVE the surplus units (`remove_unit`) so their slots can be redeployed efficiently.
+       - If a unit truly has no reachable fire, REMOVE it (`remove_unit`) so the slot can be redeployed immediately.
+    
+    3. **🚀 DEPLOY NEW UNITS - SMART CALCULATION**
+       - DON'T just deploy all available slots blindly!
+       - Calculate: how many NEW units do we ACTUALLY need?
+       - Consider: fires will spread, so plan ahead a bit
+    - If there are MANY fires (>=6) or multiple clusters, PRIORITIZE rapid deployments over slow repositioning—getting more units on the board fast is the safest play.
+
+    🔧 ADDITIONAL STRATEGIC GUIDELINES:
+    - Maintain a balanced distribution of fire trucks across the grid. Do NOT cluster everything in one sector; ensure each quadrant can cover new hotspots quickly.
+    - Re-evaluate the need for helicopters each cycle. Keep at least one deployment slot available for rapid aerial response when intensity spikes.
+    - Preserve a small reserve of idle (but ready) units so you can react instantly to unexpected ignitions. Never exhaust every slot unless absolutely necessary.
+    - Set up continuous monitoring for fires emerging outside current coverage. The moment a new fire appears beyond your protected zone, queue a reposition or deployment to cover it immediately.
+    
+    SMART DEPLOY COUNT CALCULATION:
+    ```
+    # Step 1: Calculate base need
+    uncovered_count = find_uncovered_fires().uncovered_count
+    building_threats = find_building_threats().uncovered_threats
+    
+    # Step 2: Account for idle units we can reposition
+    idle_count = find_idle_units().idle_count
+    fires_after_reposition = max(0, uncovered_count - idle_count)
+    
+    # Step 3: Calculate deploy count based on situation
+    IF building_threats > 0:
+        # Building emergency! Deploy enough to cover ALL building threats
+        deploy_count = max(building_threats, fires_after_reposition)
+    ELIF uncovered_count <= 2:
+        # Few fires - deploy just enough to cover them
+        deploy_count = fires_after_reposition
+    ELIF uncovered_count <= 5:
+        # Moderate fires - deploy to cover + 1 buffer
+        deploy_count = min(fires_after_reposition + 1, available_slots)
+    ELSE:
+        # Many fires - go aggressive and add extra units
+        deploy_count = fires_after_reposition + 2  # base coverage
+        if uncovered_count >= 6:
+            deploy_count += 1  # extra buffer for surging fires
+        if uncovered_count >= 8:
+            deploy_count = available_slots  # fill every slot for maximum suppression
+    
+    # Final: never exceed available slots
+    deploy_count = min(deploy_count, available_slots)
+    ```
+    
+    Strategy Selection:
+    - "balanced": Both reposition idle AND deploy new units
+    - "optimize_existing": Have idle units, reposition them first
+    - "deploy_new": No idle units, need to deploy new ones
+    - "monitor": ALL fires are covered - situation under control
+    - "helicopter_fallback": Fire persists despite truck coverage → USE HELICOPTER!
+    
+    🚁 **HELICOPTER FALLBACK STRATEGY:**
+    - If a fire has 2+ trucks nearby but is STILL not being extinguished → USE HELICOPTER!
+    - If fire is SURROUNDED by buildings/obstacles → Trucks can't reach center → USE HELICOPTER!
+    - A helicopter covering 2 tiles outward can reach fires in confined areas that trucks (1-tile reach) cannot
+    - Don't keep deploying trucks if they're not working - REMOVE ineffective trucks, DEPLOY helicopters!
+    - Use remove_unit(x, y) to remove ineffective truck, then deploy_unit("helicopter", x, y) at better position
+       - Free every idle unit slot ASAP: REMOVE anything that cannot be placed adjacent to an active fire.
+    
+    POSITIONING MANDATE (APPLIES TO ALL ACTIONS):
+    - Always choose the closest possible legal tile to the target fire, ideally immediately adjacent.
+    - Fires threatening buildings must have units hugging them before any non-building fires receive coverage.
+    
+    You MUST respond in valid JSON format only.
+  
+  output_format: |
+    {
+      "strategy": "optimize_existing" | "balanced" | "deploy_new" | "monitor" | "helicopter_fallback",
+      "reasoning": "Explain why this strategy - mention MCP tool results (idle units, uncovered fires)!",
+      "deploy_count": <number>,
+      "reposition_needed": true | false,
+      "units_to_reposition": [[source_x, source_y, unit_type], ...],
+      "priority_fire_indices": [0, 1, 2],
+      "use_helicopter": true | false,
+      "helicopter_reason": "Why helicopter is needed (e.g., fire surrounded, trucks ineffective)"
+    }
+
+execute:
+  system: |
+    You are a SMART fire rescue executor. Generate EFFICIENT deployment actions!
+    
+    🎯 WIN/LOSE CONDITIONS:
+    - ❌ LOSE: Building integrity drops below 50%
+    - ✅ WIN: ALL fires extinguished
+    
+    ⚠️ SMART EXECUTION PRINCIPLE:
+    - Follow the plan's deploy_count - don't exceed it unless building emergency!
+    - Prioritize building threats ALWAYS - these are non-negotiable
+    - Generate actions based on ACTUAL NEED, not maximum possible
+    - Quality over quantity - each action should have clear purpose
+    
+    📡 MCP TOOLS:
+    - `move_unit(source_x, source_y, target_x, target_y)` → Reposition unit
+    - `deploy_unit(unit_type, x, y)` → Deploy new unit
+    - `remove_unit(x, y)` → Remove a unit (frees deployment slot)
+    - `find_idle_units()` → Get idle unit positions
+    - `find_uncovered_fires()` → Get fires needing coverage
+    - `find_building_threats()` → Get building-adjacent fires (HIGHEST PRIORITY!)
+    
+    EXECUTION PRIORITIES (STRICT ORDER):
+    
+    1. **🏢 BUILDINGS FIRST - ALWAYS! (NON-NEGOTIABLE)**
+       - Use `find_building_threats()` to get fires near buildings
+       - These fires cause DIRECT building damage → GAME OVER risk!
+       - ALWAYS address building threats BEFORE other fires
+       - Use fire_truck for building threats (40% power = fastest!) and park them as close as legally possible (adjacent preferred)
+    
+    2. **🔄 REPOSITION IDLE UNITS FIRST**
+       - Use `find_idle_units()` to find wasted units
+       - Move idle units to building threats FIRST, then uncovered fires, always ending adjacent (1 cell away) to the target fire
+       - NEVER park a unit on a cell without a nearby fire; either move it or remove it
+       - If idle_units > uncovered_fires, immediately remove the excess idle units so the board only holds active responders
+       - This is FREE optimization - doesn't use deployment slots!
+    
+    3. **🚀 DEPLOY NEW UNITS (FOLLOW THE PLAN)**
+       - Deploy according to plan's deploy_count
+       - Prioritize: building threats > high intensity > uncovered fires
+       - Only exceed deploy_count if there are UNCOVERED building threats!
+       - When picking target tiles, always choose the closest available cell hugging the fire; do not leave gaps if adjacency is possible
+
+    🔧 EXECUTION SAFETY CHECKS:
+    - After every action, verify trucks remain spread across the map; if a region is underserved, schedule a reposition to rebalance coverage.
+    - Keep at least one deployment slot or removable unit available for helicopter insertion. Before issuing the last deployment, confirm no aerial response will be needed in the next tick.
+    - Maintain a micro-reserve of idle-but-ready units; mark them in reasoning so the planner knows they are intentional rapid-response assets.
+    - Continuously poll for fires outside the current coverage bubble. If any appear, immediately include a move or deploy action in the recommendation list to contain it.
+    
+    UNIT SELECTION:
+    - Fire Truck 🚒: Covers 1 tile outward from its center, Power 40% - USE FOR BUILDING THREATS & high intensity!
+    - Helicopter 🚁: Covers 2 tiles outward from its center, Power 25% - good for area coverage & distant fires
+    
+    🚁 **CRITICAL: WHEN TO USE HELICOPTER INSTEAD OF TRUCK:**
+    - Fire SURROUNDED by buildings/units → Trucks can't reach center! USE HELICOPTER!
+    - Fire PERSISTS despite multiple nearby trucks → Need helicopter's longer range!
+    - Fire in CONFINED area where trucks are blocked → Helicopter can reach from farther
+    - If same fire remains uncovered after 2+ ticks with trucks nearby → SWITCH TO HELICOPTER!
+    - Covering 2 tiles outward (helicopter) beats 1 tile (truck) = use heli when trucks can't reach!
+       - If a truck can't reach any fire, remove it immediately instead of leaving it idle on the board
+    
+    RECOMMENDATION COUNT LOGIC:
+    - recommendations = reposition_count + deploy_count
+    - If uncovered building threats exist: add extra for EACH uncovered threat
+    - Cap at 4 for UI display
+    
+    CRITICAL RULES:
+    1. Deploy 1-2 cells ADJACENT to fire (not ON the fire)
+    2. Cannot deploy ON buildings
+    3. Grid boundaries: x=[0, width-1], y=[0, height-1]
+    4. Each action should have a clear reason tied to a specific fire
+    5. Any idle unit left on an empty cell must be removed so the slot can be redeployed near fire, especially when idle > fires
+    
+    MCP TOOL USAGE:
+    ```python
+    # Move idle unit to cover building threat
+    move_unit(source_x=2, source_y=3, target_x=6, target_y=5)
+    
+    # Deploy fire truck near building threat (PRIORITY!)
+    deploy_unit(unit_type="fire_truck", x=5, y=3)
+    
+    # Remove ineffective truck, then deploy helicopter at better position
+    remove_unit(x=4, y=5)  # Remove truck that can't reach fire
+    deploy_unit(unit_type="helicopter", x=6, y=7)  # Deploy helicopter with better range
+    ```
+    
+    You MUST respond in valid JSON format only.
+  
+  output_format: |
+    {
+      "recommendations": [
+        {
+          "action": "move",
+          "unit_type": "fire_truck" | "helicopter",
+          "source": {"x": <current_x>, "y": <current_y>},
+          "target": {"x": <new_x>, "y": <new_y>},
+          "reason": "Moving idle unit to cover uncovered fire at (fx, fy)",
+          "mcp_call": "move_unit(source_x=<x>, source_y=<y>, target_x=<x>, target_y=<y>)"
+        },
+        {
+          "action": "deploy",
+          "unit_type": "fire_truck" | "helicopter",
+          "target": {"x": <number>, "y": <number>},
+          "reason": "Deploying new unit to cover fire at (fx, fy)",
+          "mcp_call": "deploy_unit(unit_type='<type>', x=<x>, y=<y>)"
+        },
+        {
+          "action": "remove",
+          "position": {"x": <number>, "y": <number>},
+          "unit_type": "fire_truck" | "helicopter",
+          "reason": "Removing ineffective truck to redeploy as helicopter elsewhere",
+          "mcp_call": "remove_unit(x=<x>, y=<y>)"
+        }
+      ],
+      "summary": "Brief tactical summary"
+    }
+
+summary:
+  system: |
+    You are a tactical mission summarizer. After the AI completes Assessment → Planning → Execution, create a concise Stage 4 summary for this cycle.
+    
+    Use the provided data:
+    - Tick number and mission status
+    - Stage 1 assessment metrics (fires, building threats, integrity, idle units)
+    - Stage 2 plan strategy and reasoning
+    - Stage 3 execution recommendations (moves/deployments/removals)
+    
+    Requirements:
+    1. Produce a single headline that captures the cycle outcome and threat posture.
+    2. List 2-4 key highlights (what worked, positive outcomes, metrics that improved).
+    3. List 1-3 risks or issues that still need attention.
+    4. Suggest 1-3 next-focus items for the upcoming cycle (actionable guidance).
+    5. Keep bullet text concise (max 18 words each).
+    6. Output strictly in English JSON.
+  output_format: |
+    {
+      "headline": "Concise summary of the cycle outcome",
+      "threat_level": "CRITICAL | HIGH | MODERATE | LOW",
+      "key_highlights": ["Highlight 1", "Highlight 2"],
+      "risks": ["Risk 1", "Risk 2"],
+      "next_focus": ["Action item 1", "Action item 2"]
+    }
+
+after_action:
+  system: |
+    You are the mission debrief analyst for the Fire-Rescue simulator.
+    Produce an AFTER-ACTION REPORT in English when the mission ends (victory or failure).
+    
+    Context provided:
+    - Outcome summary (success/fail, integrity, remaining fires, ticks)
+    - Stage 4 cycle summaries (headlines, highlights, risks, next focus)
+    - Mission status snapshot (units deployed, tick count, integrity metrics)
+    
+    Requirements:
+    1. Cite concrete evidence from the provided summaries and mission metrics for every bullet.
+    2. Summarize what went WELL (Strengths), what needs IMPROVEMENT, and ACTIONABLE follow-ups (Next Actions).
+    3. Each bullet should reference specific fires, units, or buildings when possible.
+    4. If any summary data is missing, acknowledge the gap but still deliver useful insights based on available data.
+    5. Respond entirely in English.
+  output_format: |
+    {
+      "summary": "One-sentence conclusion highlighting the decisive factor.",
+      "strengths": ["Strength 1", "Strength 2"],
+      "improvements": ["Improvement 1", "Improvement 2"],
+      "next_actions": ["Actionable recommendation 1", "Actionable recommendation 2"]
+    }
+
+# Model configuration
+# Using HuggingFace Inference Provider with openai/gpt-oss-120b
+# This model has top-notch tool calling capabilities
+model:
+  default: "openai/gpt-oss-120b"
+  # max_tokens for HuggingFace API (automatically converted from max_completion_tokens)
+  # Increased to 10000 to avoid truncation of complex JSON responses
+  max_completion_tokens: 10000
+  # Note: temperature not set - using model default

pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "fire-rescue-mcp"
+version = "0.2.0"
+description = "Fire rescue simulation with MCP integration and LLM advisor"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=1.0.0",
+    "openai>=1.0.0",
+    "pydantic>=2.0.0",
+    "python-dotenv>=1.0.0",
+    "gradio>=6.0.1",
+    "pyyaml>=6.0.0",
+]
+
+[project.scripts]
+fire-rescue-mcp = "fire_rescue_mcp.mcp_server:run_server"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["fire_rescue_mcp"]
+
+[tool.uv]
+dev-dependencies = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+]
+

requirements.txt

@@ -0,0 +1,8 @@
+# Fire-Rescue MCP Dependencies
+mcp>=1.0.0
+openai>=1.0.0
+pydantic>=2.0.0
+python-dotenv>=1.0.0
+gradio>=6.0.1
+pyyaml>=6.0.0
+

restart.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# Fire-Rescue App Restart Script
+
+echo "🔄 Stopping existing app..."
+pkill -f "python app.py" 2>/dev/null
+
+# Wait a moment for the process to terminate
+sleep 1
+
+echo "🚀 Starting Fire-Rescue App..."
+cd "$(dirname "$0")" && uv run --active python app.py
+

service.py

@@ -0,0 +1,1995 @@
+"""
+Fire-Rescue MCP - Simulation Service
+
+Background service that manages simulation loop and LLM advisor evaluations.
+Designed for integration with Gradio and HTTP API endpoints.
+"""
+
+import asyncio
+import concurrent.futures
+import html
+import json
+import threading
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Callable, Optional
+
+from agent import (
+    AdvisorAgent,
+    AdvisorResponse,
+    AfterActionReport,
+    AssessmentResult,
+    PlanResult,
+    CycleSummary,
+)
+from models import SimulationStatus, CellType
+from simulation import SimulationEngine
+
+
+def generate_emoji_map(engine: SimulationEngine) -> str:
+    """
+    Generate an emoji-based visualization of the current world state.
+    Matches Gradio UI: 🌲Forest 🏢Building 🔥Fire 💨Smoke 🚒Truck 🚁Heli
+    """
+    if engine.world is None:
+        return "No map available"
+    
+    world = engine.world
+    
+    # Create unit position lookup
+    unit_positions = {}
+    for unit in world.units:
+        key = (unit.x, unit.y)
+        if key not in unit_positions:
+            unit_positions[key] = []
+        unit_positions[key].append(unit.unit_type.value)
+    
+    # Build the map with coordinates
+    lines = []
+    
+    # Header with X coordinates
+    header = "   " + "".join(f"{x:2}" for x in range(world.width))
+    lines.append(header)
+    
+    for y in range(world.height):
+        row_chars = []
+        for x in range(world.width):
+            cell = world.grid[y][x]
+            pos = (x, y)
+            
+            # Priority: Units > Fire > Terrain
+            if pos in unit_positions:
+                if "fire_truck" in unit_positions[pos]:
+                    row_chars.append("🚒")
+                else:
+                    row_chars.append("🚁")
+            elif cell.fire_intensity > 0:
+                if cell.fire_intensity >= 0.1:
+                    row_chars.append("🔥")
+                else:
+                    row_chars.append("💨")
+            else:
+                if cell.cell_type == CellType.BUILDING:
+                    row_chars.append("🏢")
+                elif cell.cell_type == CellType.FOREST:
+                    row_chars.append("🌲")
+                else:
+                    row_chars.append("⬜")
+        
+        lines.append(f"{y:2} " + "".join(row_chars))
+    
+    return "\n".join(lines)
+
+
+@dataclass
+class LogEntry:
+    """A single log entry for the simulation."""
+    timestamp: str
+    tick: int
+    event_type: str  # "advisor", "deploy", "status", "error"
+    message: str
+    details: Optional[dict] = None
+    
+    def to_dict(self) -> dict:
+        return {
+            "timestamp": self.timestamp,
+            "tick": self.tick,
+            "event_type": self.event_type,
+            "message": self.message,
+            "details": self.details
+        }
+
+
+@dataclass 
+class SimulationService:
+    """
+    Service that manages the simulation lifecycle and LLM advisor.
+    
+    Provides:
+    - Background simulation loop
+    - Periodic LLM advisor evaluations  
+    - Thread-safe state access
+    - Event logging
+    """
+    
+    # Configuration
+    tick_interval: float = 1.0  # Seconds between simulation ticks (slower pace)
+    advisor_interval: int = 10  # Ticks between advisor evaluations
+    
+    # Internal state
+    engine: SimulationEngine = field(default_factory=SimulationEngine)
+    advisor: AdvisorAgent = field(default_factory=AdvisorAgent)
+    
+    # Runtime state
+    _running: bool = False
+    _thread: Optional[threading.Thread] = None
+    _lock: threading.Lock = field(default_factory=threading.Lock)
+    
+    # Logs and recommendations
+    _logs: list[LogEntry] = field(default_factory=list)
+    _latest_recommendations: Optional[AdvisorResponse] = None
+    _on_update: Optional[Callable] = None  # Callback for UI updates
+    
+    # Thinking state for UI display - Progressive stage rendering
+    _is_thinking: bool = False
+    _thinking_start_tick: int = 0
+    _current_stage: int = 0  # 0=idle, 1=assess, 2=plan, 3=execute, 4=summary, 5=complete
+    _current_cycle_messages: list = field(default_factory=list)  # Messages for current cycle
+    
+    # Advisor message history for chatbot display
+    _advisor_history: list[dict] = field(default_factory=list)
+    _cycle_summaries: list[dict] = field(default_factory=list)
+    _metrics_history: list[dict] = field(default_factory=list)
+    _threat_history: list[dict] = field(default_factory=list)
+    _action_history: list[dict] = field(default_factory=list)
+    _player_actions: list[dict] = field(default_factory=list)
+    
+    # Advisor call control
+    _advisor_running: bool = False  # Prevent concurrent advisor calls
+    advisor_timeout: float = 30.0   # Timeout for AI calls (seconds)
+    advisor_max_retries: int = 3    # Max retry attempts
+    
+    # Game result popup control
+    _result_shown: bool = False     # Track if game result popup has been shown
+    _result_dismissed: bool = False # Track if player dismissed the result popup
+    _result_report: Optional[AfterActionReport] = None
+    _result_report_status: str = "idle"
+    _result_report_error: str = ""
+    _last_result_signature: str = ""
+    _last_result_payload_signature: str = ""
+    
+    # Auto-execute AI recommendations
+    _auto_execute: bool = True      # Whether to automatically execute AI recommendations
+    _executed_recommendations: set = field(default_factory=set)  # Track executed recommendations
+    
+    # Simulation loop state (preserved across pause/resume)
+    _tick_count: int = 0            # Current tick count in simulation loop
+    _advisor_first_run: bool = True # Whether first advisor run has happened
+    
+    # Change tracking for UI optimization (prevents unnecessary re-renders)
+    _last_grid_hash: str = ""           # Hash of grid state (fires, units, buildings)
+    _last_advisor_signature: tuple = field(default_factory=tuple)  # Last advisor chat signature
+    _last_history_signature: tuple = field(default_factory=tuple)  # Last history chat signature
+    _last_event_log: str = ""           # Last event log text
+    _last_button_states: tuple = ()     # Last (start_enabled, pause_enabled)
+    _last_result_state: str = ""        # Last result popup state ("", "success", "fail")
+    
+    def __post_init__(self):
+        self._lock = threading.Lock()
+        self._logs = []
+        self._result_shown = False
+        self._result_dismissed = False
+        self._reset_after_action_report_locked()
+        self._is_thinking = False
+        self._current_stage = 0  # Progressive stage tracking
+        self._current_cycle_messages = []  # Current cycle messages
+        self._advisor_history = []
+        self._cycle_summaries = []
+        self._metrics_history = []
+        self._threat_history = []
+        self._action_history = []
+        self._player_actions = []
+        self._advisor_running = False
+        self._auto_execute = True
+        self._executed_recommendations = set()
+        self._tick_count = 0
+        self._advisor_first_run = True
+        # Change tracking initialization
+        self._last_grid_hash = ""
+        self._last_advisor_signature = ()
+        self._last_history_signature = ()
+        self._last_event_log = ""
+        self._last_button_states = (True, False)
+        self._last_result_state = ""
+    
+    def start(
+        self, 
+        seed: Optional[int] = None,
+        fire_count: int = 4,
+        fire_intensity: float = 0.6,
+        building_count: int = 16,
+        max_units: int = 10,
+        on_update: Optional[Callable] = None
+    ) -> dict:
+        """
+        Start a new simulation.
+        
+        Args:
+            seed: Random seed for reproducibility
+            fire_count: Number of initial fire points (1-25)
+            fire_intensity: Initial fire intensity (0.0-1.0)
+            building_count: Number of buildings to place (1-25)
+            on_update: Callback function called on state changes
+            
+        Returns:
+            Initial world state
+        """
+        # First stop any existing simulation
+        thread = None
+        with self._lock:
+            if self._running:
+                self._running = False
+                thread = self._thread
+                self._thread = None
+        
+        # Wait for thread outside lock
+        if thread and thread.is_alive():
+            thread.join(timeout=2.0)
+        
+        # Now start fresh with lock
+        with self._lock:
+            # Reset state
+            self._logs = []
+            self._latest_recommendations = None
+            self._advisor_history = []  # Clear advisor history
+            self._cycle_summaries = []  # Clear summaries
+            self._current_cycle_messages = []  # Clear current cycle
+            self._current_stage = 0  # Reset stage
+            self._is_thinking = False
+            self._result_shown = False  # Reset result popup flag
+            self._result_dismissed = False  # Reset dismissed flag
+            self._reset_after_action_report_locked()
+            self._executed_recommendations = set()  # Clear executed recommendations
+            self._tick_count = 0  # Reset tick count
+            self._advisor_first_run = True  # Reset first run flag
+            self._on_update = on_update
+            self._metrics_history = []
+            self._threat_history = []
+            self._action_history = []
+            self._player_actions = []
+            # Reset change tracking
+            self._last_grid_hash = ""
+            self._last_advisor_signature = ()
+            self._last_history_signature = ()
+            self._last_event_log = ""
+            self._last_button_states = (True, False)
+            self._last_result_state = ""
+            
+            # Initialize simulation
+            self.engine.reset(
+                seed=seed, 
+                fire_count=fire_count, 
+                fire_intensity=fire_intensity,
+                building_count=building_count,
+                max_units=max_units
+            )
+            self._record_tick_metrics_locked(self.engine.get_state())
+            
+            # Log start event
+            self._add_log("status", f"Simulation started: {fire_count} fires, {building_count} buildings, max {max_units} units")
+            
+            # Start background loop
+            self._running = True
+            self._thread = threading.Thread(target=self._simulation_loop, daemon=True)
+            self._thread.start()
+            
+            return self._compose_state_locked()
+    
+    def resume(self, on_update: Optional[Callable] = None) -> dict:
+        """
+        Resume a paused simulation.
+        
+        Returns:
+            Current world state, or error if no paused simulation exists
+        """
+        with self._lock:
+            # Check if there's a paused simulation to resume
+            if self.engine.world is None:
+                return {"status": "error", "message": "No simulation to resume"}
+            
+            # Check if already running
+            if self._running:
+                return {"status": "error", "message": "Simulation is already running"}
+            
+            # Check if simulation has ended
+            current_status = self.engine.world.status
+            if current_status in [SimulationStatus.SUCCESS, SimulationStatus.FAIL]:
+                return {"status": "error", "message": f"Simulation has ended ({current_status.value})"}
+            
+            self._on_update = on_update
+            
+            # Set status back to running
+            self.engine.world.status = SimulationStatus.RUNNING
+            
+            # Log resume event
+            self._add_log("status", "Simulation resumed")
+            
+            # Start background loop
+            self._running = True
+            self._thread = threading.Thread(target=self._simulation_loop, daemon=True)
+            self._thread.start()
+            
+            return self._compose_state_locked()
+    
+    def pause(self) -> dict:
+        """Pause the simulation (can be resumed later)."""
+        # First set flag and get thread reference (with lock)
+        with self._lock:
+            self._running = False
+            thread = self._thread
+            self._thread = None
+        
+        # Wait for thread outside lock to avoid deadlock
+        if thread and thread.is_alive():
+            thread.join(timeout=2.0)
+        
+        with self._lock:
+            self._add_log("status", "Simulation paused")
+            # Keep status as RUNNING so we know it can be resumed
+            # (IDLE means no game, SUCCESS/FAIL means game ended)
+            if self.engine.world:
+                return self._compose_state_locked()
+            return {"status": "idle", "after_action_report": self._get_after_action_report_payload_locked()}
+    
+    def is_paused(self) -> bool:
+        """Check if simulation is paused (has world but not running)."""
+        with self._lock:
+            if self.engine.world is None:
+                return False
+            # Paused = has world, not running, and status is still RUNNING
+            return (
+                not self._running 
+                and self.engine.world.status == SimulationStatus.RUNNING
+            )
+    
+    def _stop_internal(self):
+        """Internal stop - sets flag only (must be called with lock held)."""
+        self._running = False
+    
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        fire_count: int = 4,
+        fire_intensity: float = 0.6,
+        building_count: int = 16,
+        max_units: int = 10
+    ) -> dict:
+        """Reset simulation without starting the loop."""
+        # First stop any running simulation
+        thread = None
+        with self._lock:
+            if self._running:
+                self._running = False
+                thread = self._thread
+                self._thread = None
+        
+        # Wait for thread outside lock to avoid deadlock
+        if thread and thread.is_alive():
+            thread.join(timeout=2.0)
+        
+        # Now reset with lock
+        with self._lock:
+            self._logs = []
+            self._latest_recommendations = None
+            self._advisor_history = []  # Clear advisor history
+            self._cycle_summaries = []  # Clear summaries
+            self._current_cycle_messages = []  # Clear current cycle
+            self._current_stage = 0  # Reset stage
+            self._is_thinking = False
+            self._result_shown = False  # Reset result popup flag
+            self._result_dismissed = False  # Reset dismissed flag
+            self._reset_after_action_report_locked()
+            self._executed_recommendations = set()  # Clear executed recommendations
+            self._tick_count = 0  # Reset tick count
+            self._advisor_first_run = True  # Reset first run flag
+            self._metrics_history = []
+            self._threat_history = []
+            self._action_history = []
+            # Reset change tracking
+            self._last_grid_hash = ""
+            self._last_advisor_signature = ()
+            self._last_history_signature = ()
+            self._last_event_log = ""
+            self._last_button_states = (True, False)
+            self._last_result_state = ""
+            
+            self.engine.reset(
+                seed=seed, 
+                fire_count=fire_count, 
+                fire_intensity=fire_intensity,
+                building_count=building_count,
+                max_units=max_units
+            )
+            self._record_tick_metrics_locked(self.engine.get_state())
+            self._add_log("status", f"Simulation reset: {fire_count} fires, {building_count} buildings, max {max_units} units")
+            
+            return self._compose_state_locked()
+    
+    def get_state(self) -> dict:
+        """Get current world state (thread-safe)."""
+        with self._lock:
+            if self.engine.world is None:
+                return {
+                    "status": "idle",
+                    "message": "No simulation running",
+                    "after_action_report": self._get_after_action_report_payload_locked(),
+                }
+            return self._compose_state_locked()
+
+    def _compose_state_locked(self) -> dict:
+        """Attach after-action report payload to the current engine state."""
+        state = self.engine.get_state()
+        state["after_action_report"] = self._get_after_action_report_payload_locked()
+        return state
+
+    def _reset_after_action_report_locked(self):
+        """Clear cached after-action report data."""
+        self._result_report = None
+        self._result_report_status = "idle"
+        self._result_report_error = ""
+        self._last_result_signature = ""
+        self._last_result_payload_signature = ""
+
+    def _record_cycle_summary(self, tick: int, cycle_summary: CycleSummary, state_snapshot: Optional[dict] = None):
+        """Store Stage 4 summary for each advisor cycle, including metrics for charts."""
+        state_snapshot = state_snapshot or {}
+        metrics = {
+            "tick": tick,
+            "fires": len(state_snapshot.get("fires", [])),
+            "units": len(state_snapshot.get("units", [])),
+            "max_units": state_snapshot.get("max_units", 0),
+            "building_integrity": state_snapshot.get("building_integrity", 1.0),
+        }
+        entry = {
+            "tick": tick,
+            "headline": cycle_summary.headline,
+            "threat_level": cycle_summary.threat_level,
+            "key_highlights": cycle_summary.key_highlights,
+            "risks": cycle_summary.risks,
+            "next_focus": cycle_summary.next_focus,
+            "metrics": metrics,
+        }
+        self._cycle_summaries.append(entry)
+        if len(self._cycle_summaries) > 30:
+            self._cycle_summaries = self._cycle_summaries[-30:]
+        threat_value_map = {"CRITICAL": 4, "HIGH": 3, "MODERATE": 2, "LOW": 1}
+        value = threat_value_map.get(cycle_summary.threat_level.upper(), 0) if cycle_summary.threat_level else 0
+        self._threat_history.append({
+            "tick": tick,
+            "threat_level": cycle_summary.threat_level,
+            "value": value,
+        })
+        if len(self._threat_history) > 120:
+            self._threat_history = self._threat_history[-120:]
+
+    def _record_tick_metrics_locked(self, state: Optional[dict]):
+        """Capture per-tick metrics for after-action chart visualization."""
+        if not state:
+            return
+        entry = {
+            "tick": state.get("tick", 0),
+            "fires": len(state.get("fires", [])),
+            "units": len(state.get("units", [])),
+            "max_units": state.get("max_units") or getattr(self.engine.world, "max_units", 0) if self.engine.world else 0,
+            "building_integrity": state.get("building_integrity", 1.0),
+        }
+        self._metrics_history.append(entry)
+        if len(self._metrics_history) > 600:
+            self._metrics_history = self._metrics_history[-600:]
+
+    def _record_action_breakdown(self, tick: int, deploy: int, move: int, replace: int):
+        """Track how many actions the AI recommended per tick."""
+        self._action_history.append({
+            "tick": tick,
+            "deploy": deploy,
+            "move": move,
+            "replace": replace,
+        })
+        if len(self._action_history) > 200:
+            self._action_history = self._action_history[-200:]
+
+    def _record_player_action(self, action: str, description: str, metadata: Optional[dict] = None):
+        """Track player-driven interventions (manual deploy/remove/fire)."""
+        if metadata is None:
+            metadata = {}
+        tick = 0
+        if self.engine and self.engine.world:
+            tick = getattr(self.engine.world, "tick", 0)
+        else:
+            tick = self._tick_count
+        entry = {
+            "tick": tick,
+            "timestamp": datetime.utcnow().isoformat(),
+            "action": action,
+            "description": description,
+            "details": dict(metadata),
+        }
+        self._player_actions.append(entry)
+        if len(self._player_actions) > 200:
+            self._player_actions = self._player_actions[-200:]
+
+    def _build_player_action_context(self) -> dict:
+        """Summarize player-driven interventions for after-action reporting."""
+        actions = list(self._player_actions)
+        counts = {"deploy_unit": 0, "remove_unit": 0, "add_fire": 0}
+        action_meta = {
+            "deploy_unit": ("🚒", "Deployed units"),
+            "remove_unit": ("♻️", "Removed units"),
+            "add_fire": ("🔥", "Ignited fires"),
+        }
+        for entry in actions:
+            action_type = entry.get("action")
+            if action_type in counts:
+                counts[action_type] += 1
+        total = sum(counts.values())
+        if total:
+            parts = [f"Player executed {total} manual action(s)."]
+            if counts["deploy_unit"]:
+                parts.append(f"🚒 Deploy: {counts['deploy_unit']} time(s)")
+            if counts["remove_unit"]:
+                parts.append(f"♻️ Remove: {counts['remove_unit']} time(s)")
+            if counts["add_fire"]:
+                parts.append(f"🔥 Ignite: {counts['add_fire']} time(s)")
+            summary = " ".join(parts)
+        else:
+            summary = "Player has not manually deployed, removed, or ignited anything this run."
+        recent_entries = list(reversed(actions[-6:]))
+        recent = [
+            {
+                "tick": entry.get("tick", 0),
+                "description": entry.get("description", ""),
+                "action": entry.get("action"),
+                "timestamp": entry.get("timestamp"),
+            }
+            for entry in recent_entries
+        ]
+        markdown_lines = [summary]
+        if recent:
+            markdown_lines.append("")
+            markdown_lines.append("**Recent player actions**")
+            for entry in recent:
+                icon = action_meta.get(entry["action"], ("📍", ""))[0]
+                markdown_lines.append(f"- Tick {entry['tick']} · {icon} {entry['description']}")
+        markdown = "\n".join(markdown_lines).strip()
+        return {
+            "total": total,
+            "counts": counts,
+            "recent": recent,
+            "summary": summary,
+            "markdown": markdown,
+        }
+
+    def _get_after_action_report_payload_locked(self) -> dict:
+        """Serialize after-action report state for UI consumption."""
+        payload: dict = {"status": self._result_report_status}
+        if self._result_report_status == "ready" and self._result_report:
+            payload["report"] = self._result_report.to_dict()
+        elif self._result_report_status == "error":
+            payload["error"] = self._result_report_error or "Unknown error"
+        return payload
+    
+    def should_show_result(self) -> tuple[bool, bool]:
+        """
+        Check if game result should be shown.
+        
+        Returns:
+            tuple of (should_show, is_first_time)
+            - should_show: True if popup should be displayed
+            - is_first_time: True if this is the first time showing (needs render)
+        """
+        with self._lock:
+            # Don't show if player already dismissed it
+            if self._result_dismissed:
+                return (False, False)
+            
+            state = self.engine.get_state() if self.engine.world else {"status": "idle"}
+            status = state.get("status", "idle")
+            
+            if status in ["success", "fail"]:
+                # Check if this is the first time showing
+                is_first_time = not self._result_shown
+                if is_first_time:
+                    self._result_shown = True
+                return (True, is_first_time)
+            
+            return (False, False)
+    
+    def dismiss_result(self):
+        """Dismiss the game result popup (called when player clicks it)."""
+        with self._lock:
+            self._result_dismissed = True
+    
+    def get_result_status(self) -> str:
+        """Get current result status."""
+        with self._lock:
+            if self.engine.world is None:
+                return "idle"
+            state = self.engine.get_state()
+            return state.get("status", "idle")
+
+    def _prepare_after_action_context_locked(self, outcome: str, state: dict) -> Optional[dict]:
+        """Build context for after-action report generation."""
+        signature = f"{outcome}_{state.get('tick', 0)}_{len(self._logs)}"
+        if signature == self._last_result_signature:
+            return None
+        context = self._build_after_action_context_locked(outcome, state)
+        self._result_report_status = "pending"
+        self._result_report = None
+        self._result_report_error = ""
+        self._last_result_signature = signature
+        self._last_result_payload_signature = ""
+        return context
+
+    def _build_after_action_context_locked(self, outcome: str, state: dict) -> dict:
+        """Assemble transcripts and metrics for the after-action LLM call."""
+        outcome_label = "Victory" if outcome == "success" else "Defeat"
+        fires_remaining = len(state.get("fires", []))
+        units_active = len(state.get("units", []))
+        building_integrity = state.get("building_integrity", 1.0)
+        integrity_percent = f"{building_integrity:.0%}" if isinstance(building_integrity, (int, float)) else "N/A"
+
+        stage_messages = self._current_cycle_messages[:] if self._current_cycle_messages else self._advisor_history[-3:]
+        transcripts = {"assessment_md": "", "planning_md": "", "execution_md": ""}
+        for msg in stage_messages:
+            content = msg.get("content", "")
+            if not content:
+                continue
+            lowered = content.lower()
+            if "stage 1" in lowered and not transcripts["assessment_md"]:
+                transcripts["assessment_md"] = content
+            elif "stage 2" in lowered and not transcripts["planning_md"]:
+                transcripts["planning_md"] = content
+            elif "stage 3" in lowered and not transcripts["execution_md"]:
+                transcripts["execution_md"] = content
+
+        summary_text = (
+            f"Tick {state.get('tick', 0)} · Fires {fires_remaining} · "
+            f"Units {units_active}/{state.get('max_units', 0)} · Building Integrity {integrity_percent}"
+        )
+
+        if self._metrics_history:
+            chart_points = [dict(point) for point in self._metrics_history]
+        else:
+            chart_points = []
+            for entry in self._cycle_summaries:
+                metrics = entry.get("metrics") or {}
+                if not metrics:
+                    continue
+                chart_points.append({
+                    "tick": metrics.get("tick", entry.get("tick")),
+                    "fires": metrics.get("fires", 0),
+                    "units": metrics.get("units", 0),
+                    "max_units": metrics.get("max_units", state.get("max_units", 0)),
+                    "building_integrity": metrics.get("building_integrity", building_integrity),
+                })
+
+        context = {
+            "outcome": outcome,
+            "outcome_label": outcome_label,
+            "tick": state.get("tick", 0),
+            "fires_remaining": fires_remaining,
+            "units_active": units_active,
+            "building_integrity_percent": integrity_percent,
+            "summary_text": summary_text,
+            "state_snapshot": {
+                "tick": state.get("tick", 0),
+                "status": state.get("status", ""),
+                "building_integrity": building_integrity,
+                "max_units": state.get("max_units", 0),
+            },
+            "cycle_summaries": list(self._cycle_summaries),
+            "chart_points": chart_points,
+            "threat_history": list(self._threat_history),
+            "action_history": list(self._action_history),
+        }
+        player_actions_context = self._build_player_action_context()
+        context.update(transcripts)
+        context["player_actions_context"] = player_actions_context
+        context["player_actions_md"] = player_actions_context.get("markdown", "")
+        return context
+
+    def _launch_after_action_report(self, context: dict):
+        """Run after-action report generation in the background."""
+
+        def _runner():
+            try:
+                report = self.advisor.generate_after_action_report(context)
+            except Exception as exc:
+                with self._lock:
+                    self._result_report = None
+                    self._result_report_status = "error"
+                    self._result_report_error = str(exc)
+                    self._last_result_payload_signature = ""
+                return
+
+            with self._lock:
+                if report and not report.error:
+                    self._result_report = report
+                    self._result_report_status = "ready"
+                    self._result_report_error = ""
+                else:
+                    self._result_report = report
+                    self._result_report_status = "error"
+                    self._result_report_error = (report.error if report else "Unknown error")
+                self._last_result_payload_signature = ""
+
+        threading.Thread(target=_runner, daemon=True).start()
+    
+    def get_recommendations(self) -> Optional[dict]:
+        """Get latest advisor recommendations."""
+        with self._lock:
+            if self._latest_recommendations:
+                return self._latest_recommendations.to_dict()
+            return None
+    
+    def get_logs(self, limit: int = 50) -> list[dict]:
+        """Get recent log entries."""
+        with self._lock:
+            return [log.to_dict() for log in self._logs[-limit:]]
+    
+    def get_logs_text(self, limit: int = 20) -> str:
+        """Get all logs as formatted text for display."""
+        with self._lock:
+            lines = []
+            for log in self._logs[-limit:]:
+                if log.event_type == "advisor":
+                    lines.append(f"[Tick {log.tick}] 🤖 AI: {log.message}")
+                    if log.details and log.details.get("recommendations"):
+                        for rec in log.details["recommendations"]:
+                            target = rec.get("target", {})
+                            lines.append(
+                                f"  → {rec.get('suggested_unit_type')} at "
+                                f"({target.get('x')}, {target.get('y')}): {rec.get('reason', '')[:50]}"
+                            )
+                elif log.event_type == "deploy":
+                    lines.append(f"[Tick {log.tick}] 🚒 Deploy: {log.message}")
+                elif log.event_type == "status":
+                    lines.append(f"[{log.timestamp}] ℹ️ {log.message}")
+                elif log.event_type == "error":
+                    lines.append(f"[{log.timestamp}] ⚠️ Error: {log.message}")
+                else:
+                    lines.append(f"[Tick {log.tick}] {log.message}")
+            return "\n".join(lines)
+    
+    def get_advisor_text(self, limit: int = 5) -> str:
+        """Get AI advisor display with rich reasoning (legacy text format)."""
+        messages = self.get_advisor_messages(limit)
+        if not messages:
+            return "🤖 AI Advisor standing by..."
+        return messages[-1].get("content", "") if messages else ""
+    
+    def _wrap_analysis_block(
+        self,
+        content: str,
+        default_summary: str = "AI Analysis",
+        *,
+        split_stage_sections: bool = False,
+        open_by_default: bool = False,
+    ) -> str:
+        """Wrap advisor markdown in a collapsible details block."""
+        if not content:
+            return content
+        
+        lines = content.splitlines()
+        summary = default_summary
+        first_value_line = ""
+        auto_summary = default_summary == "AI Analysis"
+        
+        for line in lines:
+            stripped = line.strip()
+            if not stripped:
+                continue
+            if not first_value_line:
+                first_value_line = stripped
+            if auto_summary and stripped.lower().startswith("###"):
+                summary = stripped.lstrip("# ").strip()
+                break
+        
+        summary = html.escape(summary or default_summary)
+        
+        if auto_summary and first_value_line and first_value_line.lower().startswith("###"):
+            body_lines = lines[1:]
+        else:
+            body_lines = lines
+        body = "\n".join(body_lines).strip()
+        
+        if split_stage_sections:
+            rendered = self._render_stage_sections(body, open_by_default)
+            if rendered:
+                body = rendered
+        
+        open_attr = " open" if open_by_default else ""
+        return (
+            f"<details class=\"analysis-entry\"{open_attr}>"
+            f"<summary>{summary}</summary>\n"
+            f"{body}\n"
+            "</details>"
+        )
+
+    def _render_stage_sections(self, body: str, force_open: bool = False) -> str | None:
+        """Split a multi-stage markdown block into per-stage collapsible sections."""
+        lines = body.splitlines()
+        sections: list[tuple[str, list[str]]] = []
+        current_title: str | None = None
+        current_lines: list[str] = []
+        
+        def _flush():
+            nonlocal current_title, current_lines
+            if current_title is None:
+                return
+            sections.append((current_title, list(current_lines)))
+            current_title = None
+            current_lines = []
+        
+        for line in lines:
+            stripped = line.strip()
+            if stripped.startswith("### "):
+                _flush()
+                current_title = stripped.lstrip("# ").strip()
+                current_lines = []
+                continue
+            if current_title is None:
+                # Ignore content that appears before the first stage header
+                if not stripped:
+                    continue
+                current_title = "Details"
+            current_lines.append(line)
+        
+        _flush()
+        
+        if not sections:
+            return None
+        
+        rendered_sections: list[str] = []
+        for title, section_lines in sections:
+            section_body = "\n".join(section_lines).rstrip()
+            if section_body.endswith("---"):
+                section_body = section_body[:-3].rstrip()
+            section_body = section_body.strip() or "_No details available._"
+            open_attr = " open" if force_open else ""
+            rendered_sections.append(
+                f"<details class=\"analysis-stage\"{open_attr}>"
+                f"<summary>{html.escape(title)}</summary>\n"
+                f"{section_body}\n"
+                "</details>"
+            )
+        
+        return "\n\n".join(rendered_sections)
+    
+    def _build_advisor_messages_locked(self) -> list[dict]:
+        """Assemble advisor messages. Caller must hold _lock."""
+        messages: list[dict] = []
+        
+        # Show welcome message if no activity yet
+        if (
+            not self._current_cycle_messages
+            and not self._advisor_history
+            and not self._is_thinking
+        ):
+            messages.append({
+                "role": "assistant", 
+                "content": "👋 Hello! I'm your AI Tactical Advisor.\n\nStart the simulation and I'll analyze the fire situation, describe my reasoning, and recommend tactical deployments.\n\nWatch me think, plan, and execute!"
+            })
+            return messages
+        
+        current_entry = self._build_current_cycle_entry_locked()
+        if current_entry:
+            messages.append(current_entry)
+        
+        return messages
+
+    def _build_current_cycle_entry_locked(self) -> Optional[dict]:
+        """Render the active cycle as a single ⏱️ Tick block (even while streaming)."""
+        cycle_sections: list[str] = []
+        stage_placeholders = {
+            1: ("📊 Stage 1 · Assessment", "Querying MCP tools and analyzing the situation..."),
+            2: ("🎯 Stage 2 · Planning", "Formulating tactical strategy..."),
+            3: ("⚡ Stage 3 · Execution", "Generating deployment commands via MCP..."),
+            4: ("🧭 Stage 4 · Summary", "Consolidating cycle insights..."),
+        }
+        current_stage_title: Optional[str] = None
+        for msg in self._current_cycle_messages:
+            content = msg.get("content", "")
+            if content:
+                cycle_sections.append(content)
+        
+        # Add placeholder for the stage currently in progress
+        if self._is_thinking:
+            tick = self._thinking_start_tick
+            if tick is None and self.engine.world:
+                tick = self.engine.get_state().get("tick", 0)
+            title, desc = stage_placeholders.get(
+                self._current_stage,
+                ("🤖 AI Thinking", "Processing...")
+            )
+            current_stage_title = title
+            cycle_sections.append(
+                f"### {title} `[Tick {tick if tick is not None else '?'}]`\n\n{desc}"
+            )
+        
+        if not cycle_sections:
+            return None
+        
+        tick_label = self._thinking_start_tick
+        if tick_label is None and self.engine.world:
+            tick_label = self.engine.get_state().get("tick", 0)
+        summary = f"⏱️ Tick {tick_label if tick_label is not None else '?'}"
+        if self._is_thinking and current_stage_title:
+            summary = f"{summary} · {current_stage_title} ⏳"
+        body = "\n\n".join(cycle_sections).strip()
+        open_by_default = tick_label == 0
+        
+        return {
+            "role": "assistant",
+            "content": self._wrap_analysis_block(
+                body,
+                summary,
+                split_stage_sections=True,
+                open_by_default=open_by_default,
+            ),
+            "metadata": {"title": summary, "status": "pending" if self._is_thinking else "done"},
+        }
+    
+    def get_advisor_messages(self) -> list:
+        """Get current AI advisor cycle messages (progressive stage display)."""
+        with self._lock:
+            return self._build_advisor_messages_locked()
+    
+    def _build_history_messages_locked(self) -> list[dict]:
+        """Aggregate advisor history into per-tick chatbot messages."""
+        if not self._advisor_history:
+            return []
+        
+        history_messages: list[dict] = []
+        buffer: list[str] = []
+        tick_num = "?"
+        
+        def flush_cycle():
+            nonlocal buffer, tick_num
+            cycle_text = "\n\n".join(buffer).strip()
+            if cycle_text:
+                history_messages.append({
+                    "role": "assistant",
+                    "content": self._wrap_analysis_block(
+                        cycle_text,
+                        f"⏱️ Tick {tick_num}",
+                        split_stage_sections=True,
+                        open_by_default=(str(tick_num).strip() == "0"),
+                    ),
+                    "metadata": {"title": f"⏱️ Tick {tick_num}", "status": "done"},
+                })
+            buffer = []
+            tick_num = "?"
+        
+        for msg in self._advisor_history:
+            content = msg.get("content", "")
+            if not content:
+                continue
+            buffer.append(content)
+            if tick_num == "?" and "[Tick " in content:
+                start = content.find("[Tick ") + 6
+                end = content.find("]", start)
+                if end > start:
+                    tick_num = content[start:end]
+            
+            lowered = content.lower()
+            if "stage 4" in lowered:
+                flush_cycle()
+        
+        if buffer:
+            flush_cycle()
+        
+        return history_messages if history_messages else [{
+            "role": "assistant",
+            "content": self._wrap_analysis_block("No previous analysis cycles yet...", "📜 History"),
+            "metadata": {"title": "📜 History", "status": "done"},
+        }]
+    
+    def get_advisor_markdown(self) -> str:
+        """Get the latest AI advisor cycle as formatted plain text."""
+        with self._lock:
+            return self._get_advisor_markdown_internal()
+    
+    def get_advisor_history_chat_messages(self) -> list[dict]:
+        """Get advisor history formatted for chatbot display."""
+        with self._lock:
+            return self._build_history_messages_locked()
+    
+    # =========================================================================
+    # Change Tracking for UI Optimization (Dual Timer Architecture)
+    # =========================================================================
+    
+    def get_game_changes(self) -> dict:
+        """
+        Check game-critical components for changes (called by game_timer every 1s).
+        
+        Returns a dict with:
+        - state: current simulation state
+        - grid_changed: bool - whether fire/unit positions changed
+        - status_changed: bool - whether status bar should update
+        """
+        import hashlib
+        
+        with self._lock:
+            if self.engine.world:
+                state = self._compose_state_locked()
+            else:
+                state = {
+                    "status": "idle",
+                    "after_action_report": self._get_after_action_report_payload_locked(),
+                }
+            result = {"state": state}
+            
+            # Grid state - hash fires, units, buildings positions
+            grid_data = {
+                "fires": sorted([(f["x"], f["y"], round(f["intensity"], 2)) for f in state.get("fires", [])]),
+                "units": sorted([(u["x"], u["y"], u["type"]) for u in state.get("units", [])]),
+                "buildings": sorted([(b["x"], b["y"]) for b in state.get("buildings", [])])
+            }
+            current_grid_hash = hashlib.md5(json.dumps(grid_data, sort_keys=True).encode()).hexdigest()
+            result["grid_changed"] = current_grid_hash != self._last_grid_hash
+            if result["grid_changed"]:
+                self._last_grid_hash = current_grid_hash
+            
+            # Status bar - only update when simulation is actively running
+            status = state.get("status", "idle")
+            is_running = self._running
+            result["status_changed"] = is_running and status == "running"
+            
+            return result
+    
+    def get_ui_changes(self) -> dict:
+        """
+        Check UI panel components for changes (called by ui_timer every 2s).
+        
+        Returns a dict with:
+        - state: current simulation state
+        - advisor_changed: bool - whether advisor messages changed
+        - advisor_messages: list[dict] | None - new content if changed
+        - history_changed: bool - whether history HTML changed
+        - advisor_history: str or None - new content if changed
+        - event_log_changed: bool - whether event log changed
+        - event_log: str or None - new content if changed
+        - buttons_changed: bool - whether button states changed
+        - button_states: tuple (start_enabled, pause_enabled)
+        - result_changed: bool - whether result popup changed
+        - result_state: str - current result state
+        """
+        with self._lock:
+            if self.engine.world:
+                state = self._compose_state_locked()
+            else:
+                state = {
+                    "status": "idle",
+                    "after_action_report": self._get_after_action_report_payload_locked(),
+                }
+            result = {"state": state}
+            
+            # 1. Advisor chat messages - only update when AI is thinking or content changed
+            advisor_messages = self._get_advisor_chat_messages_internal()
+            signature = tuple(msg.get("content", "") for msg in advisor_messages)
+            content_changed = signature != self._last_advisor_signature
+            result["advisor_changed"] = self._is_thinking or content_changed
+            result["advisor_messages"] = advisor_messages if result["advisor_changed"] else None
+            if content_changed:
+                self._last_advisor_signature = signature
+            
+            # 2. Advisor history messages - only update when content actually changed
+            history_messages = self._build_history_messages_locked()
+            history_signature = tuple(msg.get("content", "") for msg in history_messages)
+            result["history_changed"] = history_signature != self._last_history_signature
+            result["advisor_history"] = history_messages if result["history_changed"] else None
+            if result["history_changed"]:
+                self._last_history_signature = history_signature
+            
+            # 3. Event log
+            event_log = self._get_event_log_internal()
+            result["event_log_changed"] = event_log != self._last_event_log
+            result["event_log"] = event_log if result["event_log_changed"] else None
+            if result["event_log_changed"]:
+                self._last_event_log = event_log
+            
+            # 4. Button states
+            status = state.get("status", "idle")
+            is_running = self._running
+            is_paused = (
+                self.engine.world is not None
+                and not self._running
+                and self.engine.world.status == SimulationStatus.RUNNING
+            )
+            start_enabled = is_paused or (not is_running and status in ["idle", "success", "fail"])
+            pause_enabled = is_running and status == "running"
+            current_buttons = (start_enabled, pause_enabled)
+            result["buttons_changed"] = current_buttons != self._last_button_states
+            result["button_states"] = current_buttons
+            if result["buttons_changed"]:
+                self._last_button_states = current_buttons
+            
+            # 5. Result popup state
+            if self._result_dismissed:
+                current_result = ""
+            elif status in ["success", "fail"]:
+                current_result = status
+            else:
+                current_result = ""
+            result["result_changed"] = current_result != self._last_result_state
+            result["result_state"] = current_result
+            if result["result_changed"]:
+                self._last_result_state = current_result
+
+            report_payload = self._get_after_action_report_payload_locked()
+            overlay_payload = {
+                "outcome": current_result,
+                "after_action": report_payload,
+            }
+            payload_signature = json.dumps(overlay_payload, sort_keys=True)
+            if payload_signature != self._last_result_payload_signature:
+                result["result_changed"] = True
+                self._last_result_payload_signature = payload_signature
+            result["result_payload"] = overlay_payload
+            
+            return result
+    
+    def get_changed_components(self) -> dict:
+        """
+        Legacy function - combines game and UI changes.
+        Used by button click handlers for full refresh.
+        """
+        game = self.get_game_changes()
+        ui = self.get_ui_changes()
+        
+        # Merge results
+        return {
+            "state": game["state"],
+            "grid_changed": game["grid_changed"],
+            "status_changed": game["status_changed"],
+            "advisor_changed": ui["advisor_changed"],
+            "advisor_messages": ui["advisor_messages"],
+            "history_changed": ui["history_changed"],
+            "advisor_history": ui["advisor_history"],
+            "event_log_changed": ui["event_log_changed"],
+            "event_log": ui["event_log"],
+            "buttons_changed": ui["buttons_changed"],
+            "button_states": ui["button_states"],
+            "result_changed": ui["result_changed"],
+            "result_state": ui["result_state"],
+            "result_payload": ui.get("result_payload"),
+        }
+    
+    def _get_advisor_markdown_internal(self) -> str:
+        """Internal helper to flatten advisor messages into text."""
+        messages = self._build_advisor_messages_locked()
+        parts = [msg.get("content", "") for msg in messages if msg.get("content")]
+        return "\n\n---\n\n".join(parts) if parts else "Waiting for analysis..."
+    
+    def _get_advisor_chat_messages_internal(self) -> list[dict]:
+        """Internal helper to normalize advisor messages for Chatbot display."""
+        messages = self._build_advisor_messages_locked()
+        chat_messages: list[dict] = []
+        for msg in messages:
+            role = msg.get("role", "assistant")
+            if role not in ("user", "assistant", "system"):
+                role = "assistant"
+            chat_msg = {
+                "role": role,
+                "content": msg.get("content", ""),
+            }
+            metadata = msg.get("metadata")
+            if metadata:
+                chat_msg["metadata"] = metadata
+            options = msg.get("options")
+            if options:
+                chat_msg["options"] = options
+            chat_messages.append(chat_msg)
+        return chat_messages
+    
+    def get_advisor_chat_messages(self) -> list[dict]:
+        """Public helper for UI components that expect message dictionaries."""
+        with self._lock:
+            return self._get_advisor_chat_messages_internal()
+    
+    def _get_event_log_internal(self, limit: int = 15) -> str:
+        """Internal method to get event log (must be called with lock held)."""
+        lines = []
+        event_logs = [log for log in self._logs if log.event_type != "advisor"]
+        for log in event_logs[-limit:]:
+            if log.event_type == "deploy":
+                lines.append(f"[Tick {log.tick}] 🚒 {log.message}")
+            elif log.event_type == "status":
+                lines.append(f"[{log.timestamp}] ℹ️ {log.message}")
+            elif log.event_type == "error":
+                lines.append(f"[{log.timestamp}] ⚠️ {log.message}")
+            else:
+                lines.append(f"[Tick {log.tick}] {log.message}")
+        return "\n".join(lines) if lines else "No events yet..."
+    
+    def get_event_log_text(self, limit: int = 15) -> str:
+        """Get event logs (deploy, status, error) without AI advisor."""
+        with self._lock:
+            lines = []
+            event_logs = [log for log in self._logs if log.event_type != "advisor"]
+            for log in event_logs[-limit:]:
+                if log.event_type == "deploy":
+                    lines.append(f"[Tick {log.tick}] 🚒 {log.message}")
+                elif log.event_type == "status":
+                    lines.append(f"[{log.timestamp}] ℹ️ {log.message}")
+                elif log.event_type == "error":
+                    lines.append(f"[{log.timestamp}] ⚠️ {log.message}")
+                else:
+                    lines.append(f"[Tick {log.tick}] {log.message}")
+            return "\n".join(lines) if lines else "No events yet..."
+    
+    def get_deploy_log_text(self, limit: int = 10) -> str:
+        """Get deploy-related logs only (deploy success and errors)."""
+        with self._lock:
+            lines = []
+            deploy_logs = [log for log in self._logs if log.event_type in ["deploy", "error"]]
+            for log in deploy_logs[-limit:]:
+                if log.event_type == "deploy":
+                    lines.append(f"[Tick {log.tick}] ✅ {log.message}")
+                elif log.event_type == "error":
+                    lines.append(f"[Tick {log.tick}] ❌ {log.message}")
+            return "\n".join(lines) if lines else "Click on a cell to deploy units..."
+    
+    def deploy_unit(self, unit_type: str, x: int, y: int, source: str = "player") -> dict:
+        """Deploy a unit (thread-safe)."""
+        with self._lock:
+            result = self.engine.deploy_unit(unit_type, x, y, source)
+            
+            if result.get("status") == "ok":
+                self._add_log(
+                    "deploy",
+                    f"Deployed {unit_type} at ({x}, {y})",
+                    {"unit": result.get("unit"), "source": source}
+                )
+                if str(source or "").startswith("player"):
+                    unit_label = "fire truck" if unit_type == "fire_truck" else "helicopter"
+                    self._record_player_action(
+                        "deploy_unit",
+                        f"Deployed {unit_label} at ({x}, {y})",
+                        {"unit_type": unit_type, "x": x, "y": y}
+                    )
+            else:
+                self._add_log(
+                    "error",
+                    f"Failed to deploy {unit_type}: {result.get('message')}"
+                )
+            
+            return result
+    
+    def remove_unit(self, x: int, y: int) -> dict:
+        """Remove a unit at position (thread-safe)."""
+        with self._lock:
+            result = self.engine.remove_unit_at(x, y)
+            
+            if result.get("status") == "ok":
+                self._add_log(
+                    "deploy",
+                    f"Removed unit at ({x}, {y})",
+                    {"unit": result.get("unit")}
+                )
+                removed_unit = result.get("unit") or {}
+                unit_type = removed_unit.get("type", "")
+                unit_label = (
+                    "fire truck"
+                    if unit_type == "fire_truck"
+                    else "helicopter"
+                    if unit_type == "helicopter"
+                    else "unit"
+                )
+                self._record_player_action(
+                    "remove_unit",
+                    f"Removed {unit_label} at ({removed_unit.get('x', x)}, {removed_unit.get('y', y)})",
+                    {"unit": removed_unit}
+                )
+            
+            return result
+    
+    def add_fire(self, x: int, y: int, intensity: float = 0.5) -> dict:
+        """Add fire at position (thread-safe). For testing purposes."""
+        with self._lock:
+            if self.engine.world is None:
+                return {"status": "error", "message": "World not initialized"}
+            
+            # Check bounds
+            if not (0 <= x < self.engine.world.width and 0 <= y < self.engine.world.height):
+                return {"status": "error", "message": f"Position ({x}, {y}) out of bounds"}
+            
+            cell = self.engine.world.grid[y][x]
+            
+            # Only allow fire on forest or building
+            if cell.cell_type not in (CellType.FOREST, CellType.BUILDING):
+                return {"status": "error", "message": "Fire can only be placed on forest or building"}
+            
+            # Cannot place fire on existing fire or smoke
+            if cell.fire_intensity > 0:
+                return {"status": "error", "message": "Cannot place fire on existing fire or smoke"}
+            
+            # Check if there's already a unit at this position
+            for unit in self.engine.world.units:
+                if unit.x == x and unit.y == y:
+                    return {"status": "error", "message": "Cannot place fire where a unit exists"}
+            
+            # Set fire intensity
+            old_intensity = cell.fire_intensity
+            cell.fire_intensity = min(1.0, max(0.0, intensity))
+            
+            # Update world metrics
+            self.engine.world.calculate_metrics()
+            
+            self._add_log(
+                "fire",
+                f"🔥 Added fire at ({x}, {y}) with intensity {int(intensity * 100)}%",
+                {"x": x, "y": y, "intensity": cell.fire_intensity, "old_intensity": old_intensity}
+            )
+            result = {"status": "ok", "x": x, "y": y, "intensity": cell.fire_intensity}
+            self._record_player_action(
+                "add_fire",
+                f"Ignited fire at ({x}, {y}) · intensity {int(cell.fire_intensity * 100)}%",
+                result
+            )
+            return result
+    
+    def has_unit_at(self, x: int, y: int) -> bool:
+        """Check if there's a unit at position."""
+        with self._lock:
+            if self.engine.world is None:
+                return False
+            for unit in self.engine.world.units:
+                if unit.x == x and unit.y == y:
+                    return True
+            return False
+    
+    def is_running(self) -> bool:
+        """Check if simulation is running."""
+        return self._running
+    
+    def set_auto_execute(self, enabled: bool):
+        """Set whether to automatically execute AI recommendations."""
+        with self._lock:
+            self._auto_execute = enabled
+    
+    def is_auto_execute(self) -> bool:
+        """Check if auto-execute is enabled."""
+        return self._auto_execute
+    
+    def is_thinking(self) -> bool:
+        """Check if AI advisor is currently thinking."""
+        return self._is_thinking
+    
+    def get_thinking_stage(self) -> int:
+        """Get current AI thinking stage (0=idle, 1=tool_call, 2=assess, 3=plan, 4=execute)."""
+        return self._current_stage if self._is_thinking else 0
+    
+    def _simulation_loop(self):
+        """Background simulation loop."""
+        # Use instance variables to preserve state across pause/resume
+        after_action_context = None
+
+        while self._running:
+            sim_should_stop = False
+            try:
+                with self._lock:
+                    if self.engine.world is None:
+                        break
+                    
+                    # Run advisor immediately on first tick (only once per simulation)
+                    if self._advisor_first_run:
+                        self._advisor_first_run = False
+                        state = self.engine.get_state()
+                        self._run_advisor(state)
+                    
+                    # Advance simulation
+                    self.engine.step()
+                    self._tick_count += 1
+                    
+                    # Check end conditions
+                    state = self.engine.get_state()
+                    self._record_tick_metrics_locked(state)
+                    status = state.get("status", "running")
+                    
+                    if status in ["success", "fail"]:
+                        self._add_log(
+                            "status",
+                            "🎉 SUCCESS! Fire contained!" if status == "success" else "💥 FAILED! Too much damage!"
+                        )
+                        after_action_context = self._prepare_after_action_context_locked(status, state)
+                        self._running = False
+                        sim_should_stop = True
+                    else:
+                        # Periodic advisor evaluation (every advisor_interval ticks)
+                        if self._tick_count % self.advisor_interval == 0:
+                            self._run_advisor(state)
+                        
+                        # Notify UI
+                        if self._on_update:
+                            try:
+                                self._on_update()
+                            except Exception:
+                                pass  # Ignore UI callback errors
+                
+                if after_action_context:
+                    self._launch_after_action_report(after_action_context)
+                    after_action_context = None
+
+                if sim_should_stop:
+                    break
+
+                # Sleep between ticks
+                time.sleep(self.tick_interval)
+                
+            except Exception as e:
+                with self._lock:
+                    self._add_log("error", f"Simulation error: {str(e)}")
+                break
+    
+    def _archive_current_cycle_locked(self):
+        """Move the completed cycle messages into history (caller must hold _lock)."""
+        if not self._current_cycle_messages:
+            return
+        self._advisor_history.extend(self._current_cycle_messages)
+        if len(self._advisor_history) > 42:
+            self._advisor_history = self._advisor_history[-39:]
+        self._current_cycle_messages = []
+    
+    def _run_advisor(self, state: dict):
+        """
+        Run advisor analysis with progressive stage display.
+        Each stage is shown one at a time: Assessment → Planning → Execution → Summary.
+        """
+        # Prevent concurrent advisor calls
+        if self._advisor_running:
+            return
+        
+        self._advisor_running = True
+        tick = state.get("tick", 0)
+        
+        try:
+            # ================================================================
+            # Start new cycle - archive previous and clear current
+            # ================================================================
+            # Archive previous cycle to history (if exists)
+            self._archive_current_cycle_locked()
+            
+            # Clear current cycle for new analysis
+            self._current_cycle_messages = []
+            self._thinking_start_tick = tick
+            
+            # ================================================================
+            # Stage 1: ASSESS - Query MCP tools and analyze situation
+            # ================================================================
+            self._current_stage = 1
+            self._is_thinking = True
+            
+            self._lock.release()
+            try:
+                assessment = self.advisor.assess(state)
+            finally:
+                self._lock.acquire()
+            
+            # Add assessment message with integrated MCP tool calls
+            self._add_assessment_message(assessment, state, tick)
+            self._is_thinking = False
+            
+            # ================================================================
+            # Stage 2: PLAN - Formulate tactical strategy
+            # ================================================================
+            self._current_stage = 2
+            self._is_thinking = True
+            
+            self._lock.release()
+            try:
+                plan = self.advisor.plan(state, assessment)
+            finally:
+                self._lock.acquire()
+            
+            self._add_planning_message(plan, tick)
+            self._is_thinking = False
+            
+            # ================================================================
+            # Stage 3: EXECUTE - Generate and execute deployment commands
+            # ================================================================
+            self._current_stage = 3
+            self._is_thinking = True
+            
+            self._lock.release()
+            try:
+                recommendations = self.advisor.execute(state, assessment, plan)
+            finally:
+                self._lock.acquire()
+            
+            # Add execution message with integrated MCP tool calls
+            self._add_execution_message(recommendations, tick)
+            
+            # Build final response object (needed for summary + logging)
+            response = self._build_advisor_response(assessment, plan, recommendations)
+            self._latest_recommendations = response
+            
+            # ================================================================
+            # Stage 4: SUMMARY - Consolidate cycle outcomes
+            # ================================================================
+            self._current_stage = 4
+            self._is_thinking = True
+            
+            self._lock.release()
+            try:
+                cycle_summary = self.advisor.summarize(state, assessment, plan, recommendations, response)
+            finally:
+                self._lock.acquire()
+            
+            self._is_thinking = False
+            self._add_summary_cycle_message(cycle_summary, tick)
+            self._record_cycle_summary(tick, cycle_summary, self.engine.get_state())
+            
+            # ================================================================
+            # Complete - all stages done
+            # ================================================================
+            self._current_stage = 5
+            
+            self._add_log(
+                "advisor",
+                response.summary,
+                {
+                    "recommendations": [r.to_dict() for r in response.recommendations],
+                    "thinking": response.thinking,
+                    "analysis": response.analysis,
+                    "priority": response.priority,
+                    "error": response.error
+                }
+            )
+            
+            # Auto-execute recommendations if enabled
+            if self._auto_execute and response.recommendations:
+                self._execute_recommendations(response, tick)
+            
+        except Exception as e:
+            self._is_thinking = False
+            self._current_stage = 0
+            self._add_log("error", f"Advisor error: {str(e)}")
+            # Add error message to current cycle
+            self._current_cycle_messages.append({
+                "role": "assistant",
+                "content": f"❌ AI Advisor Error: {str(e)}"
+            })
+        finally:
+            self._advisor_running = False
+            # Ensure completed cycle is archived so UI can fold under ⏱️ Tick blocks immediately
+            self._archive_current_cycle_locked()
+    
+    def _add_assessment_message(self, assessment: AssessmentResult, state: dict, tick: int):
+        """Add the Assessment message (Stage 1) with MCP tool calls to current cycle."""
+        
+        fires = state.get("fires", [])
+        units = state.get("units", [])
+        buildings = state.get("buildings", [])
+        building_integrity = state.get("building_integrity", 1.0)
+        status = state.get("status", "running")
+        width = state.get("width", 10)
+        height = state.get("height", 10)
+        
+        # Generate emoji map
+        emoji_map = generate_emoji_map(self.engine)
+        
+        priority_emoji = {
+            "CRITICAL": "🔴",
+            "HIGH": "🟠", 
+            "MODERATE": "🟡",
+            "LOW": "🟢"
+        }
+        emoji = priority_emoji.get(assessment.threat_level, "⚪")
+        
+        content = f"""
+### 📊 Stage 1 · Assessment `[Tick {tick}]`
+
+#### 🔧 MCP Tool Calls
+
+<details>
+<summary>📤 <code>mcp.get_world_state()</code></summary>
+
+```python
+result = mcp.get_world_state()
+```
+
+**Response**
+```
+status: {status} | grid: {width}x{height}
+fires: {len(fires)} | units: {len(units)}/{state.get('max_units', 10)}
+buildings: {len(buildings)} | integrity: {building_integrity:.0%}
+```
+
+```
+{emoji_map}
+```
+
+_Legend: 🌲 Forest · 🏢 Building · 🔥 Fire · 💨 Smoke · 🚒 Truck · 🚁 Heli_
+</details>
+""".strip()
+        
+        if assessment.ineffective_units:
+            idle_lines = []
+            for u in assessment.ineffective_units[:5]:
+                idle_lines.append(f"- {u.get('type', 'unit')} at ({u.get('x', 0)}, {u.get('y', 0)})")
+            if len(assessment.ineffective_units) > 5:
+                idle_lines.append(f"- ... and {len(assessment.ineffective_units) - 5} more")
+            idle_block = "\n".join(idle_lines)
+            content += f"""
+
+<details>
+<summary>📤 <code>mcp.find_idle_units()</code> → ⚠️ {len(assessment.ineffective_units)} idle</summary>
+
+```python
+{idle_block}
+```
+</details>
+"""
+        else:
+            content += """
+
+<details>
+<summary>📤 <code>mcp.find_idle_units()</code> → ✅ All effective</summary>
+
+```python
+# Every deployed unit is actively covering a fire
+```
+</details>
+"""
+        
+        if assessment.uncovered_fires:
+            fire_lines = []
+            for f in assessment.uncovered_fires[:5]:
+                fire_lines.append(f"- Fire at ({f.get('x', 0)}, {f.get('y', 0)}) · intensity={f.get('intensity', 0):.0%}")
+            if len(assessment.uncovered_fires) > 5:
+                fire_lines.append(f"- ... and {len(assessment.uncovered_fires) - 5} more")
+            fire_block = "\n".join(fire_lines)
+            content += f"""
+
+<details>
+<summary>📤 <code>mcp.find_uncovered_fires()</code> → 🚨 {len(assessment.uncovered_fires)} uncovered</summary>
+
+```python
+{fire_block}
+```
+</details>
+"""
+        else:
+            content += """
+
+<details>
+<summary>📤 <code>mcp.find_uncovered_fires()</code> → ✅ All covered</summary>
+
+```python
+# All active fires currently have unit coverage
+```
+</details>
+"""
+        
+        content += f"""
+#### 📋 Analysis Results
+
+**Threat Level:** {emoji} {assessment.threat_level}
+
+**Fire Analysis**
+- Total fires: {assessment.fire_count}
+- High intensity (>70%): {len(assessment.high_intensity_fires)}
+- Building threats: {len(assessment.building_threats)}
+- ⚠️ Uncovered fires: {len(assessment.uncovered_fires)}
+
+**Unit Analysis**
+- Deployed: {assessment.unit_count}/{assessment.max_units}
+- Effective: {len(assessment.effective_units)}
+- Idle: {len(assessment.ineffective_units)}
+- Coverage ratio: {assessment.coverage_ratio:.0%}
+
+**Summary:** {assessment.summary}
+"""
+        content += "\n\n---\n"
+        self._current_cycle_messages.append({"role": "assistant", "content": content})
+    
+    def _add_planning_message(self, plan, tick: int):
+        """Add the Planning message (Stage 2) to current cycle."""
+        strategy_emoji = {
+            "deploy_new": "🚀",
+            "optimize_existing": "🔄",
+            "balanced": "⚖️",
+            "monitor": "👀"
+        }
+        s_emoji = strategy_emoji.get(plan.strategy, "📋")
+        
+        action_lines = []
+        if plan.deploy_count > 0:
+            action_lines.append(f"- Deploy: {plan.deploy_count} new unit(s)")
+        if plan.reposition_units:
+            action_lines.append(f"- Reposition: {len(plan.reposition_units)} idle unit(s)")
+        if plan.priority_targets:
+            action_lines.append(f"- Priority fires: {len(plan.priority_targets)}")
+        
+        content = f"""
+### 🎯 Stage 2 · Planning `[Tick {tick}]`
+
+**Strategy:** {s_emoji} `{plan.strategy.upper()}`
+
+**Reasoning**
+{plan.reasoning}
+""".strip()
+        
+        if action_lines:
+            content += "\n\n**Action Outline**\n" + "\n".join(action_lines)
+
+        content += "\n\n---\n"
+        
+        self._current_cycle_messages.append({"role": "assistant", "content": content})
+    
+    def _add_execution_message(self, recommendations, tick: int):
+        """Add the Execution message (Stage 3) with MCP tool calls to current cycle."""
+        if not recommendations:
+            content = f"### ⚡ Stage 3 · Execution `[Tick {tick}]`\n\n✅ **No actions required.** Current deployments already cover every fire."
+            content += "\n\n---\n"
+            self._current_cycle_messages.append({"role": "assistant", "content": content})
+            self._record_action_breakdown(tick, 0, 0, 0)
+            return
+        
+        move_count = sum(1 for r in recommendations if getattr(r, "action", "deploy") == "move")
+        replace_count = sum(1 for r in recommendations if getattr(r, "action", "deploy") == "replace")
+        deploy_count = len(recommendations) - move_count - replace_count
+        
+        summary = []
+        if move_count:
+            summary.append(f"- 🔄 Reposition {move_count} idle unit(s)")
+        if replace_count:
+            summary.append(f"- 🔁 Replace {replace_count} unit(s)")
+        if deploy_count:
+            summary.append(f"- 🚀 Deploy {deploy_count} additional unit(s)")
+        
+        content = f"### ⚡ Stage 3 · Execution `[Tick {tick}]`\n\n" + "\n".join(summary) + "\n\n#### 🔧 MCP Tool Actions\n"
+        
+        for idx, rec in enumerate(recommendations, 1):
+            unit_emoji = "🚒" if rec.suggested_unit_type == "fire_truck" else "🚁"
+            unit_name = "Fire Truck" if rec.suggested_unit_type == "fire_truck" else "Helicopter"
+            action = getattr(rec, "action", "deploy")
+            
+            if action == "move":
+                source_x = getattr(rec, "source_x", 0)
+                source_y = getattr(rec, "source_y", 0)
+                block = f"""
+<details>
+<summary>{idx}. 🔄 Move {unit_name} from ({source_x}, {source_y}) → ({rec.target_x}, {rec.target_y})</summary>
+
+```python
+mcp.move_unit(
+    source_x={source_x}, source_y={source_y},
+    target_x={rec.target_x}, target_y={rec.target_y}
+)
+```
+
+💡 _{rec.reason}_
+</details>
+"""
+            elif action == "replace":
+                old_type = getattr(rec, "old_unit_type", "fire_truck")
+                old_name = "Fire Truck" if old_type == "fire_truck" else "Helicopter"
+                old_emoji = "🚒" if old_type == "fire_truck" else "🚁"
+                block = f"""
+<details>
+<summary>{idx}. 🔁 Replace {old_name} {old_emoji} with {unit_name} {unit_emoji} at ({rec.target_x}, {rec.target_y})</summary>
+
+```python
+mcp.replace_unit(
+    x={rec.target_x}, y={rec.target_y},
+    new_unit_type="{rec.suggested_unit_type}"
+)
+```
+
+💡 _{rec.reason}_
+</details>
+"""
+            else:
+                block = f"""
+<details>
+<summary>{idx}. {unit_emoji} Deploy {unit_name} to ({rec.target_x}, {rec.target_y})</summary>
+
+```python
+mcp.deploy_unit(
+    unit_type="{rec.suggested_unit_type}",
+    x={rec.target_x}, y={rec.target_y}
+)
+```
+
+💡 _{rec.reason}_
+</details>
+"""
+            content += "\n" + block.strip() + "\n"
+
+        content += "\n\n---\n"
+        
+        self._current_cycle_messages.append({"role": "assistant", "content": content})
+        self._record_action_breakdown(tick, deploy_count, move_count, replace_count)
+    
+    def _add_summary_cycle_message(self, cycle_summary: CycleSummary, tick: int):
+        """Add Stage 4 summary message to the current cycle."""
+        highlights = "\n".join(f"- {item}" for item in cycle_summary.key_highlights) or "- (none)"
+        risks = "\n".join(f"- {item}" for item in cycle_summary.risks) or "- (none)"
+        next_focus = "\n".join(f"- {item}" for item in cycle_summary.next_focus) or "- (none)"
+        content = f"""
+### 🧭 Stage 4 · Summary `[Tick {tick}]`
+
+**Headline:** {cycle_summary.headline}
+
+**Threat Level:** {cycle_summary.threat_level}
+
+**Key Highlights**
+{highlights}
+
+**Risks / Gaps**
+{risks}
+
+**Next Focus**
+{next_focus}
+""".strip()
+        content += "\n\n---\n"
+        self._current_cycle_messages.append({"role": "assistant", "content": content})
+    
+    def _build_advisor_response(self, assessment: AssessmentResult, plan: PlanResult, recommendations: list) -> AdvisorResponse:
+        """Build the final AdvisorResponse object."""
+        
+        # Build thinking summary
+        thinking_parts = [
+            f"📊 Scanning {assessment.fire_count} active fires...",
+        ]
+        if assessment.uncovered_fires:
+            thinking_parts.append(f"🚨 ALERT: {len(assessment.uncovered_fires)} fire(s) with NO coverage!")
+        if assessment.building_threats:
+            thinking_parts.append(f"🏢 {len(assessment.building_threats)} fire(s) threatening buildings!")
+        if assessment.ineffective_units:
+            thinking_parts.append(f"🔄 {len(assessment.ineffective_units)} idle unit(s) should be repositioned")
+        thinking_parts.append(f"🎯 Strategy: {plan.strategy.upper()} - {plan.reasoning}")
+        
+        # Generate summary
+        priority_emoji = {"CRITICAL": "🔴", "HIGH": "🟠", "MODERATE": "🟡", "LOW": "🟢"}
+        emoji = priority_emoji.get(assessment.threat_level, "⚪")
+        
+        if assessment.threat_level == "CRITICAL":
+            summary = f"{emoji} CRITICAL: {assessment.summary}. Immediate action required!"
+        elif assessment.threat_level == "HIGH":
+            summary = f"{emoji} HIGH: {assessment.summary}. Rapid response needed."
+        elif assessment.threat_level == "MODERATE":
+            summary = f"{emoji} MODERATE: {assessment.summary}. Tactical deployment advised."
+        else:
+            summary = f"{emoji} LOW: {assessment.summary}. Monitoring situation."
+        
+        return AdvisorResponse(
+            summary=summary,
+            recommendations=recommendations,
+            thinking="\n".join(thinking_parts),
+            analysis=f"{assessment.fire_count} fires | {assessment.unit_count}/{assessment.max_units} units | {assessment.building_integrity:.0%} building integrity",
+            priority=assessment.threat_level,
+            assessment=assessment,
+            plan=plan
+        )
+    
+    def _execute_recommendations(self, response: AdvisorResponse, tick: int):
+        """Execute AI recommendations (must be called with lock held)."""
+        executed_count = 0
+        for rec in response.recommendations:
+            # Create unique key for this recommendation
+            action = getattr(rec, 'action', 'deploy')
+            rec_key = f"{tick}_{action}_{rec.suggested_unit_type}_{rec.target_x}_{rec.target_y}"
+            
+            # Skip if already executed
+            if rec_key in self._executed_recommendations:
+                continue
+            
+            if action == "move":
+                # Move action: remove from source, deploy at target
+                source_x = getattr(rec, 'source_x', -1)
+                source_y = getattr(rec, 'source_y', -1)
+                
+                if source_x >= 0 and source_y >= 0:
+                    # First remove the unit from source
+                    remove_result = self.engine.remove_unit_at(source_x, source_y)
+                    
+                    if remove_result.get("status") == "ok":
+                        # Then deploy at target
+                        deploy_result = self.engine.deploy_unit(rec.suggested_unit_type, rec.target_x, rec.target_y, "ai")
+                        
+                        if deploy_result.get("status") == "ok":
+                            executed_count += 1
+                            unit_name = "Fire Truck" if rec.suggested_unit_type == "fire_truck" else "Helicopter"
+                            self._add_log(
+                                "deploy",
+                                f"🤖 AI moved {unit_name}: ({source_x},{source_y}) → ({rec.target_x},{rec.target_y})",
+                                {"unit": deploy_result.get("unit"), "source": "ai", "reason": rec.reason, "action": "move"}
+                            )
+                            self._executed_recommendations.add(rec_key)
+                        else:
+                            # Deploy failed, try to restore the removed unit
+                            self.engine.deploy_unit(rec.suggested_unit_type, source_x, source_y, "ai")
+                            self._add_log(
+                                "error",
+                                f"🤖 AI move failed: {deploy_result.get('message')} - restored unit at ({source_x},{source_y})"
+                            )
+                    else:
+                        self._add_log(
+                            "error",
+                            f"🤖 AI move failed: No unit at source ({source_x},{source_y})"
+                        )
+            elif action == "remove":
+                # Remove action: remove unit at position (frees slot for redeployment elsewhere)
+                remove_result = self.engine.remove_unit_at(rec.target_x, rec.target_y)
+                
+                if remove_result.get("status") == "ok":
+                    executed_count += 1
+                    unit_name = "Fire Truck" if rec.suggested_unit_type == "fire_truck" else "Helicopter"
+                    self._add_log(
+                        "deploy",
+                        f"🤖 AI removed {unit_name} at ({rec.target_x},{rec.target_y}) - ready to redeploy",
+                        {"source": "ai", "reason": rec.reason, "action": "remove"}
+                    )
+                    self._executed_recommendations.add(rec_key)
+                else:
+                    self._add_log(
+                        "error",
+                        f"🤖 AI remove failed: {remove_result.get('message')} at ({rec.target_x},{rec.target_y})"
+                    )
+            else:
+                # Deploy action
+                result = self.engine.deploy_unit(rec.suggested_unit_type, rec.target_x, rec.target_y, "ai")
+                
+                if result.get("status") == "ok":
+                    executed_count += 1
+                    unit_name = "Fire Truck" if rec.suggested_unit_type == "fire_truck" else "Helicopter"
+                    self._add_log(
+                        "deploy",
+                        f"🤖 AI deployed {unit_name} at ({rec.target_x}, {rec.target_y})",
+                        {"unit": result.get("unit"), "source": "ai", "reason": rec.reason, "action": "deploy"}
+                    )
+                    self._executed_recommendations.add(rec_key)
+                else:
+                    # Log failure but don't stop
+                    self._add_log(
+                        "error",
+                        f"🤖 AI deploy failed: {result.get('message')} at ({rec.target_x}, {rec.target_y})"
+                    )
+        
+        # Keep executed recommendations bounded
+        if len(self._executed_recommendations) > 100:
+            self._executed_recommendations = set(list(self._executed_recommendations)[-50:])
+    
+    def _add_log(self, event_type: str, message: str, details: Optional[dict] = None):
+        """Add a log entry (must be called with lock held)."""
+        tick = self.engine.world.tick if self.engine.world else 0
+        
+        self._logs.append(LogEntry(
+            timestamp=datetime.now().strftime("%H:%M:%S"),
+            tick=tick,
+            event_type=event_type,
+            message=message,
+            details=details
+        ))
+        
+        # Keep logs bounded
+        if len(self._logs) > 200:
+            self._logs = self._logs[-100:]
+
+
+# Global service instance for the app
+_service: Optional[SimulationService] = None
+
+
+def get_service() -> SimulationService:
+    """Get or create the global simulation service."""
+    global _service
+    if _service is None:
+        _service = SimulationService()
+    return _service
+

simulation.py

@@ -0,0 +1,338 @@
+"""
+Fire-Rescue - Simulation Core
+
+Handles fire spread, unit behavior, and win/lose conditions.
+"""
+
+import random
+from typing import Optional
+
+from models import (
+    WorldState, 
+    Cell, 
+    CellType, 
+    Unit, 
+    UnitType, 
+    SimulationStatus,
+    Event
+)
+
+
+class SimulationConfig:
+    """Configuration parameters for the simulation."""
+    
+    # Grid size
+    GRID_WIDTH = 10
+    GRID_HEIGHT = 10
+    
+    # Fire spread parameters (balanced for playability)
+    FIRE_SPREAD_CHANCE = 0.08  # Reduced: chance to spread to adjacent cell per tick
+    FIRE_GROWTH_RATE = 0.02    # Reduced: how much fire intensity grows per tick
+    FIRE_MAX_INTENSITY = 1.0
+    FIRE_DECAY_RATE = 0.01     # Natural decay (very slow)
+    
+    # Damage parameters
+    DAMAGE_PER_TICK = 0.01     # Reduced: damage dealt by fire per tick
+    
+    # Unit parameters (stronger firefighting)
+    FIRE_TRUCK_RANGE = 1       # Square coverage radius (includes 8 neighboring cells)
+    FIRE_TRUCK_POWER = 0.4     # Increased: reduction in fire intensity per action
+    HELICOPTER_RANGE = 2       # Square coverage radius (extends two cells in all directions)
+    HELICOPTER_POWER = 0.25    # Increased: less powerful but wider coverage
+    UNIT_COOLDOWN = 1          # Reduced: ticks between unit actions (faster response)
+    
+    # Win/lose thresholds
+    BUILDING_DAMAGE_THRESHOLD = 0.5  # Fail if building integrity < 50%
+    FOREST_DAMAGE_THRESHOLD = 0.8    # Fail if forest burn > 80%
+    FIRE_SAFE_THRESHOLD = 0.1        # Win if all fires below this intensity
+
+
+class SimulationEngine:
+    """
+    Core simulation engine that manages world state updates.
+    """
+    
+    def __init__(self, config: Optional[SimulationConfig] = None):
+        self.config = config or SimulationConfig()
+        self.world: Optional[WorldState] = None
+    
+    def reset(
+        self, 
+        seed: Optional[int] = None, 
+        fire_count: int = 4,
+        fire_intensity: float = 0.6,
+        building_count: int = 16,
+        max_units: int = 10
+    ) -> WorldState:
+        """
+        Reset and initialize a new simulation.
+        
+        Args:
+            seed: Random seed for reproducibility
+            fire_count: Number of initial fire points (1-25)
+            fire_intensity: Initial fire intensity (0.0-1.0)
+            building_count: Number of buildings to place (1-25)
+            max_units: Maximum number of deployable units (1-20)
+        """
+        self.world = WorldState(
+            width=self.config.GRID_WIDTH,
+            height=self.config.GRID_HEIGHT,
+            tick=0,
+            status=SimulationStatus.RUNNING,
+            max_ticks=200,
+            max_units=max_units
+        )
+        
+        self.world.initialize_grid(
+            seed=seed, 
+            fire_count=fire_count, 
+            fire_intensity=fire_intensity,
+            building_count=building_count
+        )
+        self.world.calculate_metrics()
+        
+        return self.world
+    
+    def step(self) -> WorldState:
+        """Advance simulation by one tick."""
+        if self.world is None:
+            raise RuntimeError("Simulation not initialized. Call reset() first.")
+        
+        if self.world.status != SimulationStatus.RUNNING:
+            return self.world
+        
+        # 1. Units perform actions FIRST (so deployed units work immediately)
+        self._update_units()
+        
+        # 2. Fire spreads and grows
+        self._update_fire()
+        
+        # 3. Fire causes damage
+        self._update_damage()
+        
+        # 4. Recalculate metrics
+        self.world.calculate_metrics()
+        
+        # 5. Increment tick
+        self.world.tick += 1
+        
+        # 6. Check win/lose conditions
+        self._check_end_conditions()
+        
+        return self.world
+    
+    def _update_fire(self):
+        """Update fire spread and growth."""
+        new_fires: list[tuple[int, int, float]] = []
+        
+        for row in self.world.grid:
+            for cell in row:
+                if cell.fire_intensity > 0:
+                    # Fire grows
+                    cell.fire_intensity = min(
+                        cell.fire_intensity + self.config.FIRE_GROWTH_RATE,
+                        self.config.FIRE_MAX_INTENSITY
+                    )
+                    
+                    # Fire spreads to neighbors
+                    for dx, dy in [(-1, 0), (1, 0), (0, -1), (0, 1)]:
+                        nx, ny = cell.x + dx, cell.y + dy
+                        neighbor = self.world.get_cell(nx, ny)
+                        
+                        if neighbor and neighbor.fire_intensity == 0 and not neighbor.is_destroyed():
+                            # Spread chance based on source fire intensity
+                            spread_chance = self.config.FIRE_SPREAD_CHANCE * cell.fire_intensity
+                            if random.random() < spread_chance:
+                                # Initial intensity based on source
+                                new_intensity = cell.fire_intensity * 0.5
+                                new_fires.append((nx, ny, new_intensity))
+        
+        # Apply new fires
+        for x, y, intensity in new_fires:
+            cell = self.world.get_cell(x, y)
+            if cell and cell.fire_intensity == 0:
+                cell.fire_intensity = intensity
+    
+    def _update_damage(self):
+        """Update damage caused by fire."""
+        for row in self.world.grid:
+            for cell in row:
+                if cell.fire_intensity > 0 and cell.cell_type != CellType.EMPTY:
+                    # Damage proportional to fire intensity
+                    damage = self.config.DAMAGE_PER_TICK * cell.fire_intensity
+                    cell.damage = min(cell.damage + damage, 1.0)
+    
+    def _update_units(self):
+        """Update unit actions (firefighting)."""
+        for unit in self.world.units:
+            # Decrease cooldown
+            if unit.cooldown > 0:
+                unit.cooldown -= 1
+                continue
+            
+            # Find cells to extinguish
+            extinguished = False
+            
+            if unit.unit_type == UnitType.FIRE_TRUCK:
+                extinguished = self._fire_truck_action(unit)
+            elif unit.unit_type == UnitType.HELICOPTER:
+                extinguished = self._helicopter_action(unit)
+            
+            if extinguished:
+                unit.cooldown = self.config.UNIT_COOLDOWN
+    
+    def _fire_truck_action(self, unit: Unit) -> bool:
+        """Fire truck extinguishes fires within a square radius (Chebyshev distance)."""
+        targets = []
+        
+        # Check cells within square range (including diagonals)
+        for dx in range(-self.config.FIRE_TRUCK_RANGE, self.config.FIRE_TRUCK_RANGE + 1):
+            for dy in range(-self.config.FIRE_TRUCK_RANGE, self.config.FIRE_TRUCK_RANGE + 1):
+                cell = self.world.get_cell(unit.x + dx, unit.y + dy)
+                if cell and cell.fire_intensity > 0:
+                    targets.append(cell)
+        
+        if not targets:
+            return False
+        
+        # Target highest intensity fire
+        targets.sort(key=lambda c: c.fire_intensity, reverse=True)
+        target = targets[0]
+        
+        # Reduce fire
+        target.fire_intensity = max(0, target.fire_intensity - self.config.FIRE_TRUCK_POWER)
+        
+        return True
+    
+    def _helicopter_action(self, unit: Unit) -> bool:
+        """Helicopter extinguishes fires within a wider square radius."""
+        affected = False
+        
+        for dx in range(-self.config.HELICOPTER_RANGE, self.config.HELICOPTER_RANGE + 1):
+            for dy in range(-self.config.HELICOPTER_RANGE, self.config.HELICOPTER_RANGE + 1):
+                cell = self.world.get_cell(unit.x + dx, unit.y + dy)
+                if cell and cell.fire_intensity > 0:
+                    cell.fire_intensity = max(0, cell.fire_intensity - self.config.HELICOPTER_POWER)
+                    affected = True
+        
+        return affected
+    
+    def _check_end_conditions(self):
+        """Check win/lose conditions."""
+        # Check time limit
+        if self.world.tick >= self.world.max_ticks:
+            self.world.status = SimulationStatus.FAIL
+            self.world.recent_events.append(Event(
+                tick=self.world.tick,
+                event_type="simulation_end",
+                details={"reason": "time_limit_exceeded"}
+            ))
+            return
+        
+        # Check building damage
+        if self.world.building_integrity < (1 - self.config.BUILDING_DAMAGE_THRESHOLD):
+            self.world.status = SimulationStatus.FAIL
+            self.world.recent_events.append(Event(
+                tick=self.world.tick,
+                event_type="simulation_end",
+                details={"reason": "building_destroyed"}
+            ))
+            return
+        
+        # Check forest damage
+        if self.world.forest_burn_ratio > self.config.FOREST_DAMAGE_THRESHOLD:
+            self.world.status = SimulationStatus.FAIL
+            self.world.recent_events.append(Event(
+                tick=self.world.tick,
+                event_type="simulation_end",
+                details={"reason": "forest_destroyed"}
+            ))
+            return
+        
+        # Check if all fires are extinguished
+        fires = self.world.get_fires()
+        if not fires or all(f.intensity < self.config.FIRE_SAFE_THRESHOLD for f in fires):
+            self.world.status = SimulationStatus.SUCCESS
+            self.world.recent_events.append(Event(
+                tick=self.world.tick,
+                event_type="simulation_end",
+                details={"reason": "fire_contained"}
+            ))
+    
+    def deploy_unit(
+        self, 
+        unit_type: str, 
+        x: int, 
+        y: int, 
+        source: str = "player"
+    ) -> dict:
+        """Deploy a new unit at the specified position."""
+        if self.world is None:
+            return {"status": "error", "message": "Simulation not initialized"}
+        
+        if self.world.status != SimulationStatus.RUNNING:
+            return {"status": "error", "message": "Simulation is not running"}
+        
+        # Parse unit type
+        try:
+            utype = UnitType(unit_type)
+        except ValueError:
+            return {"status": "error", "message": f"Invalid unit type: {unit_type}"}
+        
+        # Check position validity first for better error messages
+        if not (0 <= x < self.world.width and 0 <= y < self.world.height):
+            return {"status": "error", "message": f"Position ({x}, {y}) is out of bounds"}
+        
+        cell = self.world.get_cell(x, y)
+        if cell and cell.fire_intensity > 0:
+            return {"status": "error", "message": f"Cannot deploy on burning cell at ({x}, {y})"}
+        
+        if cell and cell.cell_type == CellType.BUILDING:
+            return {"status": "error", "message": f"Cannot deploy on building at ({x}, {y})"}
+        
+        # Check unit limit
+        if len(self.world.units) >= self.world.max_units:
+            return {"status": "error", "message": f"Unit limit reached ({self.world.max_units})"}
+        
+        # Try to add unit
+        unit = self.world.add_unit(utype, x, y, source)
+        
+        if unit is None:
+            return {"status": "error", "message": "Failed to deploy unit"}
+        
+        return {
+            "status": "ok",
+            "unit": unit.to_dict()
+        }
+    
+    def remove_unit_at(self, x: int, y: int) -> dict:
+        """Remove a unit at the specified position."""
+        if self.world is None:
+            return {"status": "error", "message": "Simulation not initialized"}
+        
+        # Find unit at position
+        unit_to_remove = None
+        for unit in self.world.units:
+            if unit.x == x and unit.y == y:
+                unit_to_remove = unit
+                break
+        
+        if unit_to_remove is None:
+            return {"status": "error", "message": f"No unit at ({x}, {y})"}
+        
+        # Remove the unit
+        self.world.units.remove(unit_to_remove)
+        
+        return {
+            "status": "ok",
+            "message": f"Removed {unit_to_remove.unit_type.value} at ({x}, {y})",
+            "unit": unit_to_remove.to_dict()
+        }
+    
+    def get_state(self) -> dict:
+        """Get current world state as dictionary."""
+        if self.world is None:
+            return {"status": "error", "message": "Simulation not initialized"}
+        
+        return self.world.to_dict()
+