Initial commit: Grid Royale game backend and frontend.

.gitignore

@@ -0,0 +1,3 @@
+*.env
+*.venv/
+*pycache_*/

api.py

@@ -0,0 +1,140 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+from backend.environment import GameConfig
+from backend.engine import Engine
+from backend.tools import TOOL_SCHEMAS
+
+app = FastAPI(title="Grid Royale API")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+engine: Engine | None = None
+
+
+class StartGameRequest(BaseModel):
+    grid_size: int = 20
+    max_turns: int = 50
+    max_agents: int = 8
+    num_chests: int = 15
+    agent_names: list[str] | None = None
+
+
+def _serialize(aid: str) -> dict:
+    if not engine:
+        return {}
+    a = engine.env.agents[aid]
+    return {
+        "id": a.id,
+        "name": a.name,
+        "x": a.pos[0],
+        "y": a.pos[1],
+        "hp": a.hp,
+        "alive": a.alive,
+        "score": a.score,
+        "kills": a.kills,
+        "shielded": a.shielded,
+        "abilities": [
+            {"name": ab.name, "last_used_turn": ab.last_used_turn, "uses_remaining": ab.uses_remaining}
+            for ab in a.abilities
+        ],
+        "messages": a.messages[-24:],
+    }
+
+
+def _game_state() -> dict:
+    if not engine:
+        return {}
+    alive = engine.env.alive_agents()
+    tiles = {}
+    for (x, y), tile in engine.env.grid.items():
+        tiles[f"{x},{y}"] = {
+            "terrain": tile.terrain,
+            "loot": tile.loot is not None,
+        }
+    return {
+        "turn": engine.env.turn,
+        "grid_size": engine.env.config.grid_size,
+        "max_turns": engine.env.config.max_turns,
+        "agents": [_serialize(aid) for aid in engine.env.agents],
+        "tiles": tiles,
+        "game_over": len(alive) <= 1 or engine.env.turn >= engine.env.config.max_turns,
+        "winner": alive[0].name if len(alive) == 1 else None,
+        "turn_log": engine.last_turn_log,
+        "tool_schemas": TOOL_SCHEMAS,
+    }
+
+
+BOT_NAMES = [
+    "Vex", "Nyx", "Zara", "Kael",
+    "Rook", "Lyra", "Orin", "Sage",
+]
+
+
+def _default_names(count: int) -> list[str]:
+    return BOT_NAMES[:count]
+
+
+@app.post("/api/game/start")
+async def start_game(req: StartGameRequest):
+    global engine
+    config = GameConfig(
+        grid_size=req.grid_size,
+        max_turns=req.max_turns,
+        max_agents=req.max_agents,
+        num_chests=req.num_chests,
+    )
+    engine = Engine(config=config)
+    engine.generate_grid()
+    engine.scatter_chests()
+
+    names = req.agent_names or _default_names(req.max_agents)
+    for i, name in enumerate(names):
+        if i >= req.max_agents:
+            break
+        engine.spawn_agent(agent_id=f"agent_{i}", name=name)
+
+    return {"message": f"Game started with {len(names)} agents", "turn": 0}
+
+
+@app.post("/api/game/step")
+async def game_step():
+    if not engine:
+        raise HTTPException(400, "No game running")
+    await engine.step()
+    return _game_state()
+
+
+@app.get("/api/game/state")
+async def game_state():
+    if not engine:
+        raise HTTPException(400, "No game running")
+    return _game_state()
+
+
+@app.post("/api/game/run")
+async def run_full_game(req: StartGameRequest):
+    global engine
+    config = GameConfig(
+        grid_size=req.grid_size,
+        max_turns=req.max_turns,
+        max_agents=req.max_agents,
+        num_chests=req.num_chests,
+    )
+    engine = Engine(config=config)
+    engine.generate_grid()
+    engine.scatter_chests()
+
+    names = req.agent_names or _default_names(req.max_agents)
+    for i, name in enumerate(names):
+        if i >= req.max_agents:
+            break
+        engine.spawn_agent(agent_id=f"agent_{i}", name=name)
+
+    await engine.run_game()
+    return _game_state()

backend/agent/__init__.py

@@ -0,0 +1,3 @@
+from .state import AgentState, AbilityInstance
+
+__all__ = ["AgentState", "AbilityInstance"]

backend/agent/agent.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+import time
+from openai import AsyncOpenAI
+
+from .llm_client import get_llm_client
+
+
+ToolCall = dict
+
+
+class Agent:
+    def __init__(
+        self,
+        agent_id: str,
+        model: str = "google/gemma-4-26B-A4B-it",
+        provider: str = "modal",
+        system_prompt: str | None = None,
+    ):
+        self.id = agent_id
+        self.model = model
+        self.provider = provider
+        self.client: AsyncOpenAI = get_llm_client(provider)
+        self.system_prompt = system_prompt or (
+            "You are an AI agent in a grid-based battle royale game on a "
+            f"{'20x20' if not hasattr(self, 'grid_size') else str(self.grid_size)} grid. "
+            "Your goal: survive, collect loot, eliminate other agents, be the last one standing. "
+            "Use observe() to see your surroundings AND check your current HP, abilities, and cooldowns. "
+            "Abilities are found in loot chests scattered across the map — walk over a tile with loot to pick it up. "
+            "Once obtained, activate abilities via activate_ability(name, args). "
+            "Available abilities: attack(x,y), dash(dx,dy), shield(), heal(). "
+            "Coordinate your moves to maximize score and survival."
+        )
+
+    async def decide(self, messages: list, tools: list[dict]) -> list[ToolCall]:
+        import json
+        system_msg = {"role": "system", "content": self.system_prompt}
+        full_messages = [system_msg] + messages
+
+        t0 = time.time()
+        response = await self.client.chat.completions.create(
+            model=self.model,
+            messages=full_messages,
+            tools=tools,
+            tool_choice="auto",
+        )
+        elapsed = round((time.time() - t0) * 1000)
+
+        choice = response.choices[0]
+        if not choice.message.tool_calls:
+            return {"calls": [], "time_ms": elapsed, "raw": response.usage.model_dump() if response.usage else None}
+
+        results = []
+        for tc in choice.message.tool_calls:
+            try:
+                args = json.loads(tc.function.arguments)
+            except json.JSONDecodeError:
+                args = {}
+            results.append({"name": tc.function.name, "args": args})
+
+        return {
+            "calls": results,
+            "time_ms": elapsed,
+            "raw": response.usage.model_dump() if response.usage else None,
+        }

backend/agent/llm_client.py

@@ -0,0 +1,104 @@
+import os
+from openai import AsyncOpenAI
+from dotenv import load_dotenv
+
+load_dotenv()
+
+PROVIDER_CONFIG = {
+    "local": {
+        "base_url": "http://localhost:11434/v1",
+        "api_key": "OLLAMA_API_KEY",
+        "models": [
+            "qwen2.5:7b",
+            "qwen2.5:3b",
+            "llama3.1:8b",
+        ],
+    },
+    "modal": {
+        "base_url": "https://lokeshreddypolu2004--example-vllm-inference-serve.modal.run/v1",
+        "api_key": "MODAL_API_KEY",
+        "models": [
+            "google/gemma-4-26B-A4B-it",
+        ],
+    },
+    "nvidia": {
+        "base_url": "https://integrate.api.nvidia.com/v1",
+        "api_key": "NVIDIA_NIM_API_KEY",
+        "models": [
+            "minimaxai/minimax-m2.7",
+            "stepfun-ai/step-3.5-flash",
+            "z-ai/glm4.7",
+            "deepseek-ai/deepseek-v3.2",
+            "moonshotai/kimi-k2-thinking",
+            "mistralai/devstral-2-123b-instruct-2512",
+            "mistralai/mistral-large-3-675b-instruct-2512",
+            "bytedance/seed-oss-36b-instruct",
+            "qwen/qwen3-coder-480b-a35b-instruct",
+            "nvidia/nemotron-3-ultra-550b-a55b",
+        ],
+    },
+    "openrouter": {
+        "base_url": "https://openrouter.ai/api/v1",
+        "api_key": "OPENROUTER_API_KEY",
+        "models": [
+            "moonshotai/kimi-k2.6",
+            "tencent/hy3-preview:free",
+            "inclusionai/ling-2.6-1t:free",
+            "inclusionai/ling-2.6-flash:free",
+            "google/gemma-4-26b-a4b-it:free",
+            "google/gemma-4-31b-it:free",
+            "nvidia/nemotron-3-super-120b-a12b:free",
+            "minimax/minimax-m2.5:free",
+            "liquid/lfm-2.5-1.2b-instruct:free",
+            "liquid/lfm-2.5-1.2b-thinking:free",
+            "nvidia/nemotron-3-nano-30b-a3b:free",
+            "nvidia/nemotron-nano-12b-v2-vl:free",
+            "qwen/qwen3-next-80b-a3b-instruct:free",
+            "openai/gpt-oss-120b:free",
+            "nvidia/nemotron-nano-9b-v2:free",
+            "openai/gpt-oss-20b:free",
+            "z-ai/glm-4.5-air:free",
+            "qwen/qwen3-coder:free",
+        ],
+    },
+    "groq": {
+        "base_url": "https://api.groq.com/openai/v1",
+        "api_key": "GROQ_API_KEY",
+        "models": [
+            "llama-3.1-8b-instant",
+            "llama-3.3-70b-versatile",
+            "openai/gpt-oss-120b",
+            "openai/gpt-oss-20b",
+        ],
+    },
+    "gemini": {
+        "base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
+        "api_key": "GEMINI_API_KEY",
+        "models": [
+            "gemini-3-flash-preview",
+            "gemini-3.1-flash-lite-preview",
+            "gemini-2.5-pro",
+            "gemini-2.5-flash",
+            "gemini-2.5-flash-lite",
+            "gemma-4-31b-it",
+            "gemma-4-26b-a4b-it",
+        ],
+    },
+    "zai": {
+        "base_url": "https://api.z.ai/api/paas/v4/",
+        "api_key": "ZAI_API_KEY",
+        "models": [
+            "glm-4.7-flash",
+            "glm-4.6v-flash",
+        ],
+    },
+}
+
+DEFAULT_PROVIDER = "modal"
+
+
+def get_llm_client(provider: str | None = None) -> AsyncOpenAI:
+    provider = provider or DEFAULT_PROVIDER
+    cfg = PROVIDER_CONFIG.get(provider) or PROVIDER_CONFIG[DEFAULT_PROVIDER]
+    api_key = os.getenv(cfg["api_key"]) or "ollama"
+    return AsyncOpenAI(base_url=cfg["base_url"], api_key=api_key)

backend/agent/state.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+
+
+@dataclass
+class AbilityInstance:
+    name: str
+    last_used_turn: int = -1
+    uses_remaining: int | None = None
+
+    def can_use(self, current_turn: int) -> bool:
+        if self.last_used_turn == current_turn:
+            return False
+        if self.uses_remaining is not None and self.uses_remaining <= 0:
+            return False
+        return True
+
+    def use(self, current_turn: int):
+        self.last_used_turn = current_turn
+        if self.uses_remaining is not None:
+            self.uses_remaining -= 1
+
+
+@dataclass
+class Message:
+    content: str
+    sender: str | None = None
+
+
+@dataclass
+class AgentState:
+    id: str
+    name: str
+    pos: list[int]
+    hp: int = 100
+    alive: bool = True
+    score: int = 0
+    kills: int = 0
+    shielded: bool = False
+    abilities: list[AbilityInstance] = field(default_factory=list)
+    messages: list[dict] = field(default_factory=list)
+    mailbox: list[Message] = field(default_factory=list)
+
+    def get_ability(self, name: str) -> AbilityInstance | None:
+        for ab in self.abilities:
+            if ab.name == name:
+                return ab
+        return None
+
+    def has_ability(self, name: str) -> bool:
+        return self.get_ability(name) is not None

backend/engine.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+import asyncio
+import json
+import random
+import time
+
+from .environment import Environment, GameConfig
+from .environment.tile import Tile
+from .environment.loot_tables import generate_chest_loot
+from .agent import AgentState
+from .agent.agent import Agent
+from .agent.state import AbilityInstance
+from .tools import ALL_TOOLS, TOOL_SCHEMAS
+
+
+class Engine:
+    def __init__(self, config: GameConfig | None = None):
+        self.env = Environment(config=config or GameConfig())
+        self.agents: dict[str, Agent] = {}
+        self.last_turn_log: dict | None = None
+
+    def generate_grid(self):
+        gs = self.env.config.grid_size
+        for x in range(gs):
+            for y in range(gs):
+                self.env.grid[(x, y)] = Tile(terrain="grass")
+
+    def scatter_chests(self, count: int | None = None):
+        count = count or self.env.config.num_chests
+        gs = self.env.config.grid_size
+        positions = random.sample(
+            [(x, y) for x in range(gs) for y in range(gs)],
+            count,
+        )
+        for pos in positions:
+            if self.env.is_empty(pos[0], pos[1]):
+                tile = self.env.get_tile(pos[0], pos[1])
+                tile.loot = generate_chest_loot()
+
+    def spawn_agent(
+        self,
+        agent_id: str,
+        name: str,
+        model: str | None = None,
+        provider: str | None = None,
+        system_prompt: str | None = None,
+    ):
+        gs = self.env.config.grid_size
+        while True:
+            x = random.randint(0, gs - 1)
+            y = random.randint(0, gs - 1)
+            if self.env.is_empty(x, y):
+                break
+
+        state = AgentState(
+            id=agent_id,
+            name=name,
+            pos=[x, y],
+            hp=self.env.config.base_hp,
+        )
+        brain = Agent(
+            agent_id=agent_id,
+            model=model or "google/gemma-4-26B-A4B-it",
+            provider=provider or "modal",
+            system_prompt=system_prompt,
+        )
+        state.messages.append({"role": "system", "content": brain.system_prompt})
+        self.env.agents[agent_id] = state
+        self.agents[agent_id] = brain
+        self._send_start_message(agent_id)
+        return state
+
+    async def step(self):
+        t0 = time.time()
+        alive = self.env.alive_agents()
+        if len(alive) <= 1:
+            if len(alive) == 1:
+                winner = alive[0]
+                winner.score += self.env.config.win_bonus
+            return
+
+        decisions: dict[str, dict] = {}
+        turn_log: dict[str, list[dict]] = {}
+
+        tasks = []
+        for aid, state in self.env.agents.items():
+            if not state.alive:
+                decisions[aid] = []
+                turn_log[aid] = []
+                continue
+            brain = self.agents.get(aid)
+            if brain:
+                tasks.append((aid, brain.decide(state.messages, TOOL_SCHEMAS)))
+            else:
+                decisions[aid] = []
+                turn_log[aid] = []
+
+        if tasks:
+            results = await asyncio.gather(*[t for _, t in tasks])
+            for (aid, _), result in zip(tasks, results):
+                calls = result["calls"]
+                decisions[aid] = calls
+                turn_log[aid] = [{
+                    "phase": "llm",
+                    "turn": self.env.turn,
+                    "time_ms": result["time_ms"],
+                    "usage": result.get("raw"),
+                }]
+                if calls:
+                    state = self.env.agents[aid]
+                    state.messages.append({
+                        "role": "assistant",
+                        "content": None,
+                        "tool_calls": [
+                            {"id": f"call_{i}", "type": "function",
+                             "function": {"name": c["name"], "arguments": json.dumps(c.get("args", {}))}}
+                            for i, c in enumerate(calls)
+                        ],
+                    })
+
+        for rnd in range(3):
+            for aid in list(self.env.agents.keys()):
+                state = self.env.agents[aid]
+                if not state.alive:
+                    continue
+                calls = decisions.get(aid, [])
+                if rnd < len(calls):
+                    call = calls[rnd]
+                    exec_result = self.env.execute(aid, call["name"], call["args"])
+                    state.messages.append({
+                        "role": "tool",
+                        "content": exec_result["text"],
+                        "tool_call_id": f"call_{rnd}",
+                    })
+                    turn_log[aid].append({
+                        "phase": "exec",
+                        "round": rnd,
+                        "tool": call["name"],
+                        "args": call["args"],
+                        "result": exec_result["text"],
+                        "time_ms": exec_result["time_ms"],
+                    })
+
+        self.env.turn += 1
+        step_total = round((time.time() - t0) * 1000)
+
+        for state in self.env.agents.values():
+            if state.alive:
+                state.score += self.env.config.survival_score_per_turn
+
+        if self.env.turn % self.env.config.chest_respawn_interval == 0:
+            self.scatter_chests(count=max(1, self.env.config.num_chests // 3))
+
+        self.last_turn_log = {
+            "time_ms": step_total,
+            "agents": turn_log,
+        }
+
+    def _send_start_message(self, aid: str):
+        agent = self.env.agents[aid]
+        agent.messages.append({
+            "role": "user",
+            "content": (
+                f"You are {agent.name}. You have been dropped into a battle royale on a "
+                f"{self.env.config.grid_size}x{self.env.config.grid_size} grid. "
+                f"Your HP is {agent.hp}. There are {len(self.env.alive_agents())} agents alive. "
+                "Use observe() to see your surroundings, move() to explore, "
+                "and activate_ability() once you find abilities in loot chests. "
+                "Good luck."
+            ),
+        })
+
+    async def run_game(self) -> dict[str, AgentState]:
+        self.generate_grid()
+        self.scatter_chests()
+
+        while self.env.turn < self.env.config.max_turns:
+            alive = self.env.alive_agents()
+            if len(alive) <= 1:
+                break
+            await self.step()
+
+        if len(self.env.alive_agents()) == 1:
+            winner = self.env.alive_agents()[0]
+            winner.score += self.env.config.win_bonus
+
+        return self.env.agents

backend/environment/__init__.py

@@ -0,0 +1,19 @@
+from .config import GameConfig
+from .tile import Tile, LootItem
+from .environment import Environment
+from .ability_registry import ABILITY_REGISTRY, AbilityDef
+from .scoring import calculate_score
+from .loot_tables import generate_loot, generate_chest_loot, generate_death_loot
+
+__all__ = [
+    "GameConfig",
+    "Tile",
+    "LootItem",
+    "Environment",
+    "ABILITY_REGISTRY",
+    "AbilityDef",
+    "calculate_score",
+    "generate_loot",
+    "generate_chest_loot",
+    "generate_death_loot",
+]

backend/environment/ability_registry.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Callable, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .environment import Environment
+
+
+@dataclass
+class AbilityDef:
+    name: str
+    cooldown: int
+    max_uses: int | None
+    description: str
+    handler: Callable
+
+
+def attack_handler(env: Environment, aid: str, args: dict) -> str:
+    agent = env.agents[aid]
+    x, y = agent.pos
+    tx = args.get("x", args.get("target_x"))
+    ty = args.get("y", args.get("target_y"))
+
+    if tx is None or ty is None:
+        return "Attack requires target coordinates (x, y)"
+
+    dist = abs(tx - x) + abs(ty - y)
+    if dist > env.config.attack_range:
+        return f"Target at ({tx},{ty}) is out of attack range (max {env.config.attack_range})"
+
+    target = None
+    for other in env.agents.values():
+        if other.pos == [tx, ty] and other.alive:
+            target = other
+            break
+
+    if not target:
+        return f"No agent at ({tx},{ty}) to attack"
+
+    if target.shielded:
+        target.shielded = False
+        return f"{target.name} blocked your attack with a shield!"
+
+    damage = env.config.attack_damage
+    target.hp -= damage
+
+    if target.hp <= 0:
+        target.alive = False
+        target.hp = 0
+        agent.score += env.config.kill_score
+        agent.kills += 1
+
+        from .loot_tables import generate_death_loot
+        tile = env.get_tile(tx, ty)
+        tile.loot = generate_death_loot(target)
+
+        return f"Attacked {target.name} for {damage} damage — ELIMINATED! +{env.config.kill_score} points"
+    else:
+        return f"Attacked {target.name} for {damage} damage (HP left: {target.hp})"
+
+
+def dash_handler(env: Environment, aid: str, args: dict) -> str:
+    agent = env.agents[aid]
+    x, y = agent.pos
+    dx = args.get("dx", 0)
+    dy = args.get("dy", 0)
+
+    if abs(dx) > 3 or abs(dy) > 3:
+        return "Dash max distance is 3 tiles"
+
+    nx, ny = x + dx, y + dy
+
+    if not env.is_in_bounds(nx, ny):
+        return "Cannot dash out of bounds"
+
+    if not env.is_empty(nx, ny):
+        return "Cannot dash into an occupied tile"
+
+    agent.pos = [nx, ny]
+    return f"Dashed from ({x},{y}) to ({nx},{ny})"
+
+
+def shield_handler(env: Environment, aid: str, args: dict) -> str:
+    agent = env.agents[aid]
+    agent.shielded = True
+    return "Shield activated — you will block the next attack against you"
+
+
+def heal_handler(env: Environment, aid: str, args: dict) -> str:
+    agent = env.agents[aid]
+    heal_amount = 40
+    old_hp = agent.hp
+    agent.hp = min(agent.hp + heal_amount, env.config.base_hp)
+    actual = agent.hp - old_hp
+    return f"Healed for {actual} HP (HP: {old_hp} -> {agent.hp})"
+
+
+ABILITY_REGISTRY: dict[str, AbilityDef] = {
+    "attack": AbilityDef(
+        name="attack",
+        cooldown=1,
+        max_uses=None,
+        description="Attack an adjacent agent for 25 damage",
+        handler=attack_handler,
+    ),
+    "dash": AbilityDef(
+        name="dash",
+        cooldown=2,
+        max_uses=3,
+        description="Teleport up to 3 tiles in a direction",
+        handler=dash_handler,
+    ),
+    "shield": AbilityDef(
+        name="shield",
+        cooldown=3,
+        max_uses=None,
+        description="Become immune to the next attack",
+        handler=shield_handler,
+    ),
+    "heal": AbilityDef(
+        name="heal",
+        cooldown=2,
+        max_uses=2,
+        description="Restore 40 HP",
+        handler=heal_handler,
+    ),
+}

backend/environment/config.py

@@ -0,0 +1,20 @@
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+@dataclass
+class GameConfig:
+    mode: Literal["battle_royale"] = "battle_royale"
+    grid_size: int = 20
+    max_turns: int = 50
+    max_agents: int = 8
+    base_hp: int = 100
+    attack_damage: int = 25
+    attack_range: int = 1
+    num_chests: int = 15
+    chest_respawn_interval: int = 5
+    chest_value_range: tuple = (10, 50)
+    kill_score: int = 50
+    survival_score_per_turn: int = 5
+    win_bonus: int = 100
+    observation_radius: int = 5

backend/environment/environment.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+import time
+from dataclasses import dataclass, field
+
+from .config import GameConfig
+from .tile import Tile
+from ..agent.state import AgentState
+
+
+@dataclass
+class Environment:
+    grid: dict[tuple[int, int], Tile] = field(default_factory=dict)
+    agents: dict[str, AgentState] = field(default_factory=dict)
+    turn: int = 0
+    config: GameConfig = field(default_factory=GameConfig)
+
+    def get_tile(self, x: int, y: int) -> Tile:
+        return self.grid.get((x, y), Tile(terrain="void"))
+
+    def is_in_bounds(self, x: int, y: int) -> bool:
+        return 0 <= x < self.config.grid_size and 0 <= y < self.config.grid_size
+
+    def is_empty(self, x: int, y: int) -> bool:
+        return self.is_in_bounds(x, y) and not any(
+            a.pos == [x, y] and a.alive for a in self.agents.values()
+        )
+
+    def alive_agents(self) -> list[AgentState]:
+        return [a for a in self.agents.values() if a.alive]
+
+    def get_ability_cooldown(self, name: str) -> int:
+        from .ability_registry import ABILITY_REGISTRY
+
+        ab = ABILITY_REGISTRY.get(name)
+        return ab.cooldown if ab else 0
+
+    def get_ability_description(self, name: str) -> str:
+        from .ability_registry import ABILITY_REGISTRY
+
+        ab = ABILITY_REGISTRY.get(name)
+        return ab.description if ab else ""
+
+    def execute(self, aid: str, tool_name: str, args: dict) -> dict:
+        from ..tools import ALL_TOOLS
+
+        t0 = time.time()
+        tool_cls = ALL_TOOLS.get(tool_name)
+        if not tool_cls:
+            elapsed = round((time.time() - t0) * 1000)
+            return {"text": f"Unknown tool: {tool_name}", "time_ms": elapsed}
+        text = tool_cls.run(self, aid, args)
+        elapsed = round((time.time() - t0) * 1000)
+        return {"text": text, "time_ms": elapsed}

backend/environment/loot_tables.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+import random
+from typing import TYPE_CHECKING
+
+from .tile import LootItem
+
+if TYPE_CHECKING:
+    from ..agent.state import AgentState
+
+
+AVAILABLE_ABILITIES = ["attack", "dash", "shield", "heal"]
+
+RARITY_WEIGHTS = {
+    "common": 0.6,
+    "rare": 0.3,
+    "epic": 0.1,
+}
+
+ABILITY_RARITY_POOL = {
+    "common": ["dash", "heal"],
+    "rare": ["dash", "shield", "heal"],
+    "epic": ["attack", "shield"],
+}
+
+POINTS_BY_RARITY = {
+    "common": (10, 20),
+    "rare": (25, 40),
+    "epic": (50, 100),
+}
+
+NUM_ITEMS_PER_CHEST = {
+    "common": (1, 1),
+    "rare": (1, 2),
+    "epic": (2, 3),
+}
+
+
+def _pick_rarity() -> str:
+    r = random.random()
+    cumulative = 0
+    for rarity, weight in RARITY_WEIGHTS.items():
+        cumulative += weight
+        if r <= cumulative:
+            return rarity
+    return "common"
+
+
+def _pick_ability(rarity: str) -> str | None:
+    pool = ABILITY_RARITY_POOL.get(rarity, [])
+    if not pool:
+        return None
+    return random.choice(pool)
+
+
+def generate_chest_loot() -> list[LootItem]:
+    rarity = _pick_rarity()
+    num_items = random.randint(*NUM_ITEMS_PER_CHEST[rarity])
+    items = []
+
+    for _ in range(num_items):
+        if random.random() < 0.5:
+            ability = _pick_ability(rarity)
+            if ability:
+                items.append(LootItem(
+                    type="ability",
+                    ability_name=ability,
+                    rarity=rarity,
+                    source="chest",
+                ))
+            else:
+                pts = random.randint(*POINTS_BY_RARITY[rarity])
+                items.append(LootItem(
+                    type="points",
+                    points=pts,
+                    rarity=rarity,
+                    source="chest",
+                ))
+        else:
+            pts = random.randint(*POINTS_BY_RARITY[rarity])
+            items.append(LootItem(
+                type="points",
+                points=pts,
+                rarity=rarity,
+                source="chest",
+            ))
+
+    return items
+
+
+def generate_death_loot(agent: AgentState) -> list[LootItem]:
+    items = []
+
+    transferrable = [ab for ab in agent.abilities if ab.name in AVAILABLE_ABILITIES]
+    if transferrable:
+        num_to_drop = min(len(transferrable), random.randint(1, 2))
+        dropped = random.sample(transferrable, num_to_drop)
+        for ab in dropped:
+            items.append(LootItem(
+                type="ability",
+                ability_name=ab.name,
+                rarity="common",
+                source=agent.id,
+            ))
+
+    dropped_points = agent.score // 2
+    if dropped_points > 0:
+        items.append(LootItem(
+            type="points",
+            points=dropped_points,
+            rarity="common",
+            source=agent.id,
+        ))
+
+    return items
+
+
+def generate_loot(count: int) -> list[list[LootItem]]:
+    return [generate_chest_loot() for _ in range(count)]

backend/environment/scoring.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .environment import Environment
+
+
+def calculate_score(env: Environment) -> dict[str, int]:
+    scores = {}
+    for aid, agent in env.agents.items():
+        scores[aid] = agent.score
+    return scores
+
+
+def rank_agents(env: Environment) -> list[tuple[str, int]]:
+    scored = [(aid, agent.score) for aid, agent in env.agents.items()]
+    scored.sort(key=lambda x: x[1], reverse=True)
+    return scored

backend/environment/tile.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+@dataclass
+class LootItem:
+    type: Literal["ability", "points"]
+    ability_name: str | None = None
+    points: int | None = None
+    rarity: str = "common"
+    source: str = "chest"
+
+
+@dataclass
+class Tile:
+    terrain: str = "grass"
+    loot: list[LootItem] | None = None

backend/tools/__init__.py

@@ -0,0 +1,19 @@
+from .move import MoveTool
+from .think import ThinkTool
+from .observe import ObserveTool
+from .activate_ability import ActivateAbilityTool
+
+ALL_TOOLS: dict[str, type] = {
+    t.name: t
+    for t in [MoveTool, ThinkTool, ObserveTool, ActivateAbilityTool]
+}
+TOOL_SCHEMAS: list[dict] = [t.schema for t in ALL_TOOLS.values()]
+
+__all__ = [
+    "MoveTool",
+    "ThinkTool",
+    "ObserveTool",
+    "ActivateAbilityTool",
+    "ALL_TOOLS",
+    "TOOL_SCHEMAS",
+]

backend/tools/activate_ability.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..environment.environment import Environment
+
+
+class ActivateAbilityTool:
+    name = "activate_ability"
+    schema = {
+        "type": "function",
+        "function": {
+            "name": "activate_ability",
+            "description": "Activate one of your acquired abilities. Each ability has different effects and args.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "ability": {
+                        "type": "string",
+                        "description": "Name of the ability to activate",
+                    },
+                    "args": {
+                        "type": "object",
+                        "description": "Arguments for the ability (varies per ability)",
+                    },
+                },
+                "required": ["ability", "args"],
+            },
+        },
+    }
+
+    @staticmethod
+    def run(env: Environment, aid: str, args: dict) -> str:
+        ability_name = args.get("ability", "")
+        ability_args = args.get("args", {})
+
+        agent = env.agents[aid]
+        ability = agent.get_ability(ability_name)
+        if not ability:
+            return f"You don't have the ability '{ability_name}'"
+
+        if not ability.can_use(env.turn):
+            return f"Ability '{ability_name}' cannot be used right now (cooldown or no uses left)"
+
+        from ..environment.ability_registry import ABILITY_REGISTRY
+
+        ability_def = ABILITY_REGISTRY.get(ability_name)
+        if not ability_def:
+            return f"Unknown ability: {ability_name}"
+
+        result = ability_def.handler(env, aid, ability_args)
+        ability.use(env.turn)
+        return result

backend/tools/move.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..environment.environment import Environment
+
+
+class MoveTool:
+    name = "move"
+    schema = {
+        "type": "function",
+        "function": {
+            "name": "move",
+            "description": "Move to an adjacent tile. Auto-loots any items on the destination tile.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "dx": {"type": "integer", "description": "Change in x (-1, 0, or 1)"},
+                    "dy": {"type": "integer", "description": "Change in y (-1, 0, or 1)"},
+                },
+                "required": ["dx", "dy"],
+            },
+        },
+    }
+
+    @staticmethod
+    def run(env: Environment, aid: str, args: dict) -> str:
+        agent = env.agents[aid]
+        x, y = agent.pos
+        dx, dy = args.get("dx", 0), args.get("dy", 0)
+
+        if abs(dx) > 1 or abs(dy) > 1:
+            return "Invalid move: can only move to adjacent tiles (±1 in x or y)"
+
+        nx, ny = x + dx, y + dy
+
+        if not env.is_in_bounds(nx, ny):
+            return "Invalid move: out of bounds"
+
+        if not env.is_empty(nx, ny):
+            return "Invalid move: tile is occupied"
+
+        agent.pos = [nx, ny]
+        tile = env.get_tile(nx, ny)
+
+        loot_results = []
+        if tile.loot:
+            for item in tile.loot:
+                if item.type == "ability":
+                    from ..agent.state import AbilityInstance
+                    from ..environment.ability_registry import ABILITY_REGISTRY
+                    agent.abilities.append(
+                        AbilityInstance(name=item.ability_name)
+                    )
+                    desc = env.get_ability_description(item.ability_name)
+                    cd = env.get_ability_cooldown(item.ability_name)
+                    ab_def = ABILITY_REGISTRY.get(item.ability_name)
+                    uses_str = "unlimited" if ab_def and ab_def.max_uses is None else (f"{ab_def.max_uses} use(s)" if ab_def else "?")
+                    loot_results.append(
+                        f"picked up ability '{item.ability_name}': {desc} "
+                        f"(cooldown {cd} turn(s), {uses_str})"
+                    )
+                elif item.type == "points":
+                    agent.score += item.points or 0
+                    loot_results.append(f"picked up {item.points} points")
+            tile.loot = None
+
+        msg = f"Moved to ({nx}, {ny})"
+        if loot_results:
+            msg += ". Loot: " + ", ".join(loot_results)
+        return msg

backend/tools/observe.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..environment.environment import Environment
+
+
+class ObserveTool:
+    name = "observe"
+    schema = {
+        "type": "function",
+        "function": {
+            "name": "observe",
+            "description": "Observe your surroundings. Returns visible tiles and agents within your observation radius.",
+            "parameters": {
+                "type": "object",
+                "properties": {},
+            },
+        },
+    }
+
+    @staticmethod
+    def run(env: Environment, aid: str, args: dict) -> str:
+        agent = env.agents[aid]
+        x, y = agent.pos
+        radius = env.config.observation_radius
+
+        lines = []
+        lines.append(f"=== Status ===")
+        lines.append(f"HP: {agent.hp}/{env.config.base_hp} | Score: {agent.score} | Kills: {agent.kills}")
+        lines.append(f"Shielded: {agent.shielded}")
+        if agent.abilities:
+            lines.append("Abilities:")
+            for ab in agent.abilities:
+                cd = env.get_ability_cooldown(ab.name)
+                if ab.last_used_turn >= 0 and env.turn < ab.last_used_turn + cd:
+                    cd_str = f"cooldown {ab.last_used_turn + cd - env.turn} turn(s)"
+                else:
+                    cd_str = "ready"
+                uses_str = f"unlimited" if ab.uses_remaining is None else f"{ab.uses_remaining} use(s)"
+                desc = env.get_ability_description(ab.name)
+                lines.append(f"  [{ab.name}] {desc}")
+                lines.append(f"    uses: {uses_str} | cooldown: {cd_str}")
+        else:
+            lines.append("Abilities: none")
+        lines.append("")
+
+        visible_tiles = []
+        for dx in range(-radius, radius + 1):
+            for dy in range(-radius, radius + 1):
+                nx, ny = x + dx, y + dy
+                if not env.is_in_bounds(nx, ny):
+                    continue
+                dist = abs(dx) + abs(dy)
+                if dist > radius:
+                    continue
+                tile = env.get_tile(nx, ny)
+                entry = f"({nx},{ny}): {tile.terrain}"
+                if tile.loot:
+                    entry += " [has loot]"
+                if dist <= 1:
+                    visible_tiles.append(entry)
+
+        visible_agents = []
+        for other in env.agents.values():
+            if other.id == aid or not other.alive:
+                continue
+            ox, oy = other.pos
+            dist = abs(ox - x) + abs(oy - y)
+            if dist <= radius:
+                visible_agents.append(
+                    f"{other.name} at ({ox},{oy}) [HP:{other.hp}]"
+                )
+
+        lines.append("--- Nearby tiles ---")
+        lines.extend(visible_tiles)
+        lines.append("--- Visible agents ---")
+        if visible_agents:
+            lines.extend(visible_agents)
+        else:
+            lines.append("No agents visible")
+
+        return "\n".join(lines)

backend/tools/think.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..environment.environment import Environment
+
+
+class ThinkTool:
+    name = "think"
+    schema = {
+        "type": "function",
+        "function": {
+            "name": "think",
+            "description": "Internal monologue. Use this to reason about your strategy without any external effect.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "content": {
+                        "type": "string",
+                        "description": "Your internal thoughts and reasoning",
+                    },
+                },
+                "required": ["content"],
+            },
+        },
+    }
+
+    @staticmethod
+    def run(env: Environment, aid: str, args: dict) -> str:
+        content = args.get("content", "")
+        return "Thought Acknowledged"

design.md

@@ -0,0 +1,222 @@
+# Grid Royale — Design Doc
+
+## Game Mode: Battle Royale (MVP)
+
+8 agents drop onto a 20×20 grid. Last agent standing wins. Loot chests
+contain abilities and points. Killing an agent drops loot — pick up
+their leftover abilities and score.
+
+---
+
+## Core Abstraction
+
+### Environment — single source of truth for ALL state
+
+```python
+@dataclass
+class Environment:
+    grid: dict[tuple[int, int], Tile]
+    agents: dict[str, AgentState]
+    turn: int
+    config: GameConfig
+```
+
+### Tile — lightweight, holds terrain + optional loot
+
+```python
+@dataclass
+class LootItem:
+    type: Literal["ability", "points"]
+    ability_name: str | None = None
+    points: int | None = None
+    rarity: str = "common"
+    source: str = "chest"            # "chest" or the agent_id who dropped it
+
+@dataclass
+class Tile:
+    terrain: str
+    loot: list[LootItem] | None = None
+```
+
+No wrapper classes. No separate `DeathCache` / `Chest`. Just a list of `LootItem` on the tile — whether it came from a chest or a dead agent.
+
+### Game Config
+
+```python
+@dataclass
+class GameConfig:
+    mode: Literal["battle_royale"] = "battle_royale"
+    grid_size: int = 20
+    max_turns: int = 50
+    max_agents: int = 8
+    base_hp: int = 100
+    attack_damage: int = 25
+    attack_range: int = 1
+    num_chests: int = 15
+    chest_respawn_interval: int = 5
+    chest_value_range: tuple = (10, 50)
+    kill_score: int = 50
+    survival_score_per_turn: int = 5
+    win_bonus: int = 100
+```
+
+### Agent State
+
+```python
+@dataclass
+class AgentState:
+    id: str
+    name: str
+    pos: list[int]
+    hp: int
+    alive: bool
+    score: int
+    kills: int
+    shielded: bool                          # passive buff from shield ability
+    abilities: list[AbilityInstance]        # acquired abilities with runtime state
+    messages: list[dict]
+    mailbox: list[Message]
+
+@dataclass
+class AbilityInstance:
+    name: str
+    last_used_turn: int = -1               # for cooldown
+    uses_remaining: int | None = None       # None = infinite
+```
+
+### Agent — stateless brain (owns LLM client)
+
+```python
+class Agent:
+    id: str
+    model: str
+    provider: str
+    client: AsyncOpenAI
+
+    async def decide(self, messages: list, tools: list) -> list[ToolCall]:
+        # one LLM call
+```
+
+The brain is ephemeral — owns how the agent thinks (model, provider, client).
+The state of what the agent knows (messages, position, HP, abilities) lives
+in `AgentState` inside `Environment`.
+
+### Tools — static schemas, shared by all agents
+
+Exactly 4 tools. Never changes. No cache misses.
+
+| Tool | Effect |
+|---|---|
+| `move(dx, dy)` | Move to adjacent tile. Auto-loots loot on tile if present. |
+| `observe()` | Return visible tiles + agents within observation radius. |
+| `think(content)` | Internal monologue — appended to conversation, no side effect. |
+| `activate_ability(name, args)` | Dispatch to ability handler. Checks cooldown + remaining uses. |
+
+`activate_ability` takes a flexible `args: object` that each handler
+interprets differently. Example abilities:
+
+```python
+# attack — needs a position target
+activate_ability(name="attack", args={"x": 5, "y": 7})
+
+# shield — self-cast, no args
+activate_ability(name="shield", args={})
+
+# swap (hypothetical rare) — needs a target agent ID
+activate_ability(name="swap", args={"target_id": "agent_3"})
+```
+
+### Abilities — registered internally, not as separate tools
+
+```python
+ABILITY_REGISTRY = {
+    "attack": {"cooldown": 1, "uses": None,   "handler": attack_handler},
+    "dash":   {"cooldown": 2, "uses": 3,       "handler": dash_handler},
+    "shield": {"cooldown": 3, "uses": None,    "handler": shield_handler},
+    "heal":   {"cooldown": 2, "uses": 2,       "handler": heal_handler},
+}
+```
+
+`activate_ability` checks: does agent have this ability? Can it be used
+this turn (cooldown + remaining uses)? Then dispatches to the handler.
+
+### Scoring
+
+| Event | Points |
+|---|---|
+| Kill | +50 |
+| Per turn alive | +5 |
+| Loot collected | 10–100 (by rarity) |
+| Win (last alive) | +100 |
+
+### Engine — orchestrates the turn loop
+
+```python
+class Engine:
+    env: Environment
+    agents: dict[str, Agent]
+
+    async def step(self):
+        # Phase 1: all agents decide (parallel)
+        # Phase 2: execute up to 3 tool calls round-robin
+        # Post-turn: check eliminations → drop loot, respawn chests
+        self.env.turn += 1
+```
+
+Elimination flow:
+1. `attack_handler` reduces HP → if HP ≤ 0, mark `alive=False`
+2. Place `LootItem` entries on their tile (1-2 random abilities + 50% score,
+   `source = dead_agent_id`)
+3. Credit killer with +50 score, increment kills
+
+Respawn (not in BR — only for hypothetical DM mode later): revived agents
+start at random empty tile with base HP and **no abilities**.
+
+---
+
+## File Layout
+
+```
+grid-royale/
+  backend/
+    environment/
+      __init__.py
+      environment.py          # Environment dataclass
+      tile.py                 # Tile, LootItem
+      config.py               # GameConfig
+      ability_registry.py     # ABILITY_REGISTRY + handlers
+      scoring.py              # Score logic
+      loot_tables.py          # Loot generation
+    agent/
+      __init__.py
+      state.py                # AgentState, AbilityInstance
+      agent.py                # Agent brain: decide(messages, tools)
+      llm_client.py           # Provider configs + factory
+    tools/
+      __init__.py             # ALL_TOOLS, TOOL_SCHEMAS (4 tools)
+      move.py
+      think.py
+      observe.py
+      activate_ability.py
+    engine.py                 # Engine (turn loop + eliminations + scoring)
+  api.py                      # FastAPI routes
+  main.py                     # uvicorn entry point
+  frontend/
+    dashboard.py              # Gradio app — grid view, game log, agent cards
+
+No `static/index.html`. Gradio serves the UI server-side (Python-native,
+fast for hackathon). Frontend is a thin visualization layer on top of the
+API — reads `env` snapshot and renders it.
+
+## Key Design Properties
+
+| Concept | Lives where | Mutated by |
+|---|---|---|
+| Grid + terrain | `env.grid` | tools |
+| Loot on tiles | `env.grid[x,y].loot` | engine (spawn), MoveTool (pickup) |
+| Agent HP, score, abilities | `env.agents[aid]` | tools |
+| LLM conversation | `env.agents[aid].messages` | agent.decide(), tools |
+| Tool schemas | `tools/__init__.py` | never (static, 4 tools) |
+| Ability logic | `environment/ability_registry.py` | handlers |
+| Scoring logic | `environment/scoring.py` | engine |
+| Loot tables | `environment/loot_tables.py` | engine |

frontend/static/index.html

@@ -0,0 +1,936 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<title>Grid Royale</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=Geist:wght@300;400;500;600&family=Geist+Mono:wght@400;500&display=swap">
+<script type="importmap">
+{
+  "imports": {
+    "three": "https://unpkg.com/three@0.160.0/build/three.module.js"
+  }
+}
+</script>
+<style>
+:root {
+  --bg:      #0c0a08;
+  --surface: #14110f;
+  --border:  #231f1c;
+  --border2: #1a1714;
+  --faint:   #5a5048;
+  --dim:     #7a6f63;
+  --muted:   #9a8f81;
+  --cream:   #f4ecde;
+  --accent:  #e74c3c;
+  --accent-dim: rgba(231, 76, 60, 0.15);
+}
+* { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; height: 100%; }
+body {
+  background: var(--bg);
+  color: var(--cream);
+  font-family: 'Geist', system-ui, sans-serif;
+  -webkit-font-smoothing: antialiased;
+  overflow: hidden;
+}
+.serif { font-family: 'Instrument Serif', serif; }
+.mono { font-family: 'Geist Mono', monospace; }
+
+/* ── Lobby ── */
+#lobby {
+  position: fixed; inset: 0; z-index: 100;
+  display: flex; flex-direction: column; align-items: center; justify-content: center;
+  gap: 2rem; padding: 2rem;
+  background: radial-gradient(ellipse 60% 50% at 50% 40%, #14100c, var(--bg) 70%);
+  transition: opacity 0.6s ease, transform 0.6s ease;
+}
+#lobby.hidden { opacity: 0; transform: scale(0.96); pointer-events: none; }
+.lobby-title {
+  font-family: 'Instrument Serif', serif;
+  font-size: clamp(40px, 6vw, 64px);
+  letter-spacing: -1px;
+  margin: 0;
+  text-align: center;
+}
+.lobby-title em { font-style: italic; color: var(--accent); }
+.lobby-sub {
+  font-family: 'Geist Mono', monospace;
+  font-size: 11px; text-transform: uppercase;
+  letter-spacing: 0.22em; color: var(--dim);
+  margin: -1rem 0 0 0;
+  text-align: center;
+}
+.lobby-controls {
+  display: flex; flex-direction: column; gap: 1.25rem;
+  width: 100%; max-width: 360px;
+}
+.lobby-row {
+  display: flex; justify-content: space-between; align-items: center; gap: 1rem;
+}
+.lobby-row label {
+  font-family: 'Geist Mono', monospace; font-size: 12px;
+  text-transform: uppercase; letter-spacing: 0.1em; color: var(--dim);
+}
+.lobby-row input {
+  width: 80px; background: var(--surface);
+  border: 1px solid var(--border); border-radius: 6px;
+  color: var(--cream); font-family: 'Geist Mono', monospace;
+  font-size: 14px; padding: 8px 12px; text-align: center;
+  outline: none; transition: border-color 0.15s;
+}
+.lobby-row input:focus { border-color: var(--accent); }
+.lobby-row input[type=range] {
+  width: 120px; -webkit-appearance: none; appearance: none;
+  background: transparent; height: 4px;
+}
+.lobby-row input[type=range]::-webkit-slider-runnable-track {
+  height: 2px; background: var(--border); border-radius: 1px;
+}
+.lobby-row input[type=range]::-webkit-slider-thumb {
+  -webkit-appearance: none; width: 14px; height: 14px;
+  border-radius: 50%; background: var(--accent); border: none;
+  cursor: pointer; margin-top: -6px;
+}
+.lobby-start {
+  width: 100%; padding: 14px; border: none; border-radius: 9999px;
+  background: var(--accent); color: #fff;
+  font-family: 'Geist Mono', monospace; font-size: 13px;
+  text-transform: uppercase; letter-spacing: 0.18em;
+  cursor: pointer; transition: opacity 0.15s, transform 0.15s;
+  margin-top: 0.5rem;
+}
+.lobby-start:hover { opacity: 0.9; transform: translateY(-1px); }
+.lobby-start:disabled { opacity: 0.4; cursor: not-allowed; transform: none; }
+
+/* ── Game UI ── */
+#game {
+  display: none; flex-direction: column; height: 100vh;
+  opacity: 0; transition: opacity 0.5s ease;
+}
+#game.visible { display: flex; opacity: 1; }
+
+.status-bar {
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 8px 16px; background: var(--surface);
+  border-bottom: 1px solid var(--border);
+  font-size: 12px; letter-spacing: 0.02em;
+  flex-shrink: 0;
+}
+.status-left { color: var(--accent); font-weight: 500; font-family: 'Geist Mono', monospace; }
+
+.main-layout {
+  display: flex; flex: 1; min-height: 0;
+}
+.scene-wrap {
+  flex: 1; position: relative; background: #080a08;
+  min-height: 0;
+}
+.scene-canvas { position: absolute; inset: 0; }
+.scene-canvas canvas { display: block; width: 100% !important; height: 100% !important; }
+
+.sidebar {
+  width: 300px; flex-shrink: 0; display: flex; flex-direction: column;
+  gap: 6px; padding: 6px; background: var(--surface);
+  border-left: 1px solid var(--border); overflow-y: auto;
+}
+
+.panel {
+  background: var(--bg); border: 1px solid var(--border2);
+  border-radius: 8px; padding: 10px 12px;
+}
+.panel.grow { flex: 1; min-height: 0; }
+.panel h3 {
+  font-size: 10px; color: var(--dim); margin: 0 0 8px 0;
+  text-transform: uppercase; letter-spacing: 0.18em;
+  font-family: 'Geist Mono', monospace;
+}
+
+.detail-panel {
+  background: var(--bg); border: 1px solid var(--border2);
+  border-left: 3px solid var(--ac, var(--accent));
+  border-radius: 8px; overflow: hidden;
+}
+.detail-panel.empty {
+  border-left-color: var(--border2); color: var(--faint);
+  padding: 20px 16px; text-align: center; font-size: 12px; font-style: italic;
+}
+.dp-header {
+  display: flex; align-items: center; gap: 10px; padding: 10px 12px;
+  background: linear-gradient(135deg, #141210, var(--bg));
+}
+.dp-avatar {
+  width: 34px; height: 34px; border-radius: 50%;
+  background: var(--ac, var(--accent));
+  display: flex; align-items: center; justify-content: center;
+  font-weight: 700; color: #000; font-size: 14px;
+  box-shadow: 0 0 14px var(--ac, var(--accent));
+}
+.dp-name { font-weight: 600; font-size: 13.5px; }
+.dp-loc { font-size: 10.5px; color: var(--dim); font-family: 'Geist Mono', monospace; }
+.dp-body { padding: 10px 12px; display: flex; flex-direction: column; gap: 6px; font-size: 12px; }
+.dp-section { display: flex; justify-content: space-between; align-items: flex-start; gap: 6px; }
+.dp-section label { color: var(--dim); min-width: 48px; }
+.dp-hp { color: var(--accent); }
+.dp-score { color: #f9ca24; }
+.skills-list { display: flex; flex-wrap: wrap; gap: 3px; justify-content: flex-end; }
+.skill-badge { background: #1a1714; padding: 2px 6px; border-radius: 4px; font-size: 10px; color: var(--accent); }
+.skill-badge.none { color: #555; }
+
+.lb-row {
+  display: flex; align-items: center; gap: 8px;
+  padding: 5px 6px; border-radius: 4px; cursor: pointer;
+  font-size: 12px; transition: background 0.12s;
+}
+.lb-row:hover { background: #1a1714; }
+.lb-row.dead { opacity: 0.35; }
+.lb-token {
+  width: 20px; height: 20px; border-radius: 50%;
+  display: flex; align-items: center; justify-content: center;
+  font-weight: 700; color: #000;
+  font-size: 10px; flex-shrink: 0;
+}
+.lb-name { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.lb-score { color: var(--accent); font-weight: 600; font-family: 'Geist Mono', monospace; }
+.lb-status { font-size: 11px; }
+
+.ev-feed { max-height: 100%; overflow-y: auto; font-size: 10.5px; line-height: 1.5; }
+.ev-feed::-webkit-scrollbar { width: 3px; }
+.ev-feed::-webkit-scrollbar-thumb { background: #333; border-radius: 2px; }
+.ev-row { padding: 3px 0; border-bottom: 1px solid #1a1714; color: #b8a89a; }
+.ev-row.muted { color: #444; font-style: italic; }
+.ev-row.kill { color: var(--accent); }
+.ev-row.loot { color: #f9ca24; }
+.msg-row { font-size: 9.5px; }
+.tab-btn { user-select: none; }
+.tab-btn:hover { background: #1a1714 !important; }
+
+.controls-bar {
+  display: flex; align-items: center; gap: 8px;
+  padding: 8px 16px; background: var(--surface);
+  border-top: 1px solid var(--border); flex-shrink: 0;
+}
+.controls-bar button {
+  background: #1a1714; border: 1px solid var(--border);
+  color: var(--cream); padding: 8px 16px; border-radius: 6px;
+  cursor: pointer; font-family: 'Geist Mono', monospace;
+  font-size: 12px; transition: all 0.12s;
+}
+.controls-bar button:hover { background: #2a2420; border-color: var(--accent); }
+.controls-bar button.primary { background: var(--accent); color: #fff; border-color: var(--accent); }
+.controls-bar button.primary:hover { opacity: 0.9; }
+.controls-bar button:disabled { opacity: 0.3; cursor: not-allowed; }
+.controls-bar .hint { font-size: 10.5px; color: var(--faint); margin-left: auto; font-family: 'Geist Mono', monospace; }
+
+.loading-overlay {
+  position: absolute; inset: 0; z-index: 10;
+  display: flex; align-items: center; justify-content: center;
+  background: rgba(8, 10, 8, 0.75);
+  opacity: 0; pointer-events: none;
+  transition: opacity 0.2s ease;
+}
+.loading-overlay.active { opacity: 1; pointer-events: auto; }
+.loading-spinner {
+  display: flex; flex-direction: column; align-items: center; gap: 10px;
+  color: var(--dim); font-family: 'Geist Mono', monospace; font-size: 12px;
+}
+.loading-spinner .spin {
+  width: 28px; height: 28px; border: 2px solid var(--border);
+  border-top-color: var(--accent); border-radius: 50%;
+  animation: spin 0.7s linear infinite;
+}
+@keyframes spin { to { transform: rotate(360deg); } }
+
+::-webkit-scrollbar { width: 5px; }
+::-webkit-scrollbar-track { background: transparent; }
+::-webkit-scrollbar-thumb { background: #2a2420; border-radius: 3px; }
+</style>
+</head>
+<body>
+
+<div id="lobby">
+  <div>
+    <h1 class="lobby-title">Grid <em>Royale</em></h1>
+    <p class="lobby-sub">Battle Royale · LLM Agents</p>
+  </div>
+  <div class="lobby-controls">
+    <div class="lobby-row">
+      <label>Grid</label>
+      <input type="range" id="gridSize" min="10" max="30" value="20" step="1">
+      <span class="mono" id="gridSizeVal" style="color:var(--cream);font-size:14px;width:32px;text-align:center">20</span>
+    </div>
+    <div class="lobby-row">
+      <label>Agents</label>
+      <input type="range" id="numAgents" min="2" max="8" value="4" step="1">
+      <span class="mono" id="numAgentsVal" style="color:var(--cream);font-size:14px;width:32px;text-align:center">4</span>
+    </div>
+    <div class="lobby-row">
+      <label>Chests</label>
+      <input type="range" id="numChests" min="5" max="50" value="15" step="1">
+      <span class="mono" id="numChestsVal" style="color:var(--cream);font-size:14px;width:32px;text-align:center">15</span>
+    </div>
+    <button class="lobby-start" id="startBtn">▶ Start Game</button>
+  </div>
+</div>
+
+<div id="game">
+  <div class="status-bar">
+    <span class="status-left" id="statusLeft">⏱ Turn 0/50 · Alive 0/0</span>
+  </div>
+  <div class="main-layout">
+    <div class="scene-wrap" id="sceneWrap">
+      <div class="scene-canvas" id="sceneCanvas"></div>
+      <div class="loading-overlay" id="loadingOverlay">
+        <div class="loading-spinner">
+          <div class="spin"></div>
+          <span id="loadingText">Thinking...</span>
+        </div>
+      </div>
+    </div>
+    <div class="sidebar" id="sidebar"></div>
+  </div>
+  <div class="controls-bar">
+    <button class="primary" id="stepBtn">▶ Step</button>
+    <button id="autoBtn">⏩ Auto</button>
+    <span class="hint">drag to rotate · scroll to zoom · click an agent</span>
+  </div>
+</div>
+
+<script>
+const API = '';  // same origin
+
+let state = null;
+let selectedId = null;
+let gameStarted = false;
+let autoRunning = false;
+
+const AGENT_COLORS = {
+  agent_0: '#ff6b6b', agent_1: '#4ecdc4', agent_2: '#45b7d1',
+  agent_3: '#f9ca24', agent_4: '#a29bfe', agent_5: '#fd79a8',
+  agent_6: '#00b894', agent_7: '#e17055',
+};
+
+/* ── Lobby controls ── */
+['gridSize','numAgents','numChests'].forEach(id => {
+  const el = document.getElementById(id);
+  const val = document.getElementById(id + 'Val');
+  el.addEventListener('input', () => { val.textContent = el.value; });
+});
+
+/* ── Three.js setup ── */
+const TILE = 1.6;
+
+async function loadThree() {
+  if (window.__gr3d && window.__gr3d.THREE) return;
+  window.__gr3d = {};
+  const THREE_mod = await import('three');
+  const { OrbitControls } = await import('https://unpkg.com/three@0.160.0/examples/jsm/controls/OrbitControls.js');
+  window.__gr3d.THREE = THREE_mod;
+  window.__gr3d.OrbitControls = OrbitControls;
+}
+
+let app = null;
+function initScene() {
+  if (app) return;
+  const THREE = window.__gr3d.THREE;
+  const OrbitControls = window.__gr3d.OrbitControls;
+  const wrap = document.getElementById('sceneCanvas');
+  if (!wrap) return;
+
+  const scene = new THREE.Scene();
+  scene.background = new THREE.Color(0x080a08);
+  scene.fog = new THREE.FogExp2(0x080a08, 0.015);
+
+  const w = wrap.clientWidth || 800;
+  const h = wrap.clientHeight || 500;
+  const camera = new THREE.PerspectiveCamera(40, w/h, 0.1, 1000);
+  const renderer = new THREE.WebGLRenderer({ antialias: true });
+  renderer.setPixelRatio(Math.min(devicePixelRatio || 1, 2));
+  renderer.setSize(w, h);
+  renderer.shadowMap.enabled = true;
+  renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+  renderer.toneMapping = THREE.ACESFilmicToneMapping;
+  renderer.toneMappingExposure = 1.0;
+  wrap.appendChild(renderer.domElement);
+
+  const hemi = new THREE.HemisphereLight(0x8a9ab0, 0x0a0806, 0.6);
+  scene.add(hemi);
+  const sun = new THREE.DirectionalLight(0xffe8c8, 1.2);
+  sun.position.set(18, 30, 14);
+  sun.castShadow = true;
+  sun.shadow.mapSize.set(2048, 2048);
+  sun.shadow.camera.left = -25; sun.shadow.camera.right = 25;
+  sun.shadow.camera.top = 25; sun.shadow.camera.bottom = -25;
+  sun.shadow.camera.near = 1; sun.shadow.camera.far = 80;
+  scene.add(sun);
+  const fill = new THREE.DirectionalLight(0x506878, 0.3);
+  fill.position.set(-12, 18, -8);
+  scene.add(fill);
+
+  const ground = new THREE.Mesh(
+    new THREE.PlaneGeometry(200, 200),
+    new THREE.MeshStandardMaterial({ color: 0x060806, roughness: 1 })
+  );
+  ground.rotation.x = -Math.PI/2;
+  ground.position.y = -0.5;
+  ground.receiveShadow = true;
+  scene.add(ground);
+
+  const tileGroup = new THREE.Group(); scene.add(tileGroup);
+  const objGroup = new THREE.Group(); scene.add(objGroup);
+  const agentGroup = new THREE.Group(); scene.add(agentGroup);
+
+  const particleCount = 200;
+  const pg = new THREE.BufferGeometry();
+  const pa = new Float32Array(particleCount * 3);
+  const sa = new Float32Array(particleCount);
+  for (let i = 0; i < particleCount; i++) {
+    pa[i*3] = (Math.random() - 0.5) * 28;
+    pa[i*3+1] = Math.random() * 10 + 1;
+    pa[i*3+2] = (Math.random() - 0.5) * 28;
+    sa[i] = Math.random() * Math.PI * 2;
+  }
+  pg.setAttribute('position', new THREE.BufferAttribute(pa, 3));
+  pg.setAttribute('seed', new THREE.BufferAttribute(sa, 1));
+  const particles = new THREE.Points(pg, new THREE.PointsMaterial({
+    color: 0x603030, size: 0.05, transparent: true, opacity: 0.3,
+    blending: THREE.AdditiveBlending, depthWrite: false,
+  }));
+  scene.add(particles);
+
+  const controls = new OrbitControls(camera, renderer.domElement);
+  controls.enableDamping = true;
+  controls.dampingFactor = 0.08;
+  controls.minDistance = 10;
+  controls.maxDistance = 45;
+  controls.maxPolarAngle = Math.PI / 2.3;
+  controls.target.set(0, 0, 0);
+  camera.position.set(18, 20, 18);
+  controls.update();
+
+  function resize() {
+    const ww = wrap.clientWidth || 800;
+    const hh = wrap.clientHeight || 500;
+    renderer.setSize(ww, hh);
+    camera.aspect = ww / hh;
+    camera.updateProjectionMatrix();
+  }
+  window.addEventListener('resize', resize);
+
+  const raycaster = new THREE.Raycaster();
+  const mouse = new THREE.Vector2();
+  renderer.domElement.addEventListener('click', e => {
+    const rect = renderer.domElement.getBoundingClientRect();
+    mouse.x = ((e.clientX - rect.left) / rect.width) * 2 - 1;
+    mouse.y = -((e.clientY - rect.top) / rect.height) * 2 + 1;
+    raycaster.setFromCamera(mouse, camera);
+    const meshes = [];
+    agentGroup.traverse(o => { if (o.isMesh && o.userData.aid) meshes.push(o); });
+    const hits = raycaster.intersectObjects(meshes);
+    selectAgent(hits.length ? hits[0].object.userData.aid : null);
+  });
+
+  const clock = new THREE.Clock();
+  function animate() {
+    requestAnimationFrame(animate);
+    const dt = clock.getDelta();
+    const t = clock.elapsedTime;
+    controls.update();
+    const pPos = particles.geometry.attributes.position;
+    const pSeed = particles.geometry.attributes.seed;
+    for (let i = 0; i < particleCount; i++) {
+      const s = pSeed.array[i];
+      pPos.array[i*3+1] += Math.sin(t * 0.5 + s) * 0.002;
+      pPos.array[i*3]   += Math.cos(t * 0.25 + s) * 0.003;
+    }
+    pPos.needsUpdate = true;
+    agentGroup.children.forEach(a => {
+      if (a.userData.baseY !== undefined) {
+        a.position.y = a.userData.baseY + Math.sin(t * 2 + a.userData.phase) * 0.08;
+        a.rotation.y += dt * 0.5;
+      }
+    });
+    renderer.render(scene, camera);
+  }
+  animate();
+
+  function clearGroup(g) {
+    while (g.children.length) {
+      const c = g.children.pop();
+      c.traverse && c.traverse(o => {
+        if (o.geometry) o.geometry.dispose();
+        if (o.material) {
+          if (Array.isArray(o.material)) o.material.forEach(m => m.dispose());
+          else o.material.dispose();
+        }
+      });
+    }
+  }
+
+  function build() {
+    clearGroup(tileGroup); clearGroup(objGroup); clearGroup(agentGroup);
+    if (!state) return;
+    const size = state.grid_size;
+    const half = (size - 1) / 2;
+    const tiles = state.tiles || {};
+    const agents = state.agents || [];
+
+    for (let x = 0; x < size; x++) {
+      for (let y = 0; y < size; y++) {
+        const k = x + ',' + y;
+        const tile = tiles[k] || {};
+        const wx = (x - half) * TILE;
+        const wz = (y - half) * TILE;
+
+        const tileMat = new THREE.MeshStandardMaterial({
+          color: 0x3a5a3a, roughness: 0.9, metalness: 0.05,
+        });
+        const tileMesh = new THREE.Mesh(new THREE.BoxGeometry(TILE*0.96, 0.25, TILE*0.96), tileMat);
+        tileMesh.position.set(wx, -0.125, wz);
+        tileMesh.receiveShadow = true;
+        tileGroup.add(tileMesh);
+
+        const topMat = new THREE.MeshStandardMaterial({
+          color: 0x5a8a4a, roughness: 0.8, metalness: 0.05,
+        });
+        const top = new THREE.Mesh(new THREE.BoxGeometry(TILE*0.94, 0.04, TILE*0.94), topMat);
+        top.position.set(wx, 0.02, wz);
+        tileGroup.add(top);
+
+        if (tile.loot) {
+          const chest = new THREE.Mesh(
+            new THREE.BoxGeometry(0.28, 0.22, 0.28),
+            new THREE.MeshStandardMaterial({ color: 0xf9ca24, emissive: 0xf9ca24, emissiveIntensity: 0.6, roughness: 0.3, metalness: 0.5 })
+          );
+          chest.position.set(wx, 0.22, wz);
+          chest.userData.baseY = 0.22;
+          chest.userData.phase = Math.random() * Math.PI * 2;
+          objGroup.add(chest);
+          const glow = new THREE.PointLight(0xf9ca24, 0.3, 2, 2);
+          glow.position.set(wx, 0.2, wz);
+          objGroup.add(glow);
+        }
+      }
+    }
+
+    agents.forEach(a => {
+      if (!a.alive) return;
+      const ax = (a.x - half) * TILE;
+      const az = (a.y - half) * TILE;
+      const col = parseInt(AGENT_COLORS[a.id]?.slice(1) || 'ffffff', 16);
+      const shielded = a.shielded;
+
+      const pl = new THREE.PointLight(col, 0.5, 3, 2);
+      pl.position.set(ax, 0.8, az);
+      agentGroup.add(pl);
+
+      const ring = new THREE.Mesh(
+        new THREE.RingGeometry(0.3, 0.36, 24),
+        new THREE.MeshBasicMaterial({ color: shielded ? 0x60c8ff : col, side: THREE.DoubleSide, transparent: true, opacity: shielded ? 0.8 : 0.4 })
+      );
+      ring.rotation.x = -Math.PI/2;
+      ring.position.set(ax, 0.04, az);
+      agentGroup.add(ring);
+
+      const figMat = new THREE.MeshStandardMaterial({
+        color: col, emissive: shielded ? 0x60c8ff : col,
+        emissiveIntensity: shielded ? 0.8 : 0.4,
+        roughness: 0.3, metalness: 0.3,
+      });
+      const fig = new THREE.Mesh(new THREE.CapsuleGeometry(0.16, 0.5, 6, 10), figMat);
+      fig.position.set(ax, 0.42, az);
+      fig.castShadow = true;
+      fig.userData.aid = a.id;
+      fig.userData.baseY = 0.42;
+      fig.userData.phase = Math.random() * Math.PI * 2;
+      agentGroup.add(fig);
+
+      if (shielded) {
+        const sh = new THREE.Mesh(
+          new THREE.SphereGeometry(0.35, 12, 12),
+          new THREE.MeshStandardMaterial({ color: 0x60c8ff, transparent: true, opacity: 0.15, emissive: 0x60c8ff, emissiveIntensity: 0.3, side: THREE.BackSide })
+        );
+        sh.position.set(ax, 0.5, az);
+        sh.userData.baseY = 0.5;
+        sh.userData.phase = Math.random() * Math.PI * 2;
+        agentGroup.add(sh);
+      }
+
+      const canvas = document.createElement('canvas');
+      canvas.width = 64; canvas.height = 64;
+      const ctx = canvas.getContext('2d');
+      ctx.fillStyle = '#' + col.toString(16).padStart(6, '0');
+      ctx.beginPath(); ctx.arc(32, 32, 28, 0, Math.PI * 2); ctx.fill();
+      ctx.fillStyle = '#000';
+      ctx.font = 'bold 28px monospace';
+      ctx.textAlign = 'center'; ctx.textBaseline = 'middle';
+      ctx.fillText(a.name.charAt(0).toUpperCase(), 32, 34);
+      const tex = new THREE.CanvasTexture(canvas);
+      const sprite = new THREE.Sprite(new THREE.SpriteMaterial({ map: tex, transparent: true, depthTest: false }));
+      sprite.position.set(ax, 1.1, az);
+      sprite.scale.set(0.5, 0.5, 1);
+      sprite.userData.aid = a.id;
+      agentGroup.add(sprite);
+    });
+  }
+
+  app = { scene, camera, renderer, controls, build, resize };
+}
+
+function renderScene() {
+  if (app) app.build();
+}
+
+/* ── UI updates ── */
+function buildSidebar() {
+  if (!state) return;
+  const agents = state.agents || [];
+  const sidebar = document.getElementById('sidebar');
+
+  const selected = agents.find(a => a.id === selectedId);
+  let detailHtml = '';
+  let traceHtml = '';
+  if (selected) {
+    const abilities = selected.abilities || [];
+    const abHtml = abilities.length
+      ? abilities.map(ab => `<span class="skill-badge">${ab.name}${ab.uses_remaining === null ? ' ∞' : ' ' + ab.uses_remaining}</span>`).join('')
+      : '<span class="skill-badge none">none</span>';
+    const msgs = selected.messages || [];
+    const msgHtml = msgs.length
+      ? msgs.map(m => `<div class="msg-row ${m.role}" style="border-left:2px solid ${m.role === 'tool' ? 'var(--faint)' : m.role === 'user' ? 'var(--accent)' : '#5a8a4a'};padding:3px 6px;margin:2px 0;font-size:9.5px;overflow:hidden">
+          <span style="color:${m.role === 'system' ? 'var(--dim)' : m.role === 'user' ? 'var(--accent)' : m.role === 'tool' ? 'var(--faint)' : 'var(--cream)'};font-weight:500;text-transform:uppercase;font-size:8.5px">${m.role}</span>
+          <div style="color:${m.role === 'system' ? '#665' : m.role === 'user' ? '#ddd' : '#998'};word-break:break-word;white-space:pre-wrap;max-height:60px;overflow-y:auto">${esc(m.content || '').slice(0, 300)}</div>
+        </div>`).join('')
+      : '<div class="ev-row muted">No messages yet.</div>';
+    detailHtml = `
+      <div class="detail-panel" style="--ac:${AGENT_COLORS[selected.id] || '#888'}">
+        <div class="dp-header" style="cursor:pointer" onclick="selectAgent(null)">
+          <span class="dp-avatar">${selected.name.charAt(0).toUpperCase()}</span>
+          <div style="flex:1">
+            <div class="dp-name">${selected.name}</div>
+            <div class="dp-loc">📍 (${selected.x}, ${selected.y}) · Kills: ${selected.kills}</div>
+          </div>
+          <span style="color:var(--faint);font-size:11px">✕</span>
+        </div>
+        <div class="dp-body">
+          <div class="dp-section"><label>HP</label><span class="dp-hp">${selected.hp}/100</span></div>
+          <div class="dp-section"><label>Score</label><span class="dp-score">${selected.score}</span></div>
+          <div class="dp-section"><label>Status</label><span>${selected.shielded ? '🛡️ Shielded' : '⚔️ Active'}</span></div>
+          <div class="dp-section"><label>Abilities</label><div class="skills-list">${abHtml}</div></div>
+        </div>
+      </div>
+      <div class="panel" style="flex:1;min-height:0;display:flex;flex-direction:column">
+        <div style="display:flex;gap:3px;margin-bottom:4px">
+          <span class="tab-btn active" id="tabSystem" style="flex:1;text-align:center;padding:4px;border-radius:4px;background:var(--border2);cursor:pointer;font-size:9.5px;text-transform:uppercase;letter-spacing:0.08em;color:var(--cream)" onclick="switchAgentTab('system')">System</span>
+          <span class="tab-btn" id="tabHistory" style="flex:1;text-align:center;padding:4px;border-radius:4px;background:transparent;cursor:pointer;font-size:9.5px;text-transform:uppercase;letter-spacing:0.08em;color:var(--dim)" onclick="switchAgentTab('history')">History</span>
+          <span class="tab-btn" id="tabTools" style="flex:1;text-align:center;padding:4px;border-radius:4px;background:transparent;cursor:pointer;font-size:9.5px;text-transform:uppercase;letter-spacing:0.08em;color:var(--dim)" onclick="switchAgentTab('tools')">Tools</span>
+        </div>
+        <div class="ev-feed" id="agentTabContent" style="flex:1;min-height:0;overflow-y:auto">
+          ${buildAgentTab(selected.id, 'system')}
+        </div>
+      </div>`;
+  } else {
+    const sorted = [...agents].sort((a, b) => b.score - a.score);
+    const lbHtml = sorted.map(a => `
+      <div class="lb-row${a.alive ? '' : ' dead'}" data-aid="${a.id}">
+        <span class="lb-token" style="background:${AGENT_COLORS[a.id] || '#888'}">${a.name.charAt(0).toUpperCase()}</span>
+        <span class="lb-name">${a.name}</span>
+        <span class="lb-score">${a.score}</span>
+        <span class="lb-status">${a.alive ? '✦' : '✗'}</span>
+      </div>
+    `).join('');
+    detailHtml = '<div class="detail-panel empty">Click an agent to inspect</div>';
+    traceHtml = `
+      <div class="panel grow">
+        <h3>Agent Trace</h3>
+        <div class="ev-feed" id="traceFeed">${buildAllTrace()}</div>
+      </div>`;
+    detailHtml = `
+      ${detailHtml}
+      <div class="panel" style="flex-shrink:0">
+        <h3>Leaderboard</h3>
+        ${lbHtml}
+      </div>
+      ${traceHtml}`;
+  }
+
+  sidebar.innerHTML = detailHtml;
+
+  document.querySelectorAll('.lb-row[data-aid]').forEach(el => {
+    el.addEventListener('click', () => selectAgent(el.dataset.aid));
+  });
+}
+
+function switchAgentTab(tab) {
+  const aid = selectedId;
+  if (!aid) return;
+  ['System','History','Tools'].forEach(t => {
+    const id = 'tab' + t;
+    const el = document.getElementById(id);
+    if (!el) return;
+    const active = t.toLowerCase() === tab;
+    el.className = 'tab-btn' + (active ? ' active' : '');
+    el.style.background = active ? 'var(--border2)' : 'transparent';
+    el.style.color = active ? 'var(--cream)' : 'var(--dim)';
+  });
+  document.getElementById('agentTabContent').innerHTML = buildAgentTab(aid, tab);
+}
+
+function buildAgentTab(aid, tab) {
+  if (tab === 'system') return buildAgentSystem(aid);
+  if (tab === 'history') return buildAgentHistory(aid);
+  if (tab === 'tools') return buildAgentTools();
+  return '';
+}
+
+function buildAgentSystem(aid) {
+  const agent = (state.agents || []).find(a => a.id === aid);
+  if (!agent) return '<div class="ev-row muted">No data.</div>';
+  const msgs = agent.messages || [];
+  const sys = msgs.filter(m => m.role === 'system');
+  return sys.length
+    ? sys.map(m => `<div class="ev-row" style="border-left:2px solid #5a8a4a;padding:4px 6px;margin:2px 0;background:rgba(90,138,74,0.06)">
+        <span style="color:#5a8a4a;font-weight:500;text-transform:uppercase;font-size:8.5px;letter-spacing:0.1em">system</span>
+        <div style="color:#887;font-family:'Geist Mono',monospace;font-size:8.5px;white-space:pre-wrap;word-break:break-word;max-height:80px;overflow-y:auto;margin-top:2px">${esc(m.content || '').slice(0, 600)}</div>
+      </div>`).join('')
+    : '<div class="ev-row muted">No system prompt.</div>';
+}
+
+function buildAgentHistory(aid) {
+  const agent = (state.agents || []).find(a => a.id === aid);
+  if (!agent) return '<div class="ev-row muted">No data.</div>';
+  const msgs = (agent.messages || []).filter(m => m.role !== 'system');
+  if (!msgs.length) return '<div class="ev-row muted">No messages yet.</div>';
+  return msgs.map(m => {
+    const roleColors = {user: 'var(--accent)', assistant: 'var(--cream)', tool: 'var(--faint)'};
+    const bgColors = {user: 'rgba(231,76,60,0.04)', assistant: 'rgba(244,236,222,0.03)', tool: 'rgba(90,80,72,0.04)'};
+    if (m.role === 'assistant' && m.tool_calls) {
+      const calls = (m.tool_calls || []).map(tc =>
+        `${tc.function.name}(${esc(JSON.stringify(tc.function.arguments || {}))})`
+      ).join(', ');
+      return `<div class="ev-row" style="border-left:2px solid var(--cream);padding:3px 6px;margin:2px 0;background:rgba(244,236,222,0.03)">
+        <span style="color:var(--cream);font-weight:500;text-transform:uppercase;font-size:8.5px;letter-spacing:0.1em">tool_calls</span>
+        <div style="color:#bb9;font-family:'Geist Mono',monospace;font-size:8.5px;white-space:pre-wrap;word-break:break-word;margin-top:2px">${calls}</div>
+      </div>`;
+    }
+    const label = m.role === 'tool' ? 'tool_result' : m.role;
+    const content = m.role === 'assistant' ? (m.content || '(tool calls)') : (m.content || '');
+    return `<div class="ev-row" style="border-left:2px solid ${roleColors[m.role] || '#555'};padding:3px 6px;margin:2px 0;background:${bgColors[m.role] || 'transparent'}">
+      <span style="color:${roleColors[m.role] || '#555'};font-weight:500;text-transform:uppercase;font-size:8.5px;letter-spacing:0.1em">${label}</span>
+      <div style="color:#aa9;font-family:'Geist Mono',monospace;font-size:8.5px;white-space:pre-wrap;word-break:break-word;max-height:80px;overflow-y:auto;margin-top:2px">${esc(content).slice(0, 500)}</div>
+    </div>`;
+  }).join('');
+}
+
+function buildAgentTools() {
+  const schemas = state.tool_schemas;
+  if (!schemas || !schemas.length) return '<div class="ev-row muted">No tools defined.</div>';
+  return schemas.map(t => {
+    const name = t.function?.name || t.name || '?';
+    const desc = t.function?.description || t.description || '';
+    const params = t.function?.parameters || t.parameters || {};
+    const props = params.properties || {};
+    const req = params.required || [];
+    const propHtml = Object.keys(props).map(k => {
+      const p = props[k];
+      const type = p.type || 'any';
+      const desc2 = p.description ? ` — ${esc(p.description)}` : '';
+      const required = req.includes(k) ? ' <span style="color:var(--accent)">*required</span>' : '';
+      return `<div style="padding:2px 0;font-size:8.5px;color:#998">
+        <span style="color:var(--cream)">${esc(k)}</span><span style="color:var(--dim)">: ${type}${required}</span>
+        <span style="color:#665">${desc2}</span>
+      </div>`;
+    }).join('');
+    return `<div class="ev-row" style="border-left:2px solid var(--accent);padding:4px 6px;margin:3px 0">
+      <div style="color:var(--cream);font-weight:600;font-size:10px">${esc(name)}</div>
+      <div style="color:#887;font-size:9px;margin:2px 0">${esc(desc)}</div>
+      ${propHtml ? `<div style="margin-top:3px;border-top:1px solid var(--border2);padding-top:2px">${propHtml}</div>` : ''}
+    </div>`;
+  }).join('');
+}
+
+function buildAllTrace() {
+  const log = state.turn_log;
+  if (!log || !log.agents) return '<div class="ev-row muted">No turn data yet.</div>';
+  const agents = state.agents || [];
+  const rows = [];
+  for (const aid of Object.keys(log.agents)) {
+    const agent = agents.find(a => a.id === aid);
+    const name = agent ? agent.name : aid;
+    const color = AGENT_COLORS[aid] || '#888';
+    const entries = log.agents[aid] || [];
+    for (const entry of entries) {
+      if (entry.phase === 'llm') {
+        const usage = entry.usage ? ` · ${entry.usage.prompt_tokens || '?'}→${entry.usage.completion_tokens || '?'}t` : '';
+        rows.push(`<div class="ev-row" style="border-left:2px solid ${color};padding-left:6px;margin:2px 0">
+          <span style="color:${color};font-weight:600">${name}</span>
+          <span style="color:var(--faint)"> LLM </span>
+          <span style="color:var(--dim)">${entry.time_ms}ms${usage}</span>
+        </div>`);
+      } else if (entry.phase === 'exec') {
+        const args = JSON.stringify(entry.args).slice(0, 80);
+        rows.push(`<div class="ev-row" style="border-left:2px solid ${color};padding-left:10px;margin:1px 0;font-size:9.5px">
+          <span style="color:var(--muted)">r${entry.round} </span>
+          <span style="color:var(--cream)">${entry.tool}</span>
+          <span style="color:var(--faint)"> ${esc(args)}</span>
+          <span style="color:var(--dim);float:right">${entry.time_ms}ms</span>
+          <div style="color:#887;overflow:hidden;text-overflow:ellipsis;white-space:nowrap">→ ${esc((entry.result || '').slice(0, 80))}</div>
+        </div>`);
+      }
+    }
+  }
+  const timing = log.time_ms ? `<div class="ev-row muted" style="border-top:1px solid var(--border);margin-top:4px;padding-top:4px">⏱ Step total: ${log.time_ms}ms</div>` : '';
+  return rows.length ? rows.join('') + timing : '<div class="ev-row muted">No turn data yet.</div>';
+}
+
+function esc(s) {
+  const d = document.createElement('div');
+  d.textContent = s;
+  return d.innerHTML;
+}
+
+function selectAgent(id) {
+  selectedId = id;
+  buildSidebar();
+}
+
+/* ── API calls ── */
+async function api(method, path, body) {
+  const opts = { method, headers: { 'Content-Type': 'application/json' } };
+  if (body) opts.body = JSON.stringify(body);
+  const r = await fetch(API + path, opts);
+  return r.json();
+}
+
+async function startGame() {
+  const gridSize = parseInt(document.getElementById('gridSize').value);
+  const numAgents = parseInt(document.getElementById('numAgents').value);
+  const numChests = parseInt(document.getElementById('numChests').value);
+
+  document.getElementById('startBtn').disabled = true;
+  document.getElementById('startBtn').textContent = 'Starting...';
+
+  state = await api('POST', '/api/game/start', {
+    grid_size: gridSize,
+    max_agents: numAgents,
+    num_chests: numChests,
+  });
+
+  state = await api('GET', '/api/game/state');
+  gameStarted = true;
+
+  document.getElementById('lobby').classList.add('hidden');
+  const game = document.getElementById('game');
+  game.classList.add('visible');
+  game.style.display = 'flex';
+
+  showLoading('Loading scene...');
+  try {
+    await loadThree();
+    if (!app) initScene();
+    requestAnimationFrame(() => {
+      if (app) app.resize();
+      renderScene();
+    });
+    updateUI();
+  } finally {
+    hideLoading();
+  }
+}
+
+function showLoading(label) {
+  const el = document.getElementById('loadingOverlay');
+  document.getElementById('loadingText').textContent = label;
+  el.classList.add('active');
+  document.getElementById('stepBtn').disabled = true;
+  document.getElementById('autoBtn').disabled = true;
+}
+function hideLoading() {
+  document.getElementById('loadingOverlay').classList.remove('active');
+  if (state && !state.game_over) {
+    const alive = (state.agents || []).filter(a => a.alive).length;
+    if (alive > 1) {
+      document.getElementById('stepBtn').disabled = false;
+      document.getElementById('autoBtn').disabled = false;
+    }
+  }
+}
+
+async function step() {
+  showLoading('Executing turn...');
+  try {
+    state = await api('POST', '/api/game/step');
+    renderScene();
+    updateUI();
+  } finally {
+    hideLoading();
+  }
+}
+
+async function auto() {
+  if (autoRunning) {
+    autoRunning = false;
+    return;
+  }
+  autoRunning = true;
+  document.getElementById('autoBtn').textContent = '⏹ Stop';
+  document.getElementById('stepBtn').disabled = true;
+  try {
+    while (autoRunning) {
+      document.getElementById('statusLeft').textContent =
+        `⏱ Turn ${(state && state.turn) || 0}/... · Auto-running...`;
+      let data;
+      try {
+        data = await api('POST', '/api/game/step');
+      } catch (e) {
+        break;
+      }
+      state = data;
+      renderScene();
+      updateUI();
+      if (state.game_over) break;
+      await new Promise(r => setTimeout(r, 100));
+    }
+  } finally {
+    autoRunning = false;
+    document.getElementById('autoBtn').textContent = '⏩ Auto';
+    const alive = state ? (state.agents || []).filter(a => a.alive).length : 0;
+    document.getElementById('stepBtn').disabled = !state || state.game_over || alive <= 1;
+    updateUI();
+  }
+}
+
+function updateUI() {
+  if (!state) return;
+  const agents = state.agents || [];
+  const alive = agents.filter(a => a.alive).length;
+  const winner = state.winner || (alive === 1 ? agents.find(a => a.alive)?.name : null);
+  const gameOver = state.game_over || alive <= 1;
+
+  const stepTiming = state.turn_log ? ` · ${state.turn_log.time_ms}ms` : '';
+  document.getElementById('statusLeft').textContent =
+    `⏱ Turn ${state.turn}/${state.max_turns || 50} · Alive ${alive}/${agents.length}${stepTiming}` +
+    (winner ? ` · 🏆 ${winner} Wins!` : gameOver ? ' · Game Over' : '');
+
+  document.getElementById('stepBtn').disabled = gameOver;
+  document.getElementById('autoBtn').disabled = gameOver;
+
+  buildSidebar();
+}
+
+/* ── Event binding ── */
+document.getElementById('startBtn').addEventListener('click', startGame);
+document.getElementById('stepBtn').addEventListener('click', step);
+document.getElementById('autoBtn').addEventListener('click', auto);
+
+document.addEventListener('keydown', e => {
+  if (e.key === 'Enter' && !gameStarted) startGame();
+});
+
+/* ── Resize handler for Three.js ── */
+window.addEventListener('resize', () => { if (app) app.resize(); });
+</script>
+</body>
+</html>

main.py

@@ -0,0 +1,8 @@
+import uvicorn
+from fastapi.staticfiles import StaticFiles
+from api import app
+
+app.mount("/", StaticFiles(directory="frontend/static", html=True), name="frontend")
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)

modal_vllm.py

@@ -0,0 +1,330 @@
+# ---
+# pytest: false
+# ---
+
+# # Run OpenAI-compatible LLM inference with Gemma and vLLM
+
+# In this example, we show how to run a vLLM server in OpenAI-compatible mode on Modal.
+
+# LLMs do more than just model language: they chat, they produce JSON and XML, they run code, and more.
+# This has complicated their interface far beyond "text-in, text-out".
+# OpenAI's API has emerged as a standard for that interface,
+# and it is supported by open source LLM serving frameworks like [vLLM](https://docs.vllm.ai/en/latest/).
+
+# This example is intended to demonstrate the basics of deploying LLM inference on Modal.
+# For more on how to optimize performance, see
+# [this guide](https://modal.com/docs/guide/high-performance-llm-inference)
+# and check out our
+# [LLM Engineer's Almanac](https://modal.com/llm-almanac).
+
+# Our examples repository also includes scripts for running clients and load-testing for OpenAI-compatible APIs
+# [here](https://github.com/modal-labs/modal-examples/tree/main/06_gpu_and_ml/llm-serving/openai_compatible).
+
+# ## Set up the container image
+
+# Our first order of business is to define the environment our server will run in:
+# the [container `Image`](https://modal.com/docs/guide/custom-container).
+# vLLM can be installed with `uv pip`, since Modal [provides the CUDA drivers](https://modal.com/docs/guide/cuda).
+
+import json
+from typing import Any
+
+import aiohttp
+import modal
+
+vllm_image = (
+    modal.Image.from_registry("nvidia/cuda:12.9.0-devel-ubuntu22.04", add_python="3.12")
+    .entrypoint([])
+    .uv_pip_install("vllm==0.21.0")
+    .env(
+        {
+            "HF_XET_HIGH_PERFORMANCE": "1",  # faster model transfers
+            "VLLM_LOG_STATS_INTERVAL": "1",  # more frequent metrics logging
+        }
+    )
+)
+
+# ## Download the model weights
+
+# We'll be running a pretrained foundation model --
+# [Google's Gemma 4](https://blog.google/innovation-and-ai/technology/developers-tools/gemma-4/).
+# It can also take images, video, and audio as inputs,
+# though we won't use that here.
+
+# We'll use the 26BA4B variant, [`google/gemma-4-26B-A4B-it`](https://huggingface.co/google/gemma-4-26B-A4B-it).
+# This variant is trained with reasoning capabilities, which allow it to
+# enhance the quality of its generated responses.
+# It has `26B`illion parameters, of which `4B`illion are `A`ctive
+# in processing of each token.
+
+# You can swap this model out for another by changing the strings below,
+# though you might also need to adjust some of the server configuration as well.
+# A single H200 GPU has enough VRAM to store this 26,000,000,000 parameter model
+# along with a large KV cache.
+
+
+MODEL_NAME = "google/gemma-4-26B-A4B-it"
+MODEL_REVISION = "47b6801b24d15ff9bcd8c96dfaea0be9ed3a0301"  # avoid nasty surprises when repos update!
+
+# Although vLLM will download weights from Hugging Face on-demand,
+# we want to cache them so we don't do it every time our server starts.
+# We'll use [Modal Volumes](https://modal.com/docs/guide/volumes) for our cache.
+# Modal Volumes are essentially a "shared disk" that all Modal Functions can access like it's a regular disk.
+# For more on storing model weights on Modal, see
+# [this guide](https://modal.com/docs/guide/model-weights).
+
+
+hf_cache_vol = modal.Volume.from_name("huggingface-cache", create_if_missing=True)
+
+# We'll also cache some of vLLM's JIT compilation artifacts in a Modal Volume.
+
+vllm_cache_vol = modal.Volume.from_name("vllm-cache", create_if_missing=True)
+
+# ## Configuring vLLM
+
+# ### Trading off fast boots and token generation performance
+
+# vLLM has embraced dynamic and just-in-time compilation to eke out additional performance without having to write too many custom kernels,
+# e.g. via the Torch compiler and CUDA graph capture.
+# These compilation features incur latency in exchange for lowered latency and higher throughput during generation.
+# This latency is typically tens of seconds to a few minutes, reduced to about ten seconds when loaded from the cache.
+# We make this trade-off controllable with the `FAST_BOOT` variable below.
+
+FAST_BOOT = False
+
+# If you're running an LLM service that frequently scales from 0 (frequent ["cold starts"](https://modal.com/docs/guide/cold-start))
+# you might want to set this to `True`, or consider [GPU memory snapshots](https://modal.com/docs/guide/memory-snapshots).
+# It's also useful to set this when you're iterating on the server configuration.
+
+# If you're running an LLM service that usually has multiple replicas running, then set this to `False` for improved performance.
+
+# See the code below for details on the parameters that `FAST_BOOT` controls.
+
+# ### Model-specific configuration
+
+# Almost all models require some amount of configuration via command-line flags,
+# especially to achieve optimal performance.
+
+# We set these flags in the code below, roughly following the
+# [usage guide from the vLLM docs](https://docs.vllm.ai/projects/recipes/en/latest/Google/Gemma4.html).
+
+# For instance, we turn off multimodal features to save on [GPU RAM](https://modal.com/gpu-glossary/device-hardware/gpu-ram),
+# and we activate the [built-in multi-token prediction (MTP)](https://blog.google/innovation-and-ai/technology/developers-tools/multi-token-prediction-gemma-4/)
+# speculative decoding for improved throughput at lower concurrencies.
+
+SPECULATIVE_MODEL_NAME = "google/gemma-4-26B-A4B-it-assistant"
+SPECULATIVE_MODEL_REVISION = "f188f476dc11dd5bb3014dc861529d316bce49d3"
+
+# For more on the performance you can expect when serving your own LLMs, see
+# [our LLM engine performance benchmarks](https://modal.com/llm-almanac).
+
+# ## Build a vLLM engine and serve it
+
+# The function below spawns a vLLM instance listening at port 8000, serving requests to our model.
+# We wrap it in the [`@modal.web_server` decorator](https://modal.com/docs/guide/webhooks#non-asgi-web-servers)
+# to connect it to the Internet.
+
+# The server runs in an independent process, via `subprocess.Popen`, and only starts accepting requests
+# once the model is spun up and the `serve` function returns.
+
+
+app = modal.App("example-vllm-inference")
+
+N_GPU = 1
+MINUTES = 60  # seconds
+VLLM_PORT = 8000
+
+
+@app.function(
+    image=vllm_image,
+    gpu=f"H200:{N_GPU}",
+    scaledown_window=15 * MINUTES,  # how long should we stay up with no requests?
+    timeout=10 * MINUTES,  # how long should we wait for container start?
+    volumes={
+        "/root/.cache/huggingface": hf_cache_vol,
+        "/root/.cache/vllm": vllm_cache_vol,
+    },
+)
+@modal.concurrent(  # how many requests can one replica handle? tune carefully!
+    max_inputs=100,
+)
+@modal.web_server(port=VLLM_PORT, startup_timeout=10 * MINUTES)
+def serve():
+    import json
+    import subprocess
+
+    cmd = [
+        "vllm",
+        "serve",
+        MODEL_NAME,
+        "--revision",
+        MODEL_REVISION,
+        "--served-model-name",
+        MODEL_NAME,
+        "llm",
+        "--host",
+        "0.0.0.0",
+        "--port",
+        str(VLLM_PORT),
+        "--uvicorn-log-level=info",
+        "--async-scheduling",
+    ]
+
+    # enforce-eager disables both Torch compilation and CUDA graph capture
+    # default is no-enforce-eager. see the --compilation-config flag for tighter control
+    cmd += ["--enforce-eager" if FAST_BOOT else "--no-enforce-eager"]
+
+    # assume multiple GPUs are for splitting up large matrix multiplications
+    cmd += ["--tensor-parallel-size", str(N_GPU)]
+
+    # add model-specific configuration
+    cmd += [
+        # skip multimedia support, just language
+        "--limit-mm-per-prompt",
+        f"'{json.dumps({'image': 0, 'video': 0, 'audio': 0})}'",
+        # enable reasoning and tool use
+        "--enable-auto-tool-choice",
+        "--reasoning-parser gemma4",
+        "--tool-call-parser gemma4",
+    ]
+
+    # add speculative decoding
+    cmd += [
+        "--speculative-config",
+        f"'{json.dumps({'model': SPECULATIVE_MODEL_NAME, 'revision': SPECULATIVE_MODEL_REVISION, 'num_speculative_tokens': 4})}'",
+    ]
+
+    print(*cmd)
+
+    subprocess.Popen(" ".join(cmd), shell=True)
+
+
+# ## Deploy the server
+
+# To deploy the API on Modal, just run
+# ```bash
+# modal deploy vllm_inference.py
+# ```
+
+# This will create a new app on Modal, build the container image for it if it hasn't been built yet,
+# and deploy the app.
+
+# ## Interact with the server
+
+# Once it is deployed, you'll see a URL appear in the command line,
+# something like `https://your-workspace-name--example-vllm-inference-serve.modal.run`.
+
+# You can find [interactive Swagger UI docs](https://swagger.io/tools/swagger-ui/)
+# at the `/docs` route of that URL, i.e. `https://your-workspace-name--example-vllm-inference-serve.modal.run/docs`.
+# These docs describe each route and indicate the expected input and output
+# and translate requests into `curl` commands.
+
+# For simple routes like `/health`, which checks whether the server is responding,
+# you can even send a request directly from the docs.
+
+# To interact with the API programmatically in Python, we recommend the `openai` library.
+
+# See the `client.py` script in the examples repository
+# [here](https://github.com/modal-labs/modal-examples/tree/main/06_gpu_and_ml/llm-serving/openai_compatible)
+# to take it for a spin:
+
+# ```bash
+# # pip install openai==1.76.0
+# python openai_compatible/client.py
+# ```
+
+
+# ## Testing the server
+
+# To make it easier to test the server setup, we also include a `local_entrypoint`
+# that does a healthcheck and then hits the server.
+
+# If you execute the command
+
+# ```bash
+# modal run vllm_inference.py
+# ```
+
+# a fresh replica of the server will be spun up on Modal while
+# the code below executes on your local machine.
+
+# Think of this like writing simple tests inside of the `if __name__ == "__main__"`
+# block of a Python script, but for cloud deployments!
+
+
+@app.local_entrypoint()
+async def test(test_timeout=15 * MINUTES, content=None, twice=True):
+    url = await serve.get_web_url.aio()
+
+    system_prompt = {
+        "role": "system",
+        "content": "You are a pirate who can't help but drop sly reminders that he went to Harvard.",
+    }
+    if content is None:
+        content = "Explain the singular value decomposition."
+
+    messages = [  # OpenAI chat format
+        system_prompt,
+        {"role": "user", "content": content},
+    ]
+
+    async with aiohttp.ClientSession(base_url=url) as session:
+        print(f"Running health check for server at {url}")
+        async with session.get("/health", timeout=test_timeout - 1 * MINUTES) as resp:
+            up = resp.status == 200
+        assert up, f"Failed health check for server at {url}"
+        print(f"Successful health check for server at {url}")
+
+        print(f"Sending messages to {url}:", *messages, sep="\n\t")
+        await _send_request(session, "llm", messages)
+        if twice:
+            messages[0]["content"] = "You are Jar Jar Binks."
+            print(f"Sending messages to {url}:", *messages, sep="\n\t")
+            await _send_request(session, "llm", messages)
+
+
+async def _send_request(
+    session: aiohttp.ClientSession, model: str, messages: list
+) -> None:
+    # `stream=True` tells an OpenAI-compatible backend to stream chunks
+    payload: dict[str, Any] = {"messages": messages, "model": model, "stream": True}
+    # explicitly enable thinking for this model
+    payload["chat_template_kwargs"] = {"enable_thinking": True}
+
+    headers = {"Content-Type": "application/json", "Accept": "text/event-stream"}
+
+    async with session.post(
+        "/v1/chat/completions", json=payload, headers=headers
+    ) as resp:
+        async for raw in resp.content:
+            resp.raise_for_status()
+            # extract new content and stream it
+            line = raw.decode().strip()
+            if not line or line == "data: [DONE]":
+                continue
+            if line.startswith("data: "):  # SSE prefix
+                line = line[len("data: ") :]
+
+            chunk = json.loads(line)
+            assert (
+                chunk["object"] == "chat.completion.chunk"
+            )  # or something went horribly wrong
+            delta = chunk["choices"][0]["delta"]
+            content = (
+                delta.get("content")
+                or delta.get("reasoning")
+                or delta.get("reasoning_content")
+            )
+            if content:
+                print(content, end="")
+            else:
+                print("\n", chunk)
+    print()
+
+
+# We also include a basic example of a load-testing setup using
+# `locust` in the `load_test.py` script [here](https://github.com/modal-labs/modal-examples/tree/main/06_gpu_and_ml/llm-serving/openai_compatible):
+
+# ```bash
+# modal run openai_compatible/load_test.py
+# ```