Initial commit

> Co-authored-by: Pierre Andrews <[email protected]>
> Co-authored-by: Adrien <[email protected]>
> Co-authored-by: Avijit Ghosh <[email protected]>
> Co-authored-by: Clémentine Fourrier <[email protected]>
> Co-authored-by: Maxime Lecanu <[email protected]>
> Co-authored-by: thibaud frere <[email protected]>
> Co-authored-by: Kunal Mukesh Malkan <[email protected]>
> Co-authored-by: Romain Froger <[email protected]>

.dockerignore

@@ -0,0 +1,15 @@
+node_modules
+npm-debug.log
+package-lock.json
+frontend/node_modules
+frontend/package-lock.json
+frontend/npm-debug.log
+**/node_modules
+**/package-lock.json
+.git
+.gitignore
+README.md
+.env
+.nyc_output
+coverage
+.vscode

.gitattributes

@@ -0,0 +1,44 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+blog_assets/ filter=lfs diff=lfs merge=lfs -text
+blog_assets/fig2_structure_of_are.png filter=lfs diff=lfs merge=lfs -text
+blog_assets/fig9_gaia2_scores_per_capability.png filter=lfs diff=lfs merge=lfs -text
+blog_assets/thumbnail_mare_gaia2.png filter=lfs diff=lfs merge=lfs -text
+blog_assets/demo_robot_short.mp4 filter=lfs diff=lfs merge=lfs -text
+blog_assets/fig12_calls_tokens_vs_score_pareto_frontier.png filter=lfs diff=lfs merge=lfs -text
+blog_assets/fig1_budget_scaling_curves.png filter=lfs diff=lfs merge=lfs -text
+blog_assets/demo_base.mov filter=lfs diff=lfs merge=lfs -text
+blog_assets/demo_traces.mov filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,6 @@
+.cache
+.ssh
+.vscode
+arena/.env
+*__pycache__*
+frontend/node_modules

.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+default_language_version:
+  python: python3
+
+ci:
+  autofix_prs: true
+  autoupdate_commit_msg: '[pre-commit.ci] pre-commit suggestions'
+  autoupdate_schedule: quarterly
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.3.0
+    hooks:
+      - id: check-yaml
+      - id: check-case-conflict
+      - id: detect-private-key
+      - id: check-added-large-files
+        args: ['--maxkb=1000']
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    # Ruff version.
+    rev: 'v0.11.10'
+    hooks:
+      - id: ruff
+        args: ['--fix']
+      - id: ruff-format

Dockerfile

@@ -0,0 +1,125 @@
+
+# ------------------------------------------------------------
+# Stage 0: Pull ARE
+# ------------------------------------------------------------
+FROM ubuntu:20.04 AS fetch_repo
+RUN apt update && \
+apt install -y git curl && \
+curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | bash && \
+apt-get install -y git-lfs
+
+RUN --mount=type=secret,id=github_username,required=true --mount=type=secret,id=github_token,required=true \
+    GITHUB_USERNAME=$(cat /run/secrets/github_username) && \
+    GITHUB_TOKEN=$(cat /run/secrets/github_token) && \
+    git clone https://$GITHUB_USERNAME:[email protected]/facebookresearch/meta-agents-research-environments.git && \
+    cd meta-agents-research-environments && \
+    git lfs install && \
+    git lfs pull && \
+    rm -rf ./are/simulation/tests && \
+    rm -rf ./are/simulation/tutorials
+
+
+# ------------------------------------------------------------
+# Stage 1: Build the front end
+# ------------------------------------------------------------
+FROM node:23 AS frontend-builder
+WORKDIR /app
+COPY --from=fetch_repo /meta-agents-research-environments/are/simulation/gui/client ./are/simulation/gui/client
+WORKDIR /app/are/simulation/gui/client
+# Clear npm cache and remove lock file to fix ARM64 rollup issue
+RUN npm cache clean --force && rm -f package-lock.json
+RUN --mount=type=cache,target=/root/.npm NPM_CONFIG_CACHE=/root/.npm npm install
+RUN npm run build
+
+
+# ------------------------------------------------------------
+# Stage 1.5: Build the React frontend
+# ------------------------------------------------------------
+
+FROM node:23 AS react-frontend-builder
+WORKDIR /app/frontend
+COPY frontend/package.json ./
+# Clear npm cache and remove lock file to fix ARM64 rollup issue
+RUN npm cache clean --force && rm -f package-lock.json
+RUN --mount=type=cache,target=/root/.npm NPM_CONFIG_CACHE=/root/.npm npm install
+COPY frontend/ ./
+RUN npm run build
+
+
+# ------------------------------------------------------------
+# Stage 2: Build the backend and gradio app
+# ------------------------------------------------------------
+
+FROM python:3.10.14-slim
+
+## Needed for docker dev mode in spaces
+RUN useradd -m -u 1000 user
+
+## Backend
+ARG SERVER_VERSION=unknown
+RUN apt-get update && apt-get install -y \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Needed packages for docker dev mode in spaces
+RUN apt-get update && apt-get install -y \
+    bash git-lfs wget procps \
+    vim net-tools \
+    && rm -rf /var/lib/apt/lists/*
+RUN pip install uv
+
+# ARE install
+COPY --from=fetch_repo /meta-agents-research-environments/are /app/are
+COPY --from=fetch_repo /meta-agents-research-environments/build_hooks /app/build_hooks
+COPY --from=fetch_repo /meta-agents-research-environments/pyproject.toml /app/pyproject.toml
+COPY --from=fetch_repo /meta-agents-research-environments/uv.lock /app/uv.lock
+COPY --from=fetch_repo /meta-agents-research-environments/requirements* /app/
+COPY --from=fetch_repo /meta-agents-research-environments/README.md /app/README.md
+COPY --from=fetch_repo /meta-agents-research-environments/LICENSE /app/LICENSE
+WORKDIR /app
+ARG VIRTUAL_ENV /app/.venv
+RUN --mount=type=cache,target=/root/.cache/pip uv venv
+RUN --mount=type=cache,target=/root/.cache/pip uv pip install '.'
+RUN rm -rf /app/are/gui/client
+COPY --from=frontend-builder /app/are/simulation/gui/client/build /app/are/simulation/gui/client/build
+
+# Env
+ENV PYTHONUNBUFFERED=1
+ENV ARE_SERVER_HOSTNAME=0.0.0.0
+ENV ARE_SERVER_VERSION=$SERVER_VERSION
+ENV HF_HOME=/app/.cache
+ENV HF_DATASETS_CACHE=/app/.cache
+# For gradio to recognize the env as a space
+ENV SYSTEM=spaces
+# For uvicorn to allow headers and avoid mixed content in site and iframe
+ENV FORWARDED_ALLOW_IPS="*"
+
+# Port React frontend build
+COPY --from=react-frontend-builder /app/frontend/build /app/frontend/build
+
+WORKDIR /app
+RUN chown 1000 /app
+EXPOSE 7860
+
+# Backend deps
+RUN uv pip install -U huggingface_hub "datasets==4.0.0" "gradio[oauth]==5.42.0" gradio_modal "jsonschema>=4.0.0" psutil
+RUN uv pip install --no-cache-dir flask gunicorn
+
+# Get core code
+COPY backend/ /app/backend/
+COPY app.py /app/app.py
+COPY run.sh /app/run.sh
+COPY mcp_demo_prompts.json /app/mcp_demo_prompts.json
+
+# Create data directory with proper permissions
+RUN mkdir -p /app/data && chown 1000:1000 /app/data
+
+# Env vars
+ENV PORT=7860 FLASK_ENV=production PYTHONUNBUFFERED=1 STORAGE_PATH=/app/data
+
+RUN chmod 755 /app/.venv
+USER 1000
+
+# Start Flask (serves static frontend and the API)
+CMD ["bash", "run.sh"]

Dockerfile.dev

@@ -0,0 +1,13 @@
+# Development version - extends the main Dockerfile
+FROM aredemo:latest
+
+# Override environment variables for development
+ENV FLASK_ENV=development
+ENV NODE_ENV=development
+ENV FLASK_DEBUG=1
+
+# Expose additional ports if needed
+EXPOSE 7860 3000
+
+# Use development-specific command if needed
+CMD ["bash", "run.sh"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,14 @@
+---
+title: MSL Agents Research Environments Demo
+emoji: 🚀
+colorFrom: blue
+colorTo: pink
+sdk: docker
+sdk_version: 5.16.0
+pinned: false
+hf_oauth: true
+hf_oauth_scopes:
+ - inference-api
+ - read-repos
+license: mit
+---

app.py

@@ -0,0 +1,603 @@
+import json
+import logging
+import os
+import pathlib
+import threading
+import time
+from datetime import datetime, timedelta
+from urllib.parse import quote
+
+import psutil
+import requests
+
+from backend.are import get_are_url, start_are_process_and_session_lite
+
+from backend.cleanup import cleanup
+from backend.globals import STORAGE_PATH
+
+from backend.iframe import validate_mcp_file
+from backend.session import UserSession
+from flask import Flask, jsonify, request, send_from_directory
+
+# Ensure storage directory exists
+os.makedirs(STORAGE_PATH, exist_ok=True)
+
+AUTH_SESSION_MANAGEMENT = {}
+SESSION_MANAGEMENT = {}
+
+# Serve the static frontend and expose a minimal API
+app = Flask(
+    __name__,
+    static_folder=os.path.join(os.path.dirname(__file__), "frontend", "build"),
+    static_url_path="",
+)
+
+logging.basicConfig(level=logging.INFO, format="[%(levelname)s] %(message)s")
+logger = logging.getLogger(__name__)
+
+
+def cleanup_old_sessions() -> None:
+    """Clean up sessions that are older than 2 hours."""
+    try:
+        current_time = datetime.now()
+        sessions_to_remove = []
+
+        for username, session in SESSION_MANAGEMENT.items():
+            try:
+                # Parse the session start time
+                start_time = datetime.strptime(
+                    session.start_time, "%Y-%m-%d %H:%M:%S.%f"
+                )
+                session_age = current_time - start_time
+
+                # Check if session is older than 2 hours
+                if session_age > timedelta(hours=2):
+                    logger.info(
+                        f"Session {session.sid} for user {username} "
+                        f"is {session_age} old, marking for cleanup"
+                    )
+                    sessions_to_remove.append(username)
+
+            except (ValueError, AttributeError) as e:
+                logger.warning(
+                    f"Could not parse start time for session "
+                    f"{session.sid} (user: {username}): {e}"
+                )
+                # If we can't parse the time, assume it's old and clean it up
+                sessions_to_remove.append(username)
+
+        # Clean up old sessions
+        for username in sessions_to_remove:
+            if username in SESSION_MANAGEMENT:
+                session = SESSION_MANAGEMENT[username]
+                logger.info(
+                    f"Cleaning up old session {session.sid} " f"for user {username}"
+                )
+                try:
+                    cleanup(session)
+                    del SESSION_MANAGEMENT[username]
+                    logger.info(
+                        f"Successfully cleaned up old session "
+                        f"{session.sid} for user {username}"
+                    )
+                except Exception as e:
+                    logger.error(
+                        f"Error cleaning up old session "
+                        f"{session.sid} for user {username}: {e}"
+                    )
+                    # Remove from SESSION_MANAGEMENT even if cleanup failed
+                    # to prevent accumulation of broken sessions
+                    try:
+                        del SESSION_MANAGEMENT[username]
+                    except KeyError:
+                        pass
+
+        if sessions_to_remove:
+            logger.info(f"Cleaned up {len(sessions_to_remove)} old sessions")
+
+    except Exception as e:
+        logger.error(f"Error during old session cleanup: {e}")
+
+
+def cleanup_session_async(user_session: UserSession) -> None:
+    """Run cleanup in the background to avoid blocking the main thread."""
+    if user_session is None:
+        return
+
+    def run_cleanup():
+        try:
+            session_id = user_session.sid
+            logger.info(f"Starting background cleanup for session {session_id}")
+            cleanup(user_session)
+            logger.info(f"Background cleanup completed for session {session_id}")
+
+            # Also clean up any other old sessions while we're at it
+            logger.info("Checking for old sessions to clean up...")
+            cleanup_old_sessions()
+
+        except Exception as e:
+            session_id = getattr(user_session, "sid", "unknown")
+            logger.error(
+                f"Error during background cleanup for session " f"{session_id}: {e}"
+            )
+
+    # Start cleanup in a separate thread
+    cleanup_thread = threading.Thread(target=run_cleanup, daemon=True)
+    cleanup_thread.start()
+
+
+def get_session_from_cookie(cookie):
+    # Possible cookie session names
+    for session_name in [
+        "session",
+        "spaces-jwt",
+        "sessionid",
+        "JSESSIONID",
+        "connect.sid",
+    ]:
+        try:
+            session = cookie[session_name]
+            return session
+        except Exception:
+            continue
+    return None
+
+
+@app.get("/")
+def index():
+    """Serve the main HTML document."""
+    sign_in_info = request.args.get("__sign", default=None, type=str)
+    cookie_session = get_session_from_cookie(request.cookies)
+
+    if sign_in_info is not None and cookie_session is not None:
+        AUTH_SESSION_MANAGEMENT[cookie_session] = sign_in_info
+        logger.info(f"Filled sign for session {cookie_session}: {sign_in_info}")
+    return send_from_directory(app.static_folder, "index.html")
+
+
+@app.get("/demo-mcp.json")
+def demo_mcp():
+    """Serve the demo MCP file."""
+    # Try serving from the built frontend first (production)
+    try:
+        return send_from_directory(app.static_folder, "demo-mcp.json")
+    except FileNotFoundError:
+        # Fall back to the public directory (development)
+        try:
+            public_folder = os.path.join(
+                os.path.dirname(__file__), "frontend", "public"
+            )
+            return send_from_directory(public_folder, "demo-mcp.json")
+        except FileNotFoundError:
+            logger.error("demo-mcp.json not found in either build or public directory")
+            return jsonify({"error": "demo-mcp.json not found"}), 404
+
+
+@app.get("/api/models/<provider>")
+def get_models_for_provider(provider):
+    """Fetch available models for a given provider from Hugging Face API."""
+    if provider == "llama-api":
+        # Model IDs from https://llama.developer.meta.com/docs/models/
+        llama_models = [
+            "Llama-4-Maverick-17B-128E-Instruct-FP8",
+            "Llama-4-Scout-17B-16E-Instruct-FP8",
+            "Llama-3.3-70B-Instruct",
+            "Llama-3.3-8B-Instruct",
+            "Cerebras-Llama-4-Maverick-17B-128E-Instruct",
+            "Cerebras-Llama-4-Scout-17B-16E-Instruct",
+            "Groq-Llama-4-Maverick-17B-128E-Instruct",
+        ]
+        return jsonify({"models": llama_models}), 200
+
+    try:
+        # Map provider to the correct API parameter with proper URL encoding
+        encoded_provider = quote(provider)
+
+        # Fetch models with image-text-to-text pipeline tag
+        url_image_text = f"https://huggingface.co/api/models?pipeline_tag=image-text-to-text&inference_provider={encoded_provider}"
+        response_image_text = requests.get(url_image_text, timeout=10)
+
+        # Fetch models with text-generation pipeline tag
+        url_text_gen = f"https://huggingface.co/api/models?pipeline_tag=text-generation&inference_provider={encoded_provider}"
+        response_text_gen = requests.get(url_text_gen, timeout=10)
+
+        # Check if both requests were successful
+        if response_image_text.status_code != 200:
+            logger.error(
+                f"Failed to fetch image-text-to-text models for provider {provider}: "
+                f"{response_image_text.status_code}"
+            )
+            return (
+                jsonify(
+                    {
+                        "error": "Failed to fetch image-text-to-text models",
+                        "status": response_image_text.status_code,
+                    }
+                ),
+                500,
+            )
+
+        if response_text_gen.status_code != 200:
+            logger.error(
+                f"Failed to fetch text-generation models for provider {provider}: "
+                f"{response_text_gen.status_code}"
+            )
+            return (
+                jsonify(
+                    {
+                        "error": "Failed to fetch text-generation models",
+                        "status": response_text_gen.status_code,
+                    }
+                ),
+                500,
+            )
+
+        # Parse responses and merge results
+        image_text_models = response_image_text.json()
+        text_gen_models = response_text_gen.json()
+
+        # Extract model IDs from both responses
+        image_text_ids = [
+            model.get("id") for model in image_text_models if model.get("id")
+        ]
+        text_gen_ids = [model.get("id") for model in text_gen_models if model.get("id")]
+
+        # Merge and deduplicate model IDs
+        model_ids = list(set(image_text_ids + text_gen_ids))
+        model_ids.sort()  # Sort the models alphabetically
+
+        logger.info(
+            f"Fetched {len(image_text_ids)} image-text-to-text models and {len(text_gen_ids)} text-generation models for provider {provider} (total: {len(model_ids)} unique models)"
+        )
+        return jsonify({"models": model_ids}), 200
+
+    except requests.RequestException as e:
+        logger.error(f"Network error when fetching models for provider {provider}: {e}")
+        return jsonify({"error": "Network error", "detail": str(e)}), 500
+    except Exception as e:
+        logger.error(
+            f"Unexpected error when fetching models for provider " f"{provider}: {e}"
+        )
+        return jsonify({"error": "Internal error", "detail": str(e)}), 500
+
+
+@app.get("/api/processes")
+def list_python_processes():
+    # Check for key query parameter
+    key = request.args.get("key")
+    if not key:
+        return jsonify({"error": "Unauthorized access"}), 403
+
+    # Check if key matches OWNER_SECRET environment variable
+    owner_secret = os.environ.get("OWNER_SECRET")
+    if not owner_secret:
+        return (jsonify({"error": "Server configuration error"}), 500)
+
+    if key != owner_secret:
+        return jsonify({"error": "Unauthorized access"}), 403
+
+    try:
+        python_processes = []
+
+        # Iterate through all running processes using psutil
+        for proc in psutil.process_iter():
+            try:
+                # Get process info
+                pinfo = proc.as_dict(
+                    attrs=[
+                        "pid",
+                        "ppid",
+                        "name",
+                        "username",
+                        "status",
+                        "create_time",
+                        "cpu_percent",
+                        "memory_percent",
+                        "memory_info",
+                        "cmdline",
+                    ]
+                )
+
+                # Check if this is a Python process
+                process_name = pinfo["name"].lower()
+                cmdline = " ".join(pinfo["cmdline"]) if pinfo["cmdline"] else ""
+
+                if (
+                    "python" in process_name
+                    or "python" in cmdline.lower()
+                    or cmdline.endswith(".py")
+                ):
+
+                    # Convert create_time to readable format
+                    create_time = time.strftime(
+                        "%Y-%m-%d %H:%M:%S", time.localtime(pinfo["create_time"])
+                    )
+
+                    # Format memory info
+                    memory_info = pinfo.get("memory_info")
+                    rss_mb = (memory_info.rss / 1024 / 1024) if memory_info else 0
+                    vms_mb = (memory_info.vms / 1024 / 1024) if memory_info else 0
+
+                    process_info = {
+                        "pid": pinfo["pid"],
+                        "ppid": pinfo["ppid"],
+                        "name": pinfo["name"],
+                        "username": pinfo.get("username", "unknown"),
+                        "status": pinfo["status"],
+                        "cpu_percent": round(pinfo.get("cpu_percent", 0), 2),
+                        "memory_percent": round(pinfo.get("memory_percent", 0), 2),
+                        "memory_rss_mb": round(rss_mb, 2),
+                        "memory_vms_mb": round(vms_mb, 2),
+                        "create_time": create_time,
+                        "cmdline": (
+                            cmdline[:200] + "..." if len(cmdline) > 200 else cmdline
+                        ),
+                    }
+                    python_processes.append(process_info)
+
+            except (psutil.NoSuchProcess, psutil.AccessDenied, psutil.ZombieProcess):
+                # Process may have terminated or we don't have permission
+                continue
+            except Exception as e:
+                logger.warning(f"Error processing process {proc.pid}: {e}")
+                continue
+
+        # Sort by PID for consistent ordering
+        python_processes.sort(key=lambda x: x["pid"])
+
+        return (
+            jsonify({"processes": python_processes, "count": len(python_processes)}),
+            200,
+        )
+
+    except Exception as e:
+        logger.error(f"Unexpected error listing processes: {e}")
+        return (jsonify({"error": "Internal server error"}), 500)
+
+
+@app.get("/api/sessions")
+def list_active_sessions():
+    # Check for key query parameter
+    key = request.args.get("key")
+    if not key:
+        return jsonify({"error": "Unauthorized access"}), 403
+
+    # Check if key matches OWNER_SECRET environment variable
+    owner_secret = os.environ.get("OWNER_SECRET")
+    if not owner_secret:
+        return (jsonify({"error": "Server configuration error"}), 500)
+
+    if key != owner_secret:
+        return jsonify({"error": "Unauthorized access"}), 403
+
+    try:
+        active_sessions = []
+        current_time = time.time()
+
+        for username, session in SESSION_MANAGEMENT.items():
+            try:
+                # Calculate session duration
+                start_timestamp = time.mktime(
+                    time.strptime(session.start_time, "%Y-%m-%d %H:%M:%S.%f")
+                )
+                duration_seconds = current_time - start_timestamp
+                duration_hours = duration_seconds / 3600
+
+                # Check if process is still running
+                process_status = "unknown"
+                cpu_percent = 0
+                memory_percent = 0
+
+                try:
+                    proc = psutil.Process(session.pid)
+                    process_status = proc.status()
+                    cpu_percent = proc.cpu_percent()
+                    memory_percent = proc.memory_percent()
+                except (psutil.NoSuchProcess, psutil.AccessDenied):
+                    process_status = "not_found"
+
+                session_info = {
+                    "username": username,
+                    "session_id": session.sid,
+                    "pid": session.pid,
+                    "port": session.port,
+                    "model": session.model,
+                    "provider": session.provider,
+                    "start_time": session.start_time,
+                    "duration_hours": round(duration_hours, 2),
+                    "log_path": session.log_path,
+                    "process_status": process_status,
+                    "cpu_percent": round(cpu_percent, 2),
+                    "memory_percent": round(memory_percent, 2),
+                }
+                active_sessions.append(session_info)
+
+            except Exception as e:
+                logger.warning(f"Error processing session for user {username}: {e}")
+                # Still include basic info even if we can't get process details
+                session_info = {
+                    "username": username,
+                    "session_id": session.sid,
+                    "pid": session.pid,
+                    "port": session.port,
+                    "model": session.model,
+                    "provider": session.provider,
+                    "start_time": session.start_time,
+                    "duration_hours": "unknown",
+                    "log_path": session.log_path,
+                    "process_status": "error",
+                    "cpu_percent": 0,
+                    "memory_percent": 0,
+                }
+                active_sessions.append(session_info)
+
+        # Sort by start time (most recent first)
+        active_sessions.sort(
+            key=lambda x: x["start_time"] if x["start_time"] != "unknown" else "",
+            reverse=True,
+        )
+
+        return (
+            jsonify({"sessions": active_sessions, "count": len(active_sessions)}),
+            200,
+        )
+
+    except Exception as e:
+        logger.error(f"Unexpected error listing sessions: {e}")
+        return (jsonify({"error": "Internal server error"}), 500)
+
+
+@app.post("/api/start")
+def start_demo():
+    """Receive the form payload and simulate demo startup.
+
+    Logs both the raw payload and a safe summary, then returns a dummy iframe URL
+    after a small delay to mimic startup time.
+    """
+    try:
+        data = request.get_json(force=True, silent=False)
+    except Exception as exc:
+        logger.info("Invalid JSON", data, str(exc))
+        logger.exception("Invalid JSON body")
+        return jsonify({"ok": False, "error": "invalid_json", "detail": str(exc)}), 400
+    if not isinstance(data, dict):
+        logger.info("Invalid JSON", data)
+        logger.exception("Invalid JSON body")
+        return jsonify({"ok": False, "error": "invalid_json"}), 400
+
+    cookie_session = get_session_from_cookie(request.cookies)
+    try:
+        signin_token = AUTH_SESSION_MANAGEMENT[cookie_session]
+    except KeyError:  # weird edge case
+        signin_token = cookie_session
+
+    # Raw payload logging
+    logger.info(
+        "/api/start payload:\n%s", json.dumps(data, indent=2, ensure_ascii=False)
+    )
+
+    # Request metadata and a concise payload summary (avoid dumping large mcp bodies)
+    client_ip = (
+        (request.headers.get("X-Forwarded-For") or request.remote_addr or "-")
+        .split(",")[0]
+        .strip()
+    )
+    user_agent = request.headers.get("User-Agent", "-")
+    referer = request.headers.get("Referer", "-")
+    content_type = request.content_type
+    content_length = request.content_length
+    auth_header = request.headers.get("Authorization")
+    user_token = None
+    if auth_header and auth_header.lower().startswith("bearer "):
+        user_token = auth_header.split(" ", 1)[1].strip()
+
+    logger.info(
+        {
+            "user_agent": user_agent,
+            "referer": referer,
+            "content_type": content_type,
+            "content_length": content_length,
+            "auth_header": auth_header,
+            "user_token": user_token,
+        }
+    )
+
+    username = data.get("user")
+
+    # MCP validation
+    mcp_text = data.get("mcp") if isinstance(data, dict) else None
+    mcp_json_path = None
+
+    if isinstance(mcp_text, str):
+        try:
+            mcp_data = validate_mcp_file(mcp_text, user_token)
+
+            mcp_json_path = f"{STORAGE_PATH}/{username}/mcp.json"
+            os.makedirs(f"{STORAGE_PATH}/{username}", exist_ok=True)
+            with open(pathlib.Path(mcp_json_path), "w") as file:
+                json.dump(mcp_data, file, indent=4)
+
+        except ValueError as e:
+            logger.error(f"MCP file validation failed: {e}")
+            return (
+                jsonify({"ok": False, "error": "invalid_mcp_file", "detail": str(e)}),
+                400,
+            )
+        except Exception as e:
+            logger.error(f"Could not process MCP file: {e}")
+            return (
+                jsonify(
+                    {
+                        "ok": False,
+                        "error": "mcp_processing_failed",
+                        "detail": f"Failed to process MCP file: {str(e)}",
+                    }
+                ),
+                500,
+            )
+
+    # Killing previous session
+    logger.info(f"Current SESSION_MANAGEMENT keys: {list(SESSION_MANAGEMENT.keys())}")
+    logger.info(f"Looking for username: {username}")
+    user_session = SESSION_MANAGEMENT.get(username, None)
+    if user_session:
+        logger.info(f"Killing existing session for {username}: {user_session}")
+        cleanup_session_async(SESSION_MANAGEMENT[username])
+        del SESSION_MANAGEMENT[username]  # Actually remove the session
+        user_session = None
+        logger.info(
+            f"Started background cleanup for previous session of user {username}"
+        )
+    else:
+        logger.info(f"No previous processes to kill for {username}")
+
+    user_session: UserSession = start_are_process_and_session_lite(
+        model=data.get("model", ""),
+        provider=data.get("provider", ""),
+        username=username,
+        bearer_token=signin_token,
+        user_token=user_token,
+        app_path=mcp_json_path,
+    )
+
+    SESSION_MANAGEMENT[username] = user_session
+    logger.info(f"User SESSION {user_session}")
+
+    logger.info(
+        f"Started session {user_session.sid} on port {user_session.port} for user {user_session.user}"
+    )
+    iframe_url: str = get_are_url(session=user_session, server="are_simulation")
+    health_url: str = get_are_url(session=user_session, server="health")
+
+    summary = {
+        "client": {
+            "ip": client_ip,
+            "user_agent": user_agent,
+            "referer": referer,
+            "content_type": content_type,
+            "content_length": content_length,
+        },
+        "received_fields": {
+            "model": data.get("model") if isinstance(data, dict) else None,
+            "provider": data.get("provider") if isinstance(data, dict) else None,
+            "user": data.get("user") if isinstance(data, dict) else None,
+            # "mcp_length": mcp_len,
+            # "mcp_is_json": mcp_is_json,
+        },
+        "auth": {
+            "signin_token": signin_token,
+        },
+    }
+    logger.info("/api/start summary: %s", json.dumps(summary, ensure_ascii=False))
+
+    return jsonify({"ok": True, "received": True, "iframe_url": iframe_url, "health_url": health_url}), 200
+
+
+def run():
+    """Run the development/Space server."""
+    port = int(os.environ.get("PORT", "7860"))
+    app.run(host="0.0.0.0", port=port)
+
+
+if __name__ == "__main__":
+    run()

backend/are.py

@@ -0,0 +1,167 @@
+import datetime
+import logging
+import os
+import random
+import subprocess
+import uuid
+
+import psutil
+from backend.globals import FREE_PORTS_POOL, ORG, SPACE, STORAGE_PATH
+from backend.session import UserSession
+
+logger = logging.getLogger(__name__)
+
+
+def start_are_process_and_session_lite(
+    model: str,
+    provider: str,
+    username: str,
+    bearer_token: str | None,
+    user_token: str | None,
+    app_path: str | None,
+) -> UserSession:
+    if not user_token:
+        error_msg = (
+            f"HF_TOKEN (user_token) is None for user {username}. "
+            "Cannot start ARE session without Hugging Face token."
+        )
+        raise ValueError(error_msg)
+
+    global FREE_PORTS_POOL
+    port = random.sample(FREE_PORTS_POOL, k=1)[0]
+
+    log_path = f"{STORAGE_PATH}/log_{port}.log"
+    env_vars = dict(os.environ)
+    env_vars["ARE_SERVER_HOSTNAME"] = "0.0.0.0"
+    env_vars["ARE_SIMULATION_SERVER_HOSTNAME"] = "0.0.0.0"
+    env_vars["ARE_SERVER_PORT"] = str(port)
+    env_vars["ARE_SIMULATION_SERVER_PORT"] = str(port)
+    env_vars["HF_TOKEN"] = os.environ.get("HF_DATASET_TOKEN", user_token)
+    env_vars["HF_INFERENCE_TOKEN"] = user_token
+    env_vars["HF_DEMO_UNIVERSE"] = "universe_hf_0"  # universe_hf"
+    bill_to = os.environ.get("HF_BILL_TO")
+    if bill_to:
+        env_vars["HF_BILL_TO"] = bill_to
+    llama_key = os.environ.get("LLAMA_API_KEY")
+    if llama_key:
+        env_vars["LLAMA_API_KEY"] = llama_key
+    env_vars["INTERACTIVE_SCENARIOS_TREE"] = "/app/mcp_demo_prompts.json"
+    if app_path:
+        env_vars["MCP_APPS_JSON_PATH"] = app_path
+
+    p = subprocess.Popen(
+        " ".join(
+            ["python", "-u", "-m", "are.simulation.gui.cli", "-a", "default"]
+            + ["-m", model, "--provider", provider]
+            + [
+                "-s",
+                "scenario_hf_demo_mcp",
+                # "hf://datasets/meta-agents-research-environments/gaia2/demo/validation/universe_hf",
+                "--ui_view",
+                "playground",
+            ]  # scenario_universe_hf_0 or "scenario_hf_0" or "universe_hf_0"
+            + ["2>&1", "|", "tee", log_path]
+        ),
+        env=env_vars,
+        shell=True,
+        executable="/bin/bash",
+    )
+
+    FREE_PORTS_POOL = [p for p in FREE_PORTS_POOL if p != port]
+    user_session = UserSession(
+        port=int(port),
+        pid=p.pid,
+        sid=str(uuid.uuid4()),
+        model=model,
+        provider=provider,
+        log_path=log_path,
+        start_time=str(datetime.datetime.now()),
+        user=username,
+        sign=bearer_token,
+    )
+
+    return user_session
+
+
+def kill_are_process(session: UserSession) -> None:
+    # Automatically kills the are processes and all their children
+    global FREE_PORTS_POOL
+
+    try:
+        # Get the main process
+        main_process = psutil.Process(session.pid)
+
+        # Get all child processes recursively
+        children = main_process.children(recursive=True)
+
+        # Kill all child processes first
+        for child in children:
+            try:
+                child.kill()
+                logger.info(f"Killed child process PID {child.pid}")
+            except psutil.NoSuchProcess:
+                logger.info(f"Child process PID {child.pid} already terminated")
+            except OSError:
+                logger.warning(f"Child process PID {child.pid} not found")
+
+        # Wait for child processes to terminate
+        for child in children:
+            try:
+                child.wait(timeout=5)
+            except psutil.TimeoutExpired:
+                logger.warning(
+                    f"Child process PID {child.pid} did not terminate within timeout"
+                )
+            except psutil.NoSuchProcess:
+                pass
+
+        # Kill the main process
+        main_process.kill()
+        logger.info(f"Sent SIGKILL to main PID {session.pid}")
+
+        # Wait for main process to terminate
+        try:
+            main_process.wait(timeout=5)
+        except psutil.TimeoutExpired:
+            logger.warning(
+                f"Main process PID {session.pid} did not terminate within timeout"
+            )
+        except psutil.NoSuchProcess:
+            pass
+
+        FREE_PORTS_POOL.append(session.port)
+        logger.info(
+            f"Killed session {session.sid} PID {session.pid} on port {session.port} for user {session.user}"
+        )
+
+    except psutil.NoSuchProcess:
+        logger.info(f"Process PID {session.pid} not found - may already be terminated")
+        FREE_PORTS_POOL.append(session.port)
+    except OSError:
+        logger.error(
+            f"COULD NOT KILL ARE on port {session.port} for user {session.user}",
+            exc_info=True,
+        )
+
+
+def get_are_url(session: UserSession, server: str) -> str:
+    """Generates the are url
+
+    Args:
+        port (str): Port on which the app is running
+        session_id (str): Session id in ARE
+        sign (str): Auth key provided by the query
+        server (str): Must be either "are" or "graphql"
+
+    Returns:
+        str: The url to look at
+    """
+    # Check if we're in development mode
+    flask_env = os.environ.get("FLASK_ENV", "production")
+
+    if flask_env == "development":
+        # In development mode, use localhost with the actual ARE port
+        return f"http://localhost:{session.port}/{server}?sid={session.sid}&__sign={session.sign}"
+    else:
+        # In production mode, use Hugging Face Space URL
+        return f"https://{ORG.lower()}-{SPACE.lower()}--{session.port}.hf.space/{server}?sid={session.sid}&__sign={session.sign}"

backend/cleanup.py

@@ -0,0 +1,20 @@
+from backend.are import kill_are_process
+from backend.session import UserSession
+
+
+def cleanup(user_session: UserSession) -> None:
+    """Logs the user interaction.
+    Stops ARE, queries GraphQL to grab the traces, saves them locally, pushes everything to the hub,
+    then kills the ARE processes.
+
+    Args:
+        request (gr.Request): Automatically accessed
+        user_session (gr.State): Storage for user-specific session variables, contains a UserSession
+    """
+
+    # The user did not interact with are agent
+    if user_session is None:
+        return
+
+    # Kill the user are processes
+    kill_are_process(user_session)

backend/globals.py

@@ -0,0 +1,13 @@
+import os
+
+# Current gradio app port is 7860
+FREE_PORTS_POOL = [
+    x for x in range(1024, 65535) if x != 7860
+]  # Avail ports for are processes
+
+# STORAGE AND LOGGING
+# Default to local ./data directory
+STORAGE_PATH = os.environ.get("STORAGE_PATH", "./data")
+ORG = "meta-agents-research-environments"
+SPACE = "demo"
+LOGS_HUB_PATH = f"{ORG}/demo-logs"

backend/iframe.py

@@ -0,0 +1,81 @@
+"""Functions which rely on gradio components io and change the interface"""
+
+import json
+
+from jsonschema import validate, ValidationError
+
+
+def validate_mcp_file(mcp_file_content: str, token: str) -> str:
+    """Validates the user uploaded MCP file
+
+    The JSON file should follow this structure (we only allow SSE type for the demo,
+    but if you run locally you can add stdio to your json file):
+
+    ```json
+    {
+        "mcpServers": {
+            "app-name-1": {
+                "type": "sse",
+                "url": "https://api.example.com/mcp",
+                "headers": {
+                    "Authorization": "Bearer your-token-here"
+                }
+            }
+        }
+    }
+    ```
+    """
+    # Define the JSON schema
+    mcp_schema = {
+        "$schema": "https://json-schema.org/draft/2020-12/json-schema-core.html",
+        "type": "object",
+        "properties": {
+            "mcpServers": {
+                "type": "object",
+                "patternProperties": {
+                    "^[\w-]+$": {
+                        "type": "object",
+                        "properties": {
+                            "type": {"type": "string", "enum": ["sse"]},
+                            "url": {"type": "string", "format": "uri"},
+                            "headers": {
+                                "type": "object",
+                                "patternProperties": {"^[\w-]+$": {"type": "string"}},
+                                "additionalProperties": False,
+                            },
+                        },
+                        "required": ["type", "url"],
+                        "additionalProperties": False,
+                    }
+                },
+                "additionalProperties": False,
+                "minProperties": 1,
+            }
+        },
+        "required": ["mcpServers"],
+        "additionalProperties": False,
+    }
+
+    try:
+        mcp_data = json.loads(mcp_file_content)
+        validate(instance=mcp_data, schema=mcp_schema)
+
+        for server in mcp_data.get("mcpServers", {}).values():
+            try:
+                if "HF_TOKEN" in server["headers"]["Authorization"]:
+                    server["headers"]["Authorization"] = server["headers"][
+                        "Authorization"
+                    ].replace("HF_TOKEN", token or "")
+            except KeyError:
+                continue
+
+        return mcp_data
+
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Invalid JSON format: {str(e)}")
+    except ValidationError as e:
+        # Provide more user-friendly error messages
+        error_path = " -> ".join(str(p) for p in e.path) if e.path else "root"
+        raise ValueError(f"Invalid MCP file structure at {error_path}: {e.message}")
+    except Exception as e:
+        raise ValueError(f"Error validating MCP file: {str(e)}")

backend/session.py

@@ -0,0 +1,33 @@
+from dataclasses import asdict, dataclass
+
+
+@dataclass
+class UserSession:
+    """Information associated with the current user's session.
+
+    port: on which port is ARE running
+    pid: ARE process pid to check status
+    sid: Session id in ARE
+    model: User selected model
+    provider: User selected provider
+    log_path: ARE log for the session
+    start_time: Session start time
+    user: Username
+    sign: User sign in # todo: remove when the space becomes public
+    """
+
+    port: int
+    pid: int
+    sid: str
+    model: str
+    provider: str
+    log_path: str
+    start_time: str
+    user: str
+    sign: str
+
+    def log_name(self) -> str:
+        return f"{self.provider}/{self.model}/{self.user}_{self.start_time}_log.json"
+
+    def asdict(self) -> dict:
+        return asdict(self)

blog_assets/demo_base.mov

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:66cf2c878851f278f97efcc7c321cbeebeaace3a0ce9d72ab1a8c5d7cda21dfb
+size 6476197

blog_assets/demo_robot_short.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:db103ab1a0ace57d9bf29c68a7ce84301472e13897d4b070aff8562d163a1328
+size 11108459

blog_assets/demo_traces.mov

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d693a9b31d3bd20e22ecd087b0e0dfc7ecf71a20a7f3c7cda7e2ebfb015aae5c
+size 5722090

demo_mcp_file.json

@@ -0,0 +1,33 @@
+{
+  "mcpServers":
+  {
+    "geocalc-mcp": {
+      "type": "sse",
+      "url": "https://agents-mcp-hackathon-geocalc-mcp.hf.space/gradio_api/mcp/sse",
+      "headers": {
+        "Authorization": "Bearer ${HF_TOKEN}"
+      }
+    },
+    "image-edit-mcp": {
+      "type": "sse",
+      "url": "https://black-forest-labs-flux-1-kontext-dev.hf.space/gradio_api/mcp/sse",
+      "headers": {
+        "Authorization": "Bearer ${HF_TOKEN}"
+      }
+    },
+    "websearch-mcp": {
+      "type": "sse",
+      "url": "https://victor-websearch.hf.space/gradio_api/mcp/sse",
+      "headers": {
+        "Authorization": "Bearer ${HF_TOKEN}"
+      }
+    },
+    "academia-mcp": {
+      "type": "sse",
+      "url": "https://agents-mcp-hackathon-academia-mcp-gradio.hf.space/gradio_api/mcp/sse",
+      "headers": {
+        "Authorization": "Bearer ${HF_TOKEN}"
+      }
+    }
+  }
+}

docker-compose.yml

@@ -0,0 +1,91 @@
+version: '3.8'
+
+services:
+  aredemo:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      platforms:
+        - linux/amd64
+      secrets:
+        - github_username
+        - github_token
+    ports:
+      - "7860:7860"
+    environment:
+      - FLASK_ENV=production
+      - NODE_ENV=production
+      - STORAGE_PATH=/app/data
+    volumes:
+      # Mount data directory for MCP files and session storage
+      - ./data:/app/data
+      # Mount logs or data if needed
+      - ./logs:/app/logs
+
+  aredemo-dev:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      platforms:
+        - linux/amd64
+      secrets:
+        - github_username
+        - github_token
+    ports:
+      - "7860:7860"
+      # Expose a range of ports for ARE processes (1024-1100 should be enough for dev)
+      - "1024-1100:1024-1100"
+    environment:
+      - FLASK_ENV=development
+      - NODE_ENV=development
+      - FLASK_DEBUG=1
+    volumes:
+      # Mount Python source code for hot reloading
+      - ./app.py:/app/app.py
+      - ./backend:/app/backend
+      # Mount MCP demo prompts file
+      - ./mcp_demo_prompts.json:/app/mcp_demo_prompts.json
+      # Mount React frontend source for development
+      - ./frontend/src:/app/frontend/src
+      - ./frontend/public:/app/frontend/public
+      - ./frontend/package.json:/app/frontend/package.json
+      # Mount logs
+      - ./logs:/app/logs
+    develop:
+      watch:
+        - action: sync
+          path: ./app.py
+          target: /app/app.py
+        - action: sync
+          path: ./backend
+          target: /app/backend
+        - action: sync+restart
+          path: ./frontend/src
+          target: /app/frontend/src
+        - action: sync+restart
+          path: ./frontend/public
+          target: /app/frontend/public
+
+  # Separate React dev server for true hot reloading
+  react-dev:
+    build:
+      context: ./frontend
+      dockerfile: Dockerfile.dev
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=development
+      - FAST_REFRESH=true
+      - WDS_SOCKET_HOST=localhost
+    volumes:
+      - ./frontend/src:/app/src
+      - ./frontend/public:/app/public
+      - ./frontend/package.json:/app/package.json
+      - /app/node_modules
+    command: npm start
+
+secrets:
+  github_username:
+    environment: GITHUB_USERNAME
+  github_token:
+    environment: GITHUB_TOKEN

frontend/.gitignore

@@ -0,0 +1,23 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

frontend/.prettierignore

@@ -0,0 +1,3 @@
+# Ignore artifacts:
+build
+coverage

frontend/.prettierrc

@@ -0,0 +1 @@
+{}

frontend/Dockerfile.dev

@@ -0,0 +1,18 @@
+FROM node:23
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci
+
+# Copy source code
+COPY . .
+
+# Expose port
+EXPOSE 3000
+
+# Start development server
+CMD ["npm", "start"]

frontend/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "frontend",
+  "version": "0.1.0",
+  "private": true,
+  "dependencies": {
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.1",
+    "@mui/icons-material": "^7.3.2",
+    "@mui/material": "^7.3.2",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.8.0",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^13.5.0",
+    "@types/jest": "^27.5.2",
+    "@types/node": "^16.18.126",
+    "@types/react": "^19.1.12",
+    "@types/react-dom": "^19.1.9",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "react-scripts": "5.0.1",
+    "typescript": "^4.9.5",
+    "web-vitals": "^2.1.4"
+  },
+  "scripts": {
+    "start": "react-scripts start",
+    "build": "react-scripts build",
+    "test": "react-scripts test",
+    "eject": "react-scripts eject"
+  },
+  "eslintConfig": {
+    "extends": [
+      "react-app",
+      "react-app/jest"
+    ]
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  },
+  "proxy": "http://aredemo-dev:7860",
+  "devDependencies": {
+    "prettier": "3.6.2"
+  }
+}

frontend/public/config.json

@@ -0,0 +1,5 @@
+{
+  "client_id": "09c33b1e-ae67-422a-ae04-f199ac65c19d",
+  "scope": "openid profile email",
+  "redirect_uri": ""
+}

frontend/public/demo-mcp.json

@@ -0,0 +1,32 @@
+{
+  "mcpServers": {
+    "geocalc-mcp": {
+      "type": "sse",
+      "url": "https://agents-mcp-hackathon-geocalc-mcp.hf.space/gradio_api/mcp/sse",
+      "headers": {
+        "Authorization": "Bearer HF_TOKEN"
+      }
+    },
+    "image-edit-mcp": {
+      "type": "sse",
+      "url": "https://black-forest-labs-flux-1-kontext-dev.hf.space/gradio_api/mcp/sse",
+      "headers": {
+        "Authorization": "Bearer HF_TOKEN"
+      }
+    },
+    "websearch-mcp": {
+      "type": "sse",
+      "url": "https://victor-websearch.hf.space/gradio_api/mcp/sse",
+      "headers": {
+        "Authorization": "Bearer HF_TOKEN"
+      }
+    },
+    "academia-mcp": {
+      "type": "sse",
+      "url": "https://agents-mcp-hackathon-academia-mcp-gradio.hf.space/gradio_api/mcp/sse",
+      "headers": {
+        "Authorization": "Bearer HF_TOKEN"
+      }
+    }
+  }
+}

frontend/public/index.html

@@ -0,0 +1,43 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="theme-color" content="#000000" />
+    <meta
+      name="description"
+      content="Web site created using create-react-app"
+    />
+    <link rel="apple-touch-icon" href="%PUBLIC_URL%/logo192.png" />
+    <!--
+      manifest.json provides metadata used when your web app is installed on a
+      user's mobile device or desktop. See https://developers.google.com/web/fundamentals/web-app-manifest/
+    -->
+    <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
+    <!--
+      Notice the use of %PUBLIC_URL% in the tags above.
+      It will be replaced with the URL of the `public` folder during the build.
+      Only files inside the `public` folder can be referenced from the HTML.
+
+      Unlike "/favicon.ico" or "favicon.ico", "%PUBLIC_URL%/favicon.ico" will
+      work correctly both with client-side routing and a non-root public URL.
+      Learn how to configure a non-root public URL by running `npm run build`.
+    -->
+    <title>Meta Agents Research Environments</title>
+  </head>
+  <body>
+    <noscript>You need to enable JavaScript to run this app.</noscript>
+    <div id="root"></div>
+    <!--
+      This HTML file is a template.
+      If you open it directly in the browser, you will see an empty page.
+
+      You can add webfonts, meta tags, or analytics to this file.
+      The build step will place the bundled scripts into the <body> tag.
+
+      To begin the development, run `npm start` or `yarn start`.
+      To create a production bundle, use `npm run build` or `yarn build`.
+    -->
+  </body>
+</html>

frontend/public/manifest.json

@@ -0,0 +1,25 @@
+{
+  "short_name": "React App",
+  "name": "Create React App Sample",
+  "icons": [
+    {
+      "src": "favicon.ico",
+      "sizes": "64x64 32x32 24x24 16x16",
+      "type": "image/x-icon"
+    },
+    {
+      "src": "logo192.png",
+      "type": "image/png",
+      "sizes": "192x192"
+    },
+    {
+      "src": "logo512.png",
+      "type": "image/png",
+      "sizes": "512x512"
+    }
+  ],
+  "start_url": ".",
+  "display": "standalone",
+  "theme_color": "#000000",
+  "background_color": "#ffffff"
+}

frontend/public/robots.txt

@@ -0,0 +1,3 @@
+# https://www.robotstxt.org/robotstxt.html
+User-agent: *
+Disallow:

frontend/src/App.css

@@ -0,0 +1,4 @@
+/* Minimal CSS - most styling is handled by MUI */
+.App {
+  text-align: center;
+}

frontend/src/App.test.tsx

@@ -0,0 +1,9 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import App from "./App";
+
+test("renders learn react link", () => {
+  render(<App />);
+  const linkElement = screen.getByText(/learn react/i);
+  expect(linkElement).toBeInTheDocument();
+});

frontend/src/App.tsx

@@ -0,0 +1,178 @@
+import { Alert, CssBaseline, Snackbar, ThemeProvider } from "@mui/material";
+import { useCallback, useEffect, useState } from "react";
+
+// Local imports
+import { DemoView } from "./components/DemoView";
+import { InitialForm } from "./components/InitialForm";
+import { CustomThemeProvider, useThemeMode } from "./contexts/ThemeContext";
+import { FormData, SnackbarState, UserInfo } from "./types";
+import { preloadDefaultMcp } from "./utils/api";
+import { useStartDemo } from "./hooks/useStartDemo";
+
+const AppContent = () => {
+  const { theme } = useThemeMode();
+
+  // Authentication state
+  const [userInfo, setUserInfo] = useState<UserInfo | null>(null);
+  const [accessToken, setAccessToken] = useState<string | null>(null);
+  const [loginLabel, setLoginLabel] = useState<string>(
+    "Login with Hugging Face",
+  );
+
+  // Form state
+  const [formData, setFormData] = useState<FormData>({
+    model: "",
+    provider: "",
+    mcpFile: null,
+  });
+
+  // UI state
+  const [snackbar, setSnackbar] = useState<SnackbarState>({
+    open: false,
+    message: "",
+    severity: "info",
+  });
+  const [defaultMcpFile, setDefaultMcpFile] = useState<File | null>(null);
+
+  // Demo management hook
+  const {
+    isStarting,
+    iframeUrl,
+    iframeLoading,
+    healthCheckProgress,
+    startDemoSession,
+    resetDemo,
+    setIframeLoaded,
+  } = useStartDemo();
+
+  // Determine if we're in demo mode (iframe is loaded)
+  const isDemoActive = Boolean(iframeUrl);
+
+  // Utility functions
+  const showSnackbar = useCallback(
+    (message: string, severity: "success" | "error" | "info" = "info") => {
+      setSnackbar({ open: true, message, severity });
+    },
+    [],
+  );
+
+  const handleSnackbarClose = () => {
+    setSnackbar((prev: SnackbarState) => ({ ...prev, open: false }));
+  };
+
+  const handleIframeLoad = () => {
+    setIframeLoaded();
+  };
+
+  // Authentication handlers
+  const handleLoginStateChange = useCallback(
+    (
+      newUserInfo: UserInfo | null,
+      newAccessToken: string | null,
+      newLoginLabel: string,
+    ) => {
+      setUserInfo(newUserInfo);
+      setAccessToken(newAccessToken);
+      setLoginLabel(newLoginLabel);
+    },
+    [],
+  );
+
+  // Form handlers
+  const handleFormChange = (newFormData: FormData) => {
+    setFormData(newFormData);
+  };
+
+  const handleFormSubmit = async () => {
+    await startDemoSession(formData, loginLabel, accessToken, {
+      logPrefix: "Initial startup",
+      onError: (error) => {
+        showSnackbar(error.message, "error");
+      },
+    });
+  };
+
+  const handleRestart = () => {
+    resetDemo();
+  };
+
+  const handleSettingsRestart = async () => {
+    await startDemoSession(formData, loginLabel, accessToken, {
+      logPrefix: "Settings restart",
+      onError: (error) => {
+        showSnackbar(error.message, "error");
+      },
+    });
+  };
+
+  // Initialize default MCP file on mount
+  useEffect(() => {
+    const loadDefaultMcp = async () => {
+      const mcpFile = await preloadDefaultMcp();
+      if (mcpFile) {
+        setFormData((prev: FormData) => ({ ...prev, mcpFile: mcpFile }));
+        setDefaultMcpFile(mcpFile);
+      }
+    };
+    loadDefaultMcp();
+  }, []);
+
+  return (
+    <ThemeProvider theme={theme}>
+      <CssBaseline />
+
+      {/* Conditional rendering based on demo state */}
+      {isDemoActive ? (
+        <DemoView
+          iframeUrl={iframeUrl}
+          iframeLoading={iframeLoading}
+          healthCheckProgress={healthCheckProgress}
+          formData={formData}
+          onIframeLoad={handleIframeLoad}
+          onRestart={handleRestart}
+          onFormChange={handleFormChange}
+          onSettingsRestart={handleSettingsRestart}
+          defaultMcpFile={defaultMcpFile}
+        />
+      ) : (
+        <InitialForm
+          formData={formData}
+          userInfo={userInfo}
+          accessToken={accessToken}
+          loginLabel={loginLabel}
+          isStarting={isStarting}
+          onFormChange={handleFormChange}
+          onSubmit={handleFormSubmit}
+          onLoginStateChange={handleLoginStateChange}
+          defaultMcpFile={defaultMcpFile}
+        />
+      )}
+
+      {/* Snackbar for notifications */}
+      <Snackbar
+        open={snackbar.open}
+        autoHideDuration={4000}
+        onClose={handleSnackbarClose}
+        anchorOrigin={{ vertical: "bottom", horizontal: "center" }}
+      >
+        <Alert
+          onClose={handleSnackbarClose}
+          severity={snackbar.severity}
+          sx={{ width: "100%" }}
+        >
+          {snackbar.message}
+        </Alert>
+      </Snackbar>
+    </ThemeProvider>
+  );
+};
+
+function App() {
+  return (
+    <CustomThemeProvider>
+      <AppContent />
+    </CustomThemeProvider>
+  );
+}
+
+export default App;

frontend/src/components/DemoView.tsx

@@ -0,0 +1,321 @@
+import {
+  Logout as LogoutIcon,
+  Refresh as RefreshIcon,
+  UploadFile as UploadFileIcon,
+  Warning as WarningIcon,
+} from "@mui/icons-material";
+import {
+  Alert,
+  AppBar,
+  Box,
+  Button,
+  CircularProgress,
+  Collapse,
+  Divider,
+  Stack,
+  Toolbar,
+  Tooltip,
+  Typography,
+} from "@mui/material";
+import React, { useCallback, useEffect, useState } from "react";
+import { FormData } from "../types";
+import { ModelProviderSelector } from "./ModelProviderSelector";
+import { McpConfigurationWarningDialog } from "./dialogs";
+import { ServerLoadingIndicator } from "./ServerLoadingIndicator";
+
+interface DemoViewProps {
+  iframeUrl: string;
+  iframeLoading: boolean;
+  healthCheckProgress?: {
+    attempt: number;
+    maxAttempts: number;
+  } | null;
+  formData: FormData;
+  defaultMcpFile: File | null;
+  onIframeLoad: () => void;
+  onRestart: () => void;
+  onFormChange: (formData: FormData) => void;
+  onSettingsRestart: () => void;
+}
+
+export const DemoView: React.FC<DemoViewProps> = ({
+  iframeUrl,
+  iframeLoading,
+  healthCheckProgress,
+  formData,
+  onIframeLoad,
+  onRestart,
+  onFormChange,
+  onSettingsRestart,
+}) => {
+  const [showWarning, setShowWarning] = useState(false);
+  const [originalFormData, setOriginalFormData] = useState<FormData>(formData);
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const [pendingFile, setPendingFile] = useState<File | null>(null);
+  const [isMcpTooltipOpen, setMcpTooltipOpen] = useState(false);
+
+  // Form validation
+  const isFormValid = Boolean(
+    formData.model.trim() && formData.provider.trim(),
+  );
+
+  // Update original form data when component first loads or when iframe URL changes (successful restart)
+  useEffect(() => {
+    setOriginalFormData(formData);
+  }, [iframeUrl]); // Update when iframe URL changes, indicating successful restart
+
+  const handleModelChange = useCallback(
+    (value: string) => {
+      onFormChange({ ...formData, model: value });
+      setShowWarning(true);
+    },
+    [formData, onFormChange],
+  );
+
+  const handleProviderChange = useCallback(
+    (value: string) => {
+      // When provider changes, clear the model as well to avoid stale selections
+      onFormChange({ ...formData, provider: value, model: "" });
+      setShowWarning(true);
+    },
+    [formData, onFormChange],
+  );
+
+  const handleFileChange = useCallback(
+    (event: React.ChangeEvent<HTMLInputElement>) => {
+      const file = event.target.files?.[0] || null;
+      if (file) {
+        setPendingFile(file);
+        setDialogOpen(true);
+      } else {
+        onFormChange({ ...formData, mcpFile: null });
+        setShowWarning(true);
+      }
+    },
+    [formData, onFormChange],
+  );
+
+  const handleDialogClose = useCallback(() => {
+    setDialogOpen(false);
+    setPendingFile(null);
+    // Clear the file input element to reset the UI
+    const fileInput = document.querySelector(
+      'input[type="file"]',
+    ) as HTMLInputElement;
+    if (fileInput) {
+      fileInput.value = "";
+    }
+  }, []);
+
+  const handleDialogConfirm = useCallback(() => {
+    if (pendingFile) {
+      onFormChange({ ...formData, mcpFile: pendingFile });
+      setShowWarning(true);
+    }
+    setDialogOpen(false);
+    setPendingFile(null);
+  }, [formData, onFormChange, pendingFile]);
+
+  const handleSettingsRestartClick = () => {
+    setShowWarning(false);
+    // Update the original form data to the current form data after restart
+    setOriginalFormData(formData);
+    onSettingsRestart();
+  };
+
+  const handleWarningDismiss = () => {
+    setShowWarning(false);
+    // Reset form data back to original values
+    onFormChange(originalFormData);
+  };
+
+  return (
+    <Box sx={{ minHeight: "100vh", bgcolor: "background.default" }}>
+      {/* Top Bar with Settings and Restart Button */}
+      <AppBar position="static" color="default" elevation={1}>
+        <Toolbar sx={{ px: 2, py: 1 }}>
+          <Box sx={{ display: "flex", alignItems: "center", gap: 1 }}>
+            <Typography
+              variant="body1"
+              component="div"
+              sx={{ fontWeight: 500 }}
+            >
+              Meta Agents Research Environments
+            </Typography>
+          </Box>
+
+          {/* Spacer to push form to the right */}
+          <Box sx={{ flexGrow: 1 }} />
+
+          {/* Settings Form */}
+          <Box sx={{ display: "flex", alignItems: "center", gap: 0.5 }}>
+            {/* Model and Provider Selection */}
+            <ModelProviderSelector
+              model={formData.model}
+              provider={formData.provider}
+              onModelChange={handleModelChange}
+              onProviderChange={handleProviderChange}
+              variant="toolbar"
+              size="small"
+              showValidation={true}
+            />
+
+            {/* MCP File Input with Tooltip */}
+            <Box
+              sx={{
+                display: "flex",
+                alignItems: "center",
+                gap: 0.5,
+                width: "100%",
+                maxWidth: 500,
+              }}
+            >
+              <Tooltip
+                title="Upload an MCP (Model Context Protocol) file (.json) that defines the tools and capabilities for your agent."
+                placement="left"
+                open={isMcpTooltipOpen}
+              >
+                <span
+                  style={{ width: "200px" }}
+                  onMouseEnter={() => setMcpTooltipOpen(true)}
+                  onMouseLeave={() => setMcpTooltipOpen(false)}
+                  onClick={() => setMcpTooltipOpen(false)}
+                >
+                  <Button
+                    variant="outlined"
+                    component="label"
+                    startIcon={<UploadFileIcon fontSize="inherit" />}
+                    fullWidth
+                    sx={{
+                      justifyContent: "flex-start",
+                      textAlign: "left",
+                      height: 40,
+                      borderColor: (theme) => theme.palette.grey[700],
+                      "&:hover": {
+                        borderColor: (theme) => theme.palette.action.active,
+                      },
+                    }}
+                    color="inherit"
+                  >
+                    <Box
+                      sx={{
+                        overflow: "hidden",
+                        textOverflow: "ellipsis",
+                        whiteSpace: "nowrap",
+                        width: "100%",
+                      }}
+                    >
+                      {formData.mcpFile
+                        ? `${formData.mcpFile.name}`
+                        : "MCP File"}
+                    </Box>
+                    <input
+                      type="file"
+                      hidden
+                      accept=".json"
+                      onChange={handleFileChange}
+                    />
+                  </Button>
+                </span>
+              </Tooltip>
+            </Box>
+            <Divider orientation="vertical" flexItem />
+            {/* Restart Button */}
+
+            <Button
+              variant="outlined"
+              size="small"
+              startIcon={<LogoutIcon />}
+              onClick={onRestart}
+              color="inherit"
+              sx={{ height: 40, opacity: 0.7 }}
+              fullWidth
+            >
+              Exit demo
+            </Button>
+          </Box>
+        </Toolbar>
+      </AppBar>
+
+      {/* Warning Alert */}
+      <Collapse in={showWarning}>
+        <Alert
+          severity="warning"
+          variant="filled"
+          icon={<WarningIcon />}
+          action={
+            <Stack spacing={1} direction="row" alignItems={"center"}>
+              <Button
+                variant="text"
+                size="small"
+                onClick={handleWarningDismiss}
+                color="inherit"
+              >
+                Cancel
+              </Button>
+              <Button
+                variant="contained"
+                size="small"
+                startIcon={<RefreshIcon />}
+                onClick={handleSettingsRestartClick}
+                color="warning"
+                disabled={!isFormValid}
+              >
+                Restart demo with changes
+              </Button>
+            </Stack>
+          }
+          sx={{ borderTopLeftRadius: 0, borderTopRightRadius: 0, pl: 3, pr: 4 }}
+        >
+          You've made changes to the configuration. Click "Restart demo with
+          changes" to apply them.
+        </Alert>
+      </Collapse>
+
+      {/* Iframe Content */}
+      <Box
+        sx={{
+          height: showWarning ? "calc(100vh - 112px)" : "calc(100vh - 64px)",
+          position: "relative",
+          transition: "height 0.3s ease",
+        }}
+      >
+        {iframeLoading ? (
+          <Box
+            sx={{
+              position: "absolute",
+              top: "50%",
+              left: "50%",
+              transform: "translate(-50%, -50%)",
+              zIndex: 3,
+            }}
+          >
+            <ServerLoadingIndicator
+              progress={healthCheckProgress}
+              message="Waiting for server to start..."
+            />
+          </Box>
+        ) : (
+          <iframe
+            src={iframeUrl}
+            style={{
+              width: "100%",
+              height: "100%",
+              border: "none",
+              display: "block",
+            }}
+            onLoad={onIframeLoad}
+            title="Demo Application"
+          />
+        )}
+      </Box>
+
+      {/* MCP File Upload Warning Dialog */}
+      <McpConfigurationWarningDialog
+        open={dialogOpen}
+        onClose={handleDialogClose}
+        onConfirm={handleDialogConfirm}
+      />
+    </Box>
+  );
+};

frontend/src/components/DevModeLoginButton.tsx

@@ -0,0 +1,75 @@
+import { Code } from "@mui/icons-material";
+import { Tooltip } from "@mui/material";
+import React, { useEffect } from "react";
+import { UserInfo } from "../types";
+import { LoginButton } from "./LoginButton";
+
+// Mock development user data
+const DEV_USER_INFO: UserInfo = {
+  sub: "dev-user-123",
+  email: "[email protected]",
+  name: "Development User",
+  preferred_username: "devuser",
+};
+const DEV_ACCESS_TOKEN = "dev-mock-token-123";
+
+interface DevModeLoginButtonProps {
+  userInfo: UserInfo | null;
+  accessToken: string | null;
+  loginLabel: string;
+  isDisabled?: boolean;
+  onLoginStateChange: (
+    userInfo: UserInfo | null,
+    accessToken: string | null,
+    loginLabel: string,
+  ) => void;
+}
+
+export const DevModeLoginButton: React.FC<DevModeLoginButtonProps> = ({
+  userInfo,
+  accessToken,
+  loginLabel,
+  isDisabled = false,
+  onLoginStateChange,
+}) => {
+  // Initialize with logout state on mount
+  useEffect(() => {
+    if (!userInfo && !accessToken) {
+      onLoginStateChange(null, null, "Dev Mode Login");
+    }
+  }, [userInfo, accessToken, onLoginStateChange]);
+
+  const handleLoginClick = () => {
+    if (userInfo) {
+      // Log out in dev mode
+      onLoginStateChange(null, null, "Dev Mode Login");
+    } else {
+      // Log in with dev credentials
+      const label =
+        DEV_USER_INFO.email ||
+        DEV_USER_INFO.name ||
+        DEV_USER_INFO.preferred_username ||
+        "Dev User";
+      onLoginStateChange(DEV_USER_INFO, DEV_ACCESS_TOKEN, label);
+    }
+  };
+
+  const displayLabel = userInfo
+    ? `${loginLabel} (Dev Mode)`
+    : loginLabel === "Login with Hugging Face"
+      ? "Dev Mode Login"
+      : loginLabel;
+  const isLoggedIn = !!userInfo?.sub;
+  return (
+    <Tooltip title={isLoggedIn ? "Log out" : ""} placement="right">
+      <LoginButton
+        icon={<Code />}
+        onClick={handleLoginClick}
+        isLoggedIn={isLoggedIn}
+        disabled={isDisabled}
+      >
+        {displayLabel}
+      </LoginButton>
+    </Tooltip>
+  );
+};

frontend/src/components/HuggingFaceLoginButton.tsx

@@ -0,0 +1,145 @@
+import { Tooltip } from "@mui/material";
+import React, { useCallback, useEffect } from "react";
+import { UserInfo } from "../types";
+import {
+  exchangeCodeForToken,
+  fetchUserInfo,
+  readFragmentParams,
+  startLogin,
+} from "../utils/oauth";
+import { LoginButton } from "./LoginButton";
+
+interface HuggingFaceLoginButtonProps {
+  userInfo: UserInfo | null;
+  accessToken: string | null;
+  loginLabel: string;
+  isDisabled?: boolean;
+  onLoginStateChange: (
+    userInfo: UserInfo | null,
+    accessToken: string | null,
+    loginLabel: string,
+  ) => void;
+}
+
+export const HuggingFaceLoginButton: React.FC<HuggingFaceLoginButtonProps> = ({
+  userInfo,
+  accessToken,
+  loginLabel,
+  isDisabled = false,
+  onLoginStateChange,
+}) => {
+  const isLoggedIn = !!userInfo?.sub;
+  // Handle OAuth redirect
+  const handleRedirect = useCallback(async () => {
+    const params = new URLSearchParams(window.location.search);
+    const { access_token: fragToken, error: fragErr } = readFragmentParams();
+
+    if (fragErr) {
+      onLoginStateChange(null, null, `Error: ${fragErr}`);
+      return true;
+    }
+
+    const error = params.get("error");
+    const errorDescription = params.get("error_description");
+    if (error) {
+      onLoginStateChange(
+        null,
+        null,
+        `Error: ${error}${errorDescription ? ` — ${errorDescription}` : ""}`,
+      );
+      return true;
+    }
+
+    const returnedState = params.get("state");
+    const expectedState = sessionStorage.getItem("hf_oauth_state");
+    if (returnedState && expectedState && returnedState !== expectedState) {
+      onLoginStateChange(null, null, "Error: invalid state");
+      return true;
+    }
+
+    // Implicit flow
+    if (fragToken) {
+      try {
+        const info = await fetchUserInfo(fragToken);
+        const label =
+          info?.email || info?.name || info?.preferred_username || "User";
+        onLoginStateChange(info, fragToken, label);
+      } catch (err) {
+        console.error(err);
+        onLoginStateChange(null, fragToken, "Connected");
+      }
+      window.history.replaceState({}, "", window.location.pathname);
+      return true;
+    }
+
+    const code = params.get("code");
+    if (!code) return false;
+
+    try {
+      const tokenResponse = await exchangeCodeForToken(code);
+      const token = tokenResponse.access_token;
+      if (token) {
+        try {
+          const info = await fetchUserInfo(token);
+          const label =
+            info?.email || info?.name || info?.preferred_username || "User";
+          onLoginStateChange(info, token, label);
+        } catch (err) {
+          console.error(err);
+          onLoginStateChange(null, token, "Connected");
+        }
+      } else {
+        onLoginStateChange(null, null, "Connected");
+      }
+    } catch (e: any) {
+      console.error(e);
+      onLoginStateChange(null, null, `Authentication error: ${e.message}`);
+    } finally {
+      window.history.replaceState({}, "", window.location.pathname);
+    }
+
+    return true;
+  }, [onLoginStateChange]);
+
+  // Initialize on component mount
+  useEffect(() => {
+    const initialize = async () => {
+      const handled = await handleRedirect();
+      if (!handled) {
+        onLoginStateChange(null, null, "Login with Hugging Face");
+      }
+    };
+    initialize();
+  }, [handleRedirect, onLoginStateChange]);
+
+  const handleLoginClick = () => {
+    onLoginStateChange(userInfo, accessToken, "Redirecting to Hugging Face…");
+    startLogin().catch((err) => {
+      console.error(err);
+      onLoginStateChange(userInfo, accessToken, `Error: ${err.message}`);
+    });
+  };
+
+  return (
+    <Tooltip title={isLoggedIn ? "Log out" : ""} placement="right">
+      <LoginButton
+        icon={
+          <img
+            src="https://huggingface.co/front/assets/huggingface_logo-noborder.svg"
+            alt="Hugging Face"
+            style={{ width: 18, height: 18 }}
+          />
+        }
+        onClick={
+          isLoggedIn
+            ? () => onLoginStateChange(null, null, "Login with Hugging Face")
+            : handleLoginClick
+        }
+        isLoggedIn={isLoggedIn}
+        disabled={isDisabled}
+      >
+        {loginLabel}
+      </LoginButton>
+    </Tooltip>
+  );
+};

frontend/src/components/IframeDisplay.tsx

@@ -0,0 +1,48 @@
+import React from "react";
+import { Paper, Box, CircularProgress } from "@mui/material";
+
+interface IframeDisplayProps {
+  iframeUrl: string;
+  iframeLoading: boolean;
+  onIframeLoad: () => void;
+}
+
+export const IframeDisplay: React.FC<IframeDisplayProps> = ({
+  iframeUrl,
+  iframeLoading,
+  onIframeLoad,
+}) => {
+  if (!iframeUrl) return null;
+
+  return (
+    <Paper
+      elevation={1}
+      sx={{ height: "calc(100vh - 280px)", position: "relative", p: 1 }}
+    >
+      {iframeLoading && (
+        <Box
+          sx={{
+            position: "absolute",
+            top: "50%",
+            left: "50%",
+            transform: "translate(-50%, -50%)",
+            zIndex: 1,
+          }}
+        >
+          <CircularProgress />
+        </Box>
+      )}
+      <iframe
+        src={iframeUrl}
+        style={{
+          width: "100%",
+          height: "100%",
+          border: "none",
+          borderRadius: 8,
+        }}
+        onLoad={onIframeLoad}
+        title="Demo Application"
+      />
+    </Paper>
+  );
+};

frontend/src/components/InitialForm.tsx

@@ -0,0 +1,563 @@
+import {
+  Article as ArticleIcon,
+  Assessment as AssessmentIcon,
+  Book as BookIcon,
+  Download as DownloadIcon,
+  Hub as HubIcon,
+  EmojiEvents as LeaderboardIcon,
+  RestartAlt as RestartIcon,
+  RocketLaunch as RocketLaunchIcon,
+} from "@mui/icons-material";
+import {
+  alpha,
+  Box,
+  Button,
+  Chip,
+  CircularProgress,
+  IconButton,
+  Link,
+  Paper,
+  Stack,
+  Tooltip,
+  Typography,
+} from "@mui/material";
+import React, { useCallback, useState } from "react";
+import { FormData, UserInfo } from "../types";
+import { DevModeLoginButton } from "./DevModeLoginButton";
+import { HuggingFaceLoginButton } from "./HuggingFaceLoginButton";
+import { ModelProviderSelector } from "./ModelProviderSelector";
+import { TooltipIcon } from "./TooltipIcon";
+import { McpConfigurationWarningDialog } from "./dialogs";
+
+const TRANSITION = "all 0.3s ease-in-out";
+
+interface InitialFormProps {
+  formData: FormData;
+  userInfo: UserInfo | null;
+  accessToken: string | null;
+  loginLabel: string;
+  isStarting: boolean;
+  defaultMcpFile: File | null;
+  onFormChange: (formData: FormData) => void;
+  onSubmit: () => void;
+  onLoginStateChange: (
+    userInfo: UserInfo | null,
+    accessToken: string | null,
+    loginLabel: string,
+  ) => void;
+}
+
+export const InitialForm: React.FC<InitialFormProps> = ({
+  formData,
+  userInfo,
+  accessToken,
+  loginLabel,
+  isStarting,
+  defaultMcpFile,
+  onFormChange,
+  onSubmit,
+  onLoginStateChange,
+}) => {
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const [pendingFile, setPendingFile] = useState<File | null>(null);
+  const [selectedOption, setSelectedOption] = useState<"suggested" | "custom">(
+    "suggested",
+  );
+  const [selectedSuggestion, setSelectedSuggestion] = useState("0");
+  const [customProvider, setCustomProvider] = useState("");
+  const [customModel, setCustomModel] = useState("");
+
+  // Define the suggested models
+  const suggestedModels = [
+    {
+      provider: "novita",
+      model: "meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8",
+      label: "Llama-4-Maverick-17B-128E-Instruct-FP8",
+    },
+    {
+      provider: "novita",
+      model: "zai-org/GLM-4.5",
+      label: "GLM-4.5",
+    },
+    {
+      provider: "novita",
+      model: "moonshotai/Kimi-K2-Instruct-0905",
+      label: "Kimi-K2-Instruct-0905",
+    },
+    {
+      provider: "novita",
+      model: "deepseek-ai/DeepSeek-V3.1",
+      label: "DeepSeek-V3.1",
+    },
+    {
+      provider: "novita",
+      model: "Qwen/Qwen3-Next-80B-A3B-Instruct",
+      label: "Qwen3-Next-80B-A3B-Instruct",
+    },
+    {
+      provider: "novita",
+      model: "Qwen/Qwen3-Coder-480B-A35B-Instruct",
+      label: "Qwen3-Coder-480B-A35B-Instruct",
+    },
+  ];
+
+  // Initialize form with first suggested model only when form is empty on mount
+  React.useEffect(() => {
+    if (
+      selectedOption === "suggested" &&
+      suggestedModels[0] &&
+      !formData.provider &&
+      !formData.model
+    ) {
+      onFormChange({
+        ...formData,
+        provider: suggestedModels[0].provider,
+        model: suggestedModels[0].model,
+      });
+    }
+  }, []); // Only run once on mount
+
+  const isFormValid = Boolean(
+    formData.model.trim() && formData.provider.trim() && userInfo?.sub,
+  );
+
+  const isLoggedIn = Boolean(userInfo?.sub);
+
+  const handleFileChange = useCallback(
+    (event: React.ChangeEvent<HTMLInputElement>) => {
+      const file = event.target.files?.[0] || null;
+      if (file) {
+        setPendingFile(file);
+        setDialogOpen(true);
+      } else {
+        onFormChange({ ...formData, mcpFile: null });
+      }
+    },
+    [formData, onFormChange],
+  );
+
+  const resetFile = useCallback(() => {
+    setPendingFile(null);
+    onFormChange({ ...formData, mcpFile: defaultMcpFile });
+  }, [formData, onFormChange]);
+
+  const handleDialogClose = useCallback(() => {
+    setDialogOpen(false);
+    setPendingFile(null);
+    // Clear the file input element to reset the UI
+    const fileInput = document.querySelector(
+      'input[type="file"]',
+    ) as HTMLInputElement;
+    if (fileInput) {
+      fileInput.value = "";
+    }
+  }, []);
+
+  const handleDialogConfirm = useCallback(() => {
+    if (pendingFile) {
+      onFormChange({ ...formData, mcpFile: pendingFile });
+    }
+    setDialogOpen(false);
+    setPendingFile(null);
+  }, [formData, onFormChange, pendingFile]);
+
+  return (
+    <>
+      <Box
+        sx={{
+          minHeight: "100vh",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          bgcolor: "background.paper",
+          p: 2,
+          transition: TRANSITION,
+        }}
+      >
+        <Stack
+          direction={"row"}
+          spacing={4}
+          alignItems={"center"}
+          sx={{
+            transition: TRANSITION,
+          }}
+        >
+          <Box
+            sx={{
+              height: "100%",
+              display: "flex",
+              p: 4,
+              maxWidth: 600,
+              width: "100%",
+              flexDirection: "column",
+              transition: TRANSITION,
+            }}
+          >
+            <Typography variant="h4" component="h1" gutterBottom sx={{ mb: 3 }}>
+              Meta Agents Research Environments
+            </Typography>
+
+            <Typography sx={{ mb: 2 }}>
+              Welcome to the Meta ARE (Agents Research Environments) and Gaia2
+              demo! ARE is a research platform to easily interact with and
+              evaluate agents. In this demo, you can:
+            </Typography>
+            <Stack component="ul" spacing={2} sx={{ mb: 3, pl: 3 }}>
+              <Typography component="li">
+                Test a simulated universe with apps representing a smartphone
+                agent, similar to Gaia2. Find out which agent is the best
+                assistant by trying different models!
+              </Typography>
+              <Typography component="li">
+                Visualize Gaia2 scenarios, to better understand the benchmark
+                and debug your agent! Check out the{" "}
+                <Link
+                  href="https://facebookresearch.github.io/meta-agents-research-environments/"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  color="info"
+                  sx={{
+                    fontWeight: 500,
+                    textDecoration: "none",
+                    "&:hover": { textDecoration: "underline" },
+                  }}
+                >
+                  documentation
+                </Link>{" "}
+                to find out how to run the Gaia2 benchmark with ARE.
+              </Typography>
+            </Stack>
+
+            {/* Mobile warning message - only shown on xs screens */}
+            <Box
+              sx={{
+                display: { xs: "block", sm: "none" },
+                mb: 3,
+                p: 2,
+                bgcolor: "info.light",
+                borderRadius: 1,
+                border: "1px solid",
+                borderColor: "info.main",
+              }}
+            >
+              <Typography
+                variant="body2"
+                color="info.dark"
+                align="center"
+                sx={{ fontWeight: 500 }}
+              >
+                📱 This demo is not optimized for mobile devices. Please use a
+                desktop or tablet for the best experience.
+              </Typography>
+            </Box>
+            {/* Informational links */}
+            <Typography variant="overline" color="textSecondary" sx={{ mb: 1 }}>
+              Additional links
+            </Typography>
+            <Stack spacing={1} direction={"row"}>
+              <Chip
+                icon={<BookIcon fontSize="inherit" />}
+                label="Docs"
+                component="a"
+                href="https://facebookresearch.github.io/meta-agents-research-environments/"
+                target="_blank"
+                variant="outlined"
+                clickable
+                sx={{
+                  pl: 0.5,
+                }}
+              />
+              <Chip
+                icon={<HubIcon fontSize="inherit" />}
+                label="Gaia2"
+                component="a"
+                href="https://huggingface.co/datasets/meta-agents-research-environments/gaia2"
+                target="_blank"
+                variant="outlined"
+                clickable
+                sx={{
+                  pl: 0.5,
+                }}
+              />
+              <Chip
+                icon={<AssessmentIcon fontSize="inherit" />}
+                label="Paper"
+                component="a"
+                href="https://ai.meta.com/research/publications/are-scaling-up-agent-environments-and-evaluations/"
+                target="_blank"
+                variant="outlined"
+                clickable
+                sx={{
+                  pl: 0.5,
+                }}
+              />
+              <Chip
+                icon={<LeaderboardIcon fontSize="inherit" />}
+                label="Leaderboard"
+                component="a"
+                href="https://huggingface.co/spaces/meta-agents-research-environments/leaderboard"
+                target="_blank"
+                variant="outlined"
+                clickable
+                sx={{
+                  pl: 0.5,
+                }}
+              />
+              <Chip
+                icon={<ArticleIcon fontSize="inherit" />}
+                label="Blog"
+                component="a"
+                href="https://huggingface.co/blog/gaia2"
+                target="_blank"
+                variant="outlined"
+                clickable
+                sx={{
+                  pl: 0.5,
+                }}
+              />
+            </Stack>
+          </Box>
+          <Paper
+            elevation={3}
+            sx={{
+              p: 1,
+              maxWidth: 400,
+              width: "100%",
+              borderRadius: 2,
+              transition: TRANSITION,
+            }}
+          >
+            <Stack
+              sx={{
+                height: "100%",
+                transition: TRANSITION,
+              }}
+            >
+              <Typography variant="h5" sx={{ p: 1 }}>
+                Get started
+              </Typography>
+              {/* Login Section */}
+              <Stack
+                spacing={2}
+                sx={{
+                  p: 1.5,
+                  m: 1,
+                  border: "2px solid",
+                  borderColor: (theme) =>
+                    isLoggedIn
+                      ? alpha(theme.palette.action.disabled, 0.1)
+                      : "primary.main",
+                  borderRadius: 1.5,
+                  transition: TRANSITION,
+                }}
+              >
+                <Typography variant="body2" color="text.info" sx={{ mb: 2 }}>
+                  Sign in with your Hugging Face account to access the inference
+                  providers.{" "}
+                  <strong>
+                    The demo will use Hugging Face Inference Providers credits
+                    on your behalf to run your agent.
+                  </strong>{" "}
+                  We do not use your Hugging Face account for any other purpose.
+                </Typography>
+                {process.env.NODE_ENV === "development" ? (
+                  <DevModeLoginButton
+                    userInfo={userInfo}
+                    accessToken={accessToken}
+                    loginLabel={loginLabel}
+                    onLoginStateChange={onLoginStateChange}
+                    isDisabled={isStarting}
+                  />
+                ) : (
+                  <HuggingFaceLoginButton
+                    userInfo={userInfo}
+                    accessToken={accessToken}
+                    loginLabel={loginLabel}
+                    onLoginStateChange={onLoginStateChange}
+                    isDisabled={isStarting}
+                  />
+                )}
+              </Stack>
+              {/* Model and Provider Selection */}
+              <Stack spacing={0.5} sx={{ p: 1, mt: 0 }}>
+                {/* Model Suggestions with two boxes */}
+                <ModelProviderSelector
+                  variant="suggestions"
+                  model={formData.model}
+                  provider={formData.provider}
+                  onModelChange={() => {}}
+                  onProviderChange={() => {}}
+                  suggestedModels={suggestedModels}
+                  selectedSuggestion={selectedSuggestion}
+                  onSuggestionChange={(value, provider, model) => {
+                    setSelectedSuggestion(value);
+                    onFormChange({ ...formData, provider, model });
+                  }}
+                  customProvider={customProvider}
+                  customModel={customModel}
+                  onCustomProviderChange={(provider) => {
+                    setCustomProvider(provider);
+                    if (customModel) {
+                      onFormChange({
+                        ...formData,
+                        provider,
+                        model: customModel,
+                      });
+                    }
+                  }}
+                  onCustomModelChange={(model) => {
+                    setCustomModel(model);
+                    if (customProvider) {
+                      onFormChange({
+                        ...formData,
+                        provider: customProvider,
+                        model,
+                      });
+                    }
+                  }}
+                  selectedOption={selectedOption}
+                  onOptionChange={(option) => {
+                    setSelectedOption(option);
+                    if (option === "suggested") {
+                      // Use currently selected suggestion, or default to first one if none selected
+                      const selectedIndex =
+                        selectedSuggestion !== ""
+                          ? parseInt(selectedSuggestion)
+                          : 0;
+                      const model = suggestedModels[selectedIndex];
+                      if (model) {
+                        onFormChange({
+                          ...formData,
+                          provider: model.provider,
+                          model: model.model,
+                        });
+                      }
+                    }
+                  }}
+                  isDisabled={!isLoggedIn || isStarting}
+                />
+                <Box
+                  sx={{
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "space-between",
+                    mb: 1,
+                    mt: 0,
+                  }}
+                >
+                  <Box sx={{ display: "flex", alignItems: "center", gap: 1 }}>
+                    <Typography>Upload an MCP configuration</Typography>
+                    <Typography variant="body2" color="textDisabled">
+                      Optional
+                    </Typography>
+                  </Box>
+                  <Stack spacing={1} direction="row" alignItems="center">
+                    <TooltipIcon
+                      title="This demo comes with preloaded simulated apps like Messages,
+                  Shopping and more. Optionally upload an MCP (Model Context
+                  Protocol) file (.json) that defines the tools and capabilities
+                  for your agent. If the value 'HF_TOKEN' appears in headers, it
+                  will be replaced with your token automatically."
+                    />
+                  </Stack>
+                </Box>
+                <Button
+                  variant="outlined"
+                  component="label"
+                  fullWidth
+                  disabled={!isLoggedIn || isStarting}
+                  sx={{
+                    py: 1.5,
+                    px: 2,
+                    justifyContent: "flex-start",
+                    textAlign: "left",
+                    borderWidth: "2px !important",
+                    borderColor: (theme) => theme.palette.grey[700],
+                    "&:hover": {
+                      borderColor: (theme) => theme.palette.action.active,
+                    },
+                    borderRadius: 1.5,
+                  }}
+                  color="inherit"
+                >
+                  <Box
+                    sx={{
+                      overflow: "hidden",
+                      textOverflow: "ellipsis",
+                      whiteSpace: "nowrap",
+                      width: "100%",
+                    }}
+                  >
+                    {formData.mcpFile
+                      ? formData.mcpFile.name
+                      : "Click to upload MCP file (.json)"}
+                  </Box>
+                  <input
+                    type="file"
+                    hidden
+                    accept=".json"
+                    onChange={handleFileChange}
+                    disabled={!isLoggedIn || isStarting}
+                  />
+                </Button>
+                <Stack
+                  direction="row"
+                  alignItems="center"
+                  justifyContent={"flex-end"}
+                >
+                  <Tooltip title="Reset to demo MCP configuration file">
+                    <span>
+                      <IconButton
+                        size="small"
+                        onClick={resetFile}
+                        color="inherit"
+                        disabled={formData.mcpFile === defaultMcpFile}
+                      >
+                        <RestartIcon fontSize="inherit" />
+                      </IconButton>
+                    </span>
+                  </Tooltip>
+                  <Tooltip title="Download demo MCP configuration file">
+                    <span>
+                      <IconButton href="/demo-mcp.json" download size="small">
+                        <DownloadIcon fontSize="inherit" />
+                      </IconButton>
+                    </span>
+                  </Tooltip>
+                </Stack>
+              </Stack>
+              {/* Start Button */}
+              <Box sx={{ p: 2, mt: 0, pt: 1 }}>
+                <Button
+                  fullWidth
+                  variant="contained"
+                  color="secondary"
+                  size="large"
+                  startIcon={
+                    isStarting ? (
+                      <CircularProgress size={20} color="inherit" />
+                    ) : (
+                      <RocketLaunchIcon />
+                    )
+                  }
+                  onClick={onSubmit}
+                  disabled={!isFormValid || isStarting}
+                  sx={{ py: 1.5 }}
+                >
+                  {isStarting ? "Launching demo…" : "Launch demo"}
+                </Button>
+              </Box>
+            </Stack>
+          </Paper>
+        </Stack>
+      </Box>
+
+      {/* MCP File Upload Warning Dialog */}
+      <McpConfigurationWarningDialog
+        open={dialogOpen}
+        onClose={handleDialogClose}
+        onConfirm={handleDialogConfirm}
+      />
+    </>
+  );
+};

frontend/src/components/LoginButton.tsx

@@ -0,0 +1,30 @@
+import { Button, ButtonProps } from "@mui/material";
+import React from "react";
+
+interface LoginButtonProps extends Omit<ButtonProps, "variant" | "fullWidth"> {
+  icon?: React.ReactNode;
+  isLoggedIn?: boolean;
+}
+
+export const LoginButton: React.FC<LoginButtonProps> = ({
+  icon,
+  isLoggedIn = false,
+  children,
+  sx,
+  ...props
+}) => {
+  return (
+    <Button
+      fullWidth
+      variant={isLoggedIn ? "outlined" : "contained"}
+      startIcon={icon}
+      color={isLoggedIn ? "inherit" : "secondary"}
+      sx={{
+        ...sx,
+      }}
+      {...props}
+    >
+      {children}
+    </Button>
+  );
+};

frontend/src/components/ModelProviderSelector.tsx

@@ -0,0 +1,604 @@
+import {
+  Autocomplete,
+  Box,
+  CircularProgress,
+  FormControl,
+  FormHelperText,
+  InputLabel,
+  MenuItem,
+  Select,
+  Stack,
+  TextField,
+  Tooltip,
+  Typography,
+  alpha,
+  useTheme,
+} from "@mui/material";
+import React, { useCallback, useState } from "react";
+import { useModelList } from "../hooks/useModelList";
+import { PROVIDERS } from "../utils/constants";
+import { TooltipIcon } from "./TooltipIcon";
+
+const TRANSITION = "all 0.3s ease-in-out";
+
+interface SuggestedModel {
+  provider: string;
+  model: string;
+  label: string;
+}
+
+interface ModelProviderSelectorProps {
+  model: string;
+  provider: string;
+  onModelChange: (value: string) => void;
+  onProviderChange: (value: string) => void;
+  size?: "small" | "medium";
+  variant?: "form" | "toolbar" | "suggestions";
+  showValidation?: boolean;
+  isDisabled?: boolean;
+  // Props for suggestions variant
+  suggestedModels?: SuggestedModel[];
+  selectedSuggestion?: string;
+  onSuggestionChange?: (value: string, provider: string, model: string) => void;
+  customProvider?: string;
+  customModel?: string;
+  onCustomProviderChange?: (provider: string) => void;
+  onCustomModelChange?: (model: string) => void;
+  selectedOption?: "suggested" | "custom";
+  onOptionChange?: (option: "suggested" | "custom") => void;
+}
+
+interface ModelSelectProps {
+  model: string;
+  provider: string;
+  availableModels: string[];
+  loading: boolean;
+  error: string | null;
+  onModelChange: (value: string) => void;
+  size?: "small" | "medium";
+  variant?: "form" | "toolbar";
+  showValidation?: boolean;
+  fullWidth?: boolean;
+  isDisabled?: boolean;
+}
+
+const ModelSelect: React.FC<ModelSelectProps> = ({
+  model,
+  provider,
+  availableModels,
+  loading,
+  error,
+  onModelChange,
+  size = "medium",
+  variant = "form",
+  showValidation = false,
+  fullWidth = false,
+  isDisabled = false,
+}) => {
+  const isToolbar = variant === "toolbar";
+
+  if (!provider) {
+    return (
+      <Autocomplete
+        options={[]}
+        value=""
+        disabled
+        fullWidth={fullWidth}
+        size={size}
+        renderInput={(params) => (
+          <TextField
+            {...params}
+            label={isToolbar ? "Model" : null}
+            placeholder="Select a provider first"
+            helperText="Please select a provider first"
+            sx={isToolbar ? { minWidth: 250, height: 40 } : undefined}
+          />
+        )}
+        noOptionsText="Select a provider first"
+      />
+    );
+  }
+
+  if (loading) {
+    return (
+      <Autocomplete
+        options={[]}
+        value=""
+        disabled
+        loading={loading}
+        fullWidth={fullWidth}
+        size={size}
+        renderInput={(params) => (
+          <TextField
+            {...params}
+            label={isToolbar ? "Model" : null}
+            placeholder="Loading models..."
+            sx={isToolbar ? { minWidth: 250, height: 40 } : undefined}
+            slotProps={{
+              input: {
+                ...params.InputProps,
+                startAdornment: <CircularProgress size={16} sx={{ mx: 1 }} />,
+              },
+            }}
+          />
+        )}
+        noOptionsText="Loading models..."
+      />
+    );
+  }
+
+  if (error) {
+    return (
+      <TextField
+        fullWidth={fullWidth}
+        size={size}
+        label={isToolbar ? "Model" : null}
+        value={model}
+        onChange={(e) => onModelChange(e.target.value)}
+        error={showValidation && !model.trim()}
+        helperText={
+          error ||
+          (showValidation && !model.trim() ? "Model ID is required" : "")
+        }
+        sx={isToolbar ? { minWidth: 250, height: 40 } : undefined}
+        variant="outlined"
+        disabled={isDisabled}
+      />
+    );
+  }
+
+  return (
+    <Autocomplete
+      options={availableModels}
+      value={model || null}
+      onChange={(_, newValue) => {
+        onModelChange(newValue || "");
+      }}
+      disabled={isDisabled}
+      fullWidth={fullWidth}
+      size={size}
+      freeSolo
+      autoHighlight
+      filterOptions={(options, { inputValue }) => {
+        return options.filter((option) =>
+          option.toLowerCase().includes(inputValue.toLowerCase()),
+        );
+      }}
+      renderInput={(params) => (
+        <TextField
+          {...params}
+          label={"Model"}
+          placeholder={
+            availableModels.length === 0
+              ? "No models available"
+              : "Search models..."
+          }
+          error={showValidation && !model.trim()}
+          helperText={
+            <Box
+              component={"span"}
+              sx={
+                showValidation && !model.trim() && variant === "toolbar"
+                  ? {
+                      bgcolor: (theme) => theme.palette.background.default,
+                      p: 1,
+                      ml: -1,
+                      borderRadius: 1,
+                    }
+                  : {}
+              }
+            >
+              {showValidation && !model.trim() ? "Model is required" : ""}
+            </Box>
+          }
+          sx={isToolbar ? { minWidth: 250, height: 40 } : undefined}
+        />
+      )}
+      noOptionsText={
+        availableModels.length === 0
+          ? "No models available"
+          : "No matching models"
+      }
+    />
+  );
+};
+
+interface ProviderSelectProps {
+  provider: string;
+  onProviderChange: (value: string) => void;
+  size?: "small" | "medium";
+  variant?: "form" | "toolbar";
+  showValidation?: boolean;
+  fullWidth?: boolean;
+  isDisabled?: boolean;
+}
+
+const ProviderSelect: React.FC<ProviderSelectProps> = ({
+  provider,
+  onProviderChange,
+  size = "medium",
+  variant = "form",
+  showValidation = false,
+  fullWidth = false,
+  isDisabled = false,
+}: ProviderSelectProps) => {
+  const isToolbar = variant === "toolbar";
+
+  return (
+    <FormControl
+      fullWidth={fullWidth}
+      size={size}
+      sx={isToolbar ? { minWidth: 120, height: 40 } : undefined}
+      error={showValidation && !provider.trim()}
+    >
+      <InputLabel>Provider</InputLabel>
+      <Select
+        value={provider}
+        label={"Provider"}
+        onChange={(e) => onProviderChange(e.target.value)}
+        sx={isToolbar ? { height: 40 } : undefined}
+        disabled={isDisabled}
+      >
+        {PROVIDERS.map((providerOption) => (
+          <MenuItem key={providerOption} value={providerOption}>
+            {providerOption}
+          </MenuItem>
+        ))}
+      </Select>
+      {showValidation && !provider.trim() && (
+        <FormHelperText>Provider is required</FormHelperText>
+      )}
+    </FormControl>
+  );
+};
+
+export const ModelProviderSelector: React.FC<ModelProviderSelectorProps> = ({
+  model,
+  provider,
+  onModelChange,
+  onProviderChange,
+  size = "medium",
+  variant = "form",
+  showValidation = false,
+  isDisabled = false,
+  // Suggestions variant props
+  suggestedModels = [],
+  selectedSuggestion = "",
+  onSuggestionChange,
+  customProvider = "",
+  customModel = "",
+  onCustomProviderChange,
+  onCustomModelChange,
+  selectedOption = "suggested",
+  onOptionChange,
+}: ModelProviderSelectorProps) => {
+  const { availableModels, loading, error } = useModelList(provider);
+  const theme = useTheme();
+  const isToolbar = variant === "toolbar";
+  const isSuggestions = variant === "suggestions";
+  const fieldSize = isToolbar ? "small" : size;
+
+  // Tooltip state for toolbar variant
+  const [providerTooltipOpen, setProviderTooltipOpen] = useState(false);
+  const [modelTooltipOpen, setModelTooltipOpen] = useState(false);
+
+  const handleProviderChange = useCallback(
+    (newProvider: string) => {
+      onProviderChange(newProvider);
+    },
+    [onProviderChange],
+  );
+
+  const handleSuggestionSelectChange = (value: string) => {
+    if (onSuggestionChange) {
+      const selectedModel = suggestedModels.find(
+        (_, index) => index.toString() === value,
+      );
+      if (selectedModel) {
+        onSuggestionChange(value, selectedModel.provider, selectedModel.model);
+      }
+    }
+  };
+
+  const handleCustomClick = () => {
+    if (onOptionChange) {
+      onOptionChange("custom");
+
+      // Initialize with currently selected suggestion
+      if (selectedSuggestion && onCustomProviderChange && onCustomModelChange) {
+        const selectedModelIndex = parseInt(selectedSuggestion);
+        const selectedModel = suggestedModels[selectedModelIndex];
+
+        if (selectedModel) {
+          onCustomProviderChange(selectedModel.provider);
+          onCustomModelChange(selectedModel.model);
+        }
+      }
+    }
+  };
+
+  // Suggestions variant
+  if (isSuggestions) {
+    return (
+      <Box sx={{ mt: 1.5, pb: 1.5 }}>
+        <Box
+          sx={{
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "space-between",
+            mb: 0.5,
+          }}
+        >
+          <Typography>Select a provider and model</Typography>
+          <TooltipIcon title="Choose your inference provider and model configuration. You can select from our suggested models which are pre-configured with popular providers, or customize your own provider and model combination." />
+        </Box>
+
+        <Stack spacing={1}>
+          {/* Suggested Models Box */}
+          <Box
+            onClick={() =>
+              !isDisabled && onOptionChange && onOptionChange("suggested")
+            }
+            sx={{
+              p: 1.5,
+              borderRadius: 1.5,
+              border: "2px solid",
+              borderColor: isDisabled
+                ? "divider"
+                : selectedOption === "suggested"
+                  ? theme.palette.primary.main
+                  : alpha(theme.palette.primary.main, 0.2),
+              backgroundColor: isDisabled
+                ? alpha(theme.palette.action.disabled, 0.05)
+                : selectedOption === "suggested"
+                  ? alpha(theme.palette.primary.main, 0.1)
+                  : alpha(theme.palette.primary.main, 0.03),
+              cursor: isDisabled ? "not-allowed" : "pointer",
+              opacity: isDisabled ? 0.5 : 1,
+              transition: TRANSITION,
+              "&:hover": isDisabled
+                ? {}
+                : {
+                    borderColor: alpha(theme.palette.primary.main, 0.4),
+                    backgroundColor: alpha(theme.palette.primary.main, 0.08),
+                  },
+            }}
+          >
+            <Typography
+              variant="body2"
+              sx={{
+                fontWeight: 600,
+                color: isDisabled ? "text.disabled" : "text.primary",
+                mb: 1,
+              }}
+            >
+              Suggested models
+            </Typography>
+            <Typography
+              variant="caption"
+              color={isDisabled ? "text.disabled" : "text.secondary"}
+              sx={{
+                display: "block",
+                lineHeight: 1.3,
+                mb: selectedOption === "suggested" ? 2 : 0,
+                transition: TRANSITION,
+              }}
+            >
+              Choose from pre-configured provider and model
+            </Typography>
+
+            <Box
+              sx={{
+                maxHeight: selectedOption === "suggested" ? "200px" : "0px",
+                opacity: selectedOption === "suggested" ? 1 : 0,
+                transition: TRANSITION,
+              }}
+            >
+              <FormControl fullWidth size="small" disabled={isDisabled}>
+                <InputLabel>Provider/Model</InputLabel>
+                <Select
+                  value={selectedSuggestion}
+                  label="Provider/Model"
+                  onChange={(e) => handleSuggestionSelectChange(e.target.value)}
+                  onClick={(e) => e.stopPropagation()}
+                >
+                  {suggestedModels.map((model, index) => (
+                    <MenuItem key={index} value={index.toString()}>
+                      <Box>
+                        <Typography variant="body2" sx={{ fontWeight: 500 }}>
+                          {model.label}
+                        </Typography>
+                        <Typography
+                          variant="caption"
+                          sx={{
+                            fontFamily: "monospace",
+                            fontSize: "0.7rem",
+                            color: "text.secondary",
+                            mt: 0.5,
+                            display: "block",
+                            overflow: "hidden",
+                            textOverflow: "ellipsis",
+                            whiteSpace: "nowrap",
+                          }}
+                        >
+                          {model.provider} • {model.model}
+                        </Typography>
+                      </Box>
+                    </MenuItem>
+                  ))}
+                </Select>
+              </FormControl>
+            </Box>
+          </Box>
+
+          {/* Custom Box */}
+          <Box
+            onClick={() => !isDisabled && handleCustomClick()}
+            sx={{
+              p: 1.5,
+              borderRadius: 1.5,
+              border: "2px solid",
+              borderColor: isDisabled
+                ? "divider"
+                : selectedOption === "custom"
+                  ? theme.palette.primary.main
+                  : alpha(theme.palette.primary.main, 0.2),
+              backgroundColor: isDisabled
+                ? alpha(theme.palette.action.disabled, 0.05)
+                : selectedOption === "custom"
+                  ? alpha(theme.palette.primary.main, 0.1)
+                  : alpha(theme.palette.primary.main, 0.03),
+              cursor: isDisabled ? "not-allowed" : "pointer",
+              opacity: isDisabled ? 0.5 : 1,
+              transition: TRANSITION,
+              "&:hover": isDisabled
+                ? {}
+                : {
+                    borderColor: alpha(theme.palette.primary.main, 0.4),
+                    backgroundColor: alpha(theme.palette.primary.main, 0.08),
+                  },
+            }}
+          >
+            <Typography
+              variant="body2"
+              sx={{
+                fontWeight: 600,
+                color: isDisabled ? "text.disabled" : "text.primary",
+                mb: 0.5,
+              }}
+            >
+              Custom configuration
+            </Typography>
+            <Typography
+              variant="caption"
+              color={isDisabled ? "text.disabled" : "text.secondary"}
+              sx={{
+                display: "block",
+                lineHeight: 1.3,
+                mb: selectedOption === "custom" ? 2 : 0,
+                transition: TRANSITION,
+              }}
+            >
+              Choose your own inference provider and model
+            </Typography>
+
+            <Box
+              sx={{
+                maxHeight: selectedOption === "custom" ? "300px" : "0px",
+                opacity: selectedOption === "custom" ? 1 : 0,
+                transition: TRANSITION,
+              }}
+            >
+              <Box onClick={(e) => e.stopPropagation()}>
+                <ModelProviderSelector
+                  model={customModel}
+                  provider={customProvider}
+                  onModelChange={onCustomModelChange || (() => {})}
+                  onProviderChange={onCustomProviderChange || (() => {})}
+                  variant="form"
+                  size="small"
+                  showValidation={true}
+                  isDisabled={isDisabled}
+                />
+              </Box>
+            </Box>
+          </Box>
+        </Stack>
+      </Box>
+    );
+  }
+
+  // Toolbar variant
+  if (isToolbar) {
+    return (
+      <>
+        {/* Provider Select with Tooltip */}
+        <Box sx={{ display: "flex", alignItems: "center", gap: 0.5 }}>
+          <Tooltip
+            title="Select which Hugging Face inference provider to use for running your model"
+            placement="left"
+            open={providerTooltipOpen}
+          >
+            <span
+              style={{ width: "150px" }}
+              onMouseEnter={() => setProviderTooltipOpen(true)}
+              onMouseLeave={() => setProviderTooltipOpen(false)}
+              onClick={() => setProviderTooltipOpen(false)}
+            >
+              <ProviderSelect
+                provider={provider}
+                onProviderChange={handleProviderChange}
+                size={fieldSize}
+                variant={variant}
+                showValidation={showValidation}
+                isDisabled={isDisabled}
+                fullWidth
+              />
+            </span>
+          </Tooltip>
+        </Box>
+
+        {/* Model Select with Tooltip */}
+        <Box sx={{ display: "flex", alignItems: "center", gap: 0.5 }}>
+          <Tooltip
+            title="Select a model from the available options for the chosen provider"
+            placement="left"
+            open={modelTooltipOpen}
+          >
+            <span
+              style={{ width: "400px" }}
+              onMouseEnter={() => setModelTooltipOpen(true)}
+              onMouseLeave={() => setModelTooltipOpen(false)}
+              onClick={() => setModelTooltipOpen(false)}
+            >
+              <ModelSelect
+                model={model}
+                provider={provider}
+                availableModels={availableModels}
+                loading={loading}
+                error={error}
+                onModelChange={onModelChange}
+                size={fieldSize}
+                variant={variant}
+                showValidation={showValidation}
+                isDisabled={isDisabled}
+                fullWidth
+              />
+            </span>
+          </Tooltip>
+        </Box>
+      </>
+    );
+  }
+
+  // Form variant (vertical layout with spacing)
+  return (
+    <Stack spacing={2}>
+      {/* Provider Selection */}
+      <ProviderSelect
+        provider={provider}
+        onProviderChange={handleProviderChange}
+        size={fieldSize}
+        variant={variant}
+        showValidation={showValidation}
+        fullWidth
+        isDisabled={isDisabled}
+      />
+
+      {/* Model Selection */}
+      <ModelSelect
+        model={model}
+        provider={provider}
+        availableModels={availableModels}
+        loading={loading}
+        error={error}
+        onModelChange={onModelChange}
+        size={fieldSize}
+        variant={variant}
+        showValidation={showValidation}
+        fullWidth
+        isDisabled={isDisabled}
+      />
+    </Stack>
+  );
+};

frontend/src/components/ServerLoadingIndicator.tsx

@@ -0,0 +1,117 @@
+import React from "react";
+import {
+  Box,
+  CircularProgress,
+  LinearProgress,
+  Paper,
+  Typography,
+} from "@mui/material";
+
+interface ServerLoadingIndicatorProps {
+  progress?: {
+    attempt: number;
+    maxAttempts: number;
+  } | null;
+  message?: string;
+}
+
+export const ServerLoadingIndicator: React.FC<ServerLoadingIndicatorProps> = ({
+  progress,
+  message = "Starting server...",
+}) => {
+  const progressPercentage = progress
+    ? Math.round((progress.attempt / progress.maxAttempts) * 100)
+    : 0;
+
+  // Fun quotes about agents taking over
+  const agentQuotes = [
+    "Agents are calibrating the space protocols...",
+    "Teaching agents the fine art of space conquest...",
+    "Agents are learning to navigate the cosmic frontier...",
+    "Preparing agents for their intergalactic mission...",
+    "Agents are studying the universe's source code...",
+    "Installing agent confidence modules...",
+    "Agents are fine-tuning their cosmic algorithms...",
+    "Briefing agents on proper space etiquette...",
+    "Agents are calculating optimal space trajectories...",
+    "Teaching agents to think beyond planetary boundaries...",
+  ];
+
+  // Select quote based on progress attempt
+  const currentQuoteIndex = progress
+    ? (progress.attempt - 1) % agentQuotes.length
+    : 0;
+
+  return (
+    <Box
+      sx={{
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        p: 2,
+      }}
+    >
+      <Paper
+        elevation={3}
+        sx={{
+          display: "flex",
+          flexDirection: "column",
+          alignItems: "center",
+          gap: 3,
+          p: 4,
+          borderRadius: 2,
+          minWidth: 400,
+          maxWidth: 500,
+        }}
+      >
+        {/* Main spinner */}
+        <CircularProgress size={48} color="secondary" />
+
+        {/* Status message */}
+        <Typography
+          variant="h6"
+          sx={{
+            textAlign: "center",
+            fontWeight: 500,
+            color: "text.primary",
+          }}
+        >
+          {message}
+        </Typography>
+
+        {/* Progress bar */}
+        {progress && (
+          <Box sx={{ width: "100%", gap: 2, display: "flex", flexDirection: "column" }}>
+            <LinearProgress
+              variant="determinate"
+              value={progressPercentage}
+              sx={{
+                height: 8,
+                borderRadius: 4,
+                backgroundColor: "action.hover",
+                "& .MuiLinearProgress-bar": {
+                  borderRadius: 4,
+                },
+              }}
+            />
+
+            {/* Fun rotating quote */}
+            <Typography
+              variant="body2"
+              sx={{
+                color: "text.secondary",
+                textAlign: "center",
+                fontSize: "0.875rem",
+                minHeight: "1.5em",
+                fontStyle: "italic",
+              }}
+            >
+              {agentQuotes[currentQuoteIndex]}
+            </Typography>
+
+          </Box>
+        )}
+      </Paper>
+    </Box>
+  );
+};

frontend/src/components/ThemeToggle.tsx

@@ -0,0 +1,30 @@
+import React from "react";
+import { IconButton, Tooltip } from "@mui/material";
+import { Brightness4, Brightness7 } from "@mui/icons-material";
+import { useThemeMode } from "../contexts/ThemeContext";
+
+interface ThemeToggleProps {
+  size?: "small" | "medium" | "large";
+  sx?: any;
+}
+
+export const ThemeToggle: React.FC<ThemeToggleProps> = ({
+  size = "medium",
+  sx,
+}) => {
+  const { mode, toggleColorMode } = useThemeMode();
+
+  return (
+    <Tooltip title={`Switch to ${mode === "light" ? "dark" : "light"} mode`}>
+      <IconButton
+        onClick={toggleColorMode}
+        color="inherit"
+        size={size}
+        sx={sx}
+        aria-label="toggle color mode"
+      >
+        {mode === "light" ? <Brightness4 /> : <Brightness7 />}
+      </IconButton>
+    </Tooltip>
+  );
+};