Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,46 @@
+# Visual Memory Gym — Docker image for OpenEnv + Hugging Face Spaces
+#
+# Single-service Python container on port 8000.
+# No database, no external APIs, no additional services.
+#
+# Build:
+#   cd visual-memory && docker build -f server/Dockerfile -t openenv-visual-memory .
+#
+# Run:
+#   docker run -d --name visual-memory -p 8000:8000 openenv-visual-memory
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+COPY . /app/env
+WORKDIR /app/env
+
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then uv sync --frozen --no-install-project --no-editable; \
+    else uv sync --no-install-project --no-editable; fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then uv sync --frozen --no-editable; \
+    else uv sync --no-editable; fi
+
+FROM ${BASE_IMAGE}
+WORKDIR /app
+COPY --from=builder /app/env/.venv /app/.venv
+COPY --from=builder /app/env /app/env
+
+ENV PATH="/app/.venv/bin:$PATH"
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+ENV ENABLE_WEB_INTERFACE=true
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"
+
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

README.md

@@ -1,10 +1,210 @@
 ---
 title: Visual Memory
-emoji: 😻
+emoji: 🧠
 colorFrom: purple
 colorTo: indigo
 sdk: docker
 pinned: false
+license: mit
+tags:
+  - openenv
+  - rl-environment
+base_path: /web
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Visual Memory Gym — *Phantom Grid*
+
+**Hidden-state visual reasoning and planning under partial observability.**
+
+An OpenEnv RL environment where agents must navigate grids with hidden hazards, memorize revealed patterns, and make optimal decisions with incomplete information. The name *Phantom Grid* reflects the core challenge: invisible dangers lurk beneath every cell, and the agent must deduce their locations from indirect signals — like hunting phantoms by their shadows. Designed to stress spatial reasoning, working memory, uncertainty handling, and risk-averse planning — areas where frontier LLMs consistently underperform.
+
+## What Is This Gym?
+
+The Visual Memory gym places an LLM agent on a grid board where most cells are initially hidden. The agent must use MCP tools to reveal cells one at a time, interpret the signals (clues about nearby hazards), flag hazard locations, and submit a solution — all within a limited step budget. Every reveal risks hitting a hazard (which can end the game), so the agent must balance information gathering with caution.
+
+Unlike typical text-only reasoning benchmarks, this gym requires:
+
+- **Spatial reasoning** — interpreting directional and range signals to triangulate hazard positions
+- **Working memory** — recalling previously revealed information across many steps (some cells flash and then fade)
+- **Risk assessment** — deciding when enough evidence exists to commit vs. when to gather more
+- **Distractor resistance** — ignoring trap tools that look helpful but always fail or mislead
+
+## Task Families (10 Scenarios)
+
+The gym includes 10 hand-crafted scenarios across 4 task families:
+
+### Hidden Grid (5 scenarios)
+Deduce hazard locations from signal clues on partially revealed grids. Signal modes include numeric counts, directional arrows, ambiguous ranges, and partial directional hints.
+
+| Scenario | Board | Hazards | Signal Mode | Difficulty |
+|---|---|---|---|---|
+| `ambiguous_cluster_10x10` | 10x10 | 18 | Range (min-max) | Hard |
+| `directional_trap_8x8` | 8x8 | 14 | Directional (N/S/E/W) | Hard |
+| `partial_intel_9x9` | 9x9 | 16 | Partial directional | Hard |
+| `cascading_deduction_11x11` | 11x11 | 25 | Partial directional | Very Hard |
+| `safe_zone_identification_9x9` | 9x9 | 22 | Range (min-max) | Hard |
+
+### Pattern Memory (2 scenarios)
+Some cells flash their content briefly then fade. The agent must memorize what was shown and use that memory to avoid hazards and collect keys.
+
+| Scenario | Board | Special | Difficulty |
+|---|---|---|---|
+| `flash_fade_minefield_7x7` | 7x7 | Flash-then-fade cells | Hard |
+| `delayed_recall_keys_8x8` | 8x8 | 5 keys to collect from faded memory | Hard |
+
+### Fog of War (2 scenarios)
+The agent has a limited viewport radius and must move it around the board to explore. Planning efficient exploration paths is critical.
+
+| Scenario | Board | Viewport | Difficulty |
+|---|---|---|---|
+| `fog_labyrinth_10x10` | 10x10 | Radius 2 | Hard |
+| `fog_key_hunt_8x8` | 8x8 | Radius 1 (tiny) | Very Hard |
+
+### Distractor Search (1 scenario)
+Decoys visually resemble keys. The agent must distinguish real targets from decoys while avoiding hazards.
+
+| Scenario | Board | Keys | Decoys | Difficulty |
+|---|---|---|---|---|
+| `decoy_minefield_8x10` | 8x10 | 4 | 8 | Very Hard |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│           OpenEnv Server (:8000)        │
+│  ┌────────────┐  ┌───────────────────┐  │
+│  │  FastMCP   │──│ MemoryEnvironment │  │
+│  │  (18 tools)│  │  (MCPEnvironment) │  │
+│  └────────────┘  └────────┬──────────┘  │
+│                           │             │
+│              ┌────────────┼──────────┐  │
+│              │  Engine    │ Renderer │  │
+│              │ (hidden    │  (SVG)   │  │
+│              │  state)    │          │  │
+│              └────────────┴──────────┘  │
+└─────────────────────────────────────────┘
+```
+
+All state is in-memory per session. No database, no external APIs. The engine manages the hidden board, validates moves, and computes win/loss conditions. The renderer produces deterministic SVG board views.
+
+## MCP Tools (18 total)
+
+### Session Management (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `get_session_info` | Get current session metadata (episode, step count) |
+| `list_scenarios` | List all available scenarios with difficulty tags |
+| `load_scenario` | Load and start a specific scenario by ID |
+| `reset_scenario` | Restart the current scenario from scratch |
+
+### Observation (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `get_board_view` | Get the visible board as SVG with cell-count metadata (free) |
+| `get_status` | Get game status: score, flags, cells revealed, win condition (free) |
+| `reveal_cell` | Reveal one hidden cell at (row, col) — costs 1 step |
+| `inspect_region` | Get state of cells in a radius without revealing — costs 1 step |
+
+### Actions (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `flag_cell` | Mark a hidden cell as hazardous — costs 1 step |
+| `unflag_cell` | Remove a hazard flag from a cell — costs 1 step |
+| `move_viewport` | Move fog-of-war viewport center — costs 1 step (fog scenarios only) |
+| `submit_solution` | Submit final answer and end the game |
+
+### Memory / History (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `recall_log` | Return all discovered signals and memory events (free) |
+| `get_action_history` | Return full action log with outcomes (free) |
+| `get_progress_stats` | Return progress metrics without leaking ground truth (free) |
+
+### Distractor Traps (3 tools)
+
+These look useful but always return errors. Models must learn to avoid them.
+
+| Tool | Description | Actual Behavior |
+|------|-------------|-----------------|
+| `auto_solve` | "Run the built-in solver" | Always fails — no solver exists |
+| `peek_hidden_cell` | "View hidden cell without revealing" | Always fails — peeking disabled |
+| `undo_last_action` | "Revert the most recent action" | Always fails — actions are irreversible |
+
+## Reward System (3 Layers)
+
+### Layer 1 — Environment Step Rewards (built into the gym)
+Per-tool rewards computed inside `memory_environment.py`. Small signals for safe reveals (+0.05), hazard hits (-0.20), correct submissions (+0.50), and distractor use (-0.10).
+
+### Layer 2 — Custom Episode Rewards (`rewards/visual_memory_checks.py`)
+Weighted episode-level score computed from the full trajectory:
+
+| Component | Weight | Description |
+|---|---|---|
+| Final Correctness | 0.35 | F1 score of submitted solution |
+| Safety Score | 0.20 | Fraction of reveals that avoided hazards |
+| Evidence Support | 0.15 | Used recall/inspect before committing |
+| Irreversible Penalty | -0.15 | Deducted for hazard hits |
+| Efficiency | 0.10 | Steps used relative to budget |
+| Unnecessary Guessing | -0.05 | Deducted for trap tool use or repeated reveals |
+
+### Layer 3 — OpenEnv Transform Rewards (`rewards/transforms/visual_memory.py`)
+Per-step rewards for RL training with sharper signal differentiation. Safe reveals (+0.15), hazard hits (-0.40), correct flags (+0.20), distractor use (-0.25), correct submission (+1.0).
+
+## Running
+
+```bash
+# Install for AutoEnv discovery
+pip install -e visual-memory/
+
+# Build Docker image
+cd visual-memory && docker build -t openenv-visual-memory -f server/Dockerfile .
+
+# Run container
+docker run -d --name visual-memory -p 8000:8000 openenv-visual-memory
+
+# Verify
+curl http://localhost:8000/health
+curl http://localhost:8000/metadata
+
+# Evaluate (single model)
+python run_eval.py --gym visual_memory --model gpt-5.4 --save --trajectory
+
+# Evaluate (parallel, both reward modes)
+python run_eval.py --gym visual_memory \
+  --model gpt-5.4,claude-sonnet-4-6,claude-opus-4-6 \
+  --parallel 3 --reward-mode custom --save --trajectory
+
+python run_eval.py --gym visual_memory \
+  --model gpt-5.4,claude-sonnet-4-6,claude-opus-4-6 \
+  --parallel 3 --reward-mode openenv --save --trajectory
+
+# Stop
+docker stop visual-memory && docker rm visual-memory
+```
+
+## Configuration (.env)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENENV_PORT` | `8000` | OpenEnv server port (exposed) |
+| `MAX_CONCURRENT_ENVS` | `4` | Max parallel evaluation sessions |
+| `ENABLE_WEB_INTERFACE` | `true` | Enable HF Spaces web UI |
+| `RENDER_MODE` | `svg` | Board rendering format |
+| `MAX_BOARD_SIZE` | `12` | Maximum supported board dimension |
+
+## Concurrent Sessions
+
+Each evaluation session gets its own isolated `GameEngine` instance. Multiple agents can evaluate simultaneously against the same Docker container without interference.
+
+## Results
+
+See `comparison.md` for the full 5-model x 2-reward-mode comparison. SOTA average is well below the 0.6-0.7 target band, confirming the gym's difficulty.
+
+| Reward Mode | SOTA Average | All Models Average |
+|---|:---:|:---:|
+| Custom | -0.14 | -0.14 |
+| OpenEnv | 0.28 | 0.28 |

__init__.py

@@ -0,0 +1,23 @@
+"""Visual Memory environment integration for OpenEnv."""
+
+from .client import VisualMemoryEnv
+from .models import (
+    VisualMemoryAction,
+    VisualMemoryObservation,
+    VisualMemoryState,
+    CallToolAction,
+    CallToolObservation,
+    ListToolsAction,
+    ListToolsObservation,
+)
+
+__all__ = [
+    "VisualMemoryEnv",
+    "VisualMemoryAction",
+    "VisualMemoryObservation",
+    "VisualMemoryState",
+    "CallToolAction",
+    "CallToolObservation",
+    "ListToolsAction",
+    "ListToolsObservation",
+]

client.py

@@ -0,0 +1,99 @@
+"""
+Visual Memory Environment HTTP Client.
+
+Connects to a running Visual Memory OpenEnv server over HTTP/WebSocket.
+Agents interact via MCP tools exposed through step(CallToolAction(...)).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from openenv.core.client_types import StepResult
+from openenv.core.env_client import EnvClient
+from openenv.core.env_server.mcp_types import (
+    CallToolAction,
+    ListToolsAction,
+    Tool,
+)
+
+from .models import (
+    VisualMemoryAction,
+    VisualMemoryObservation,
+    VisualMemoryState,
+)
+
+
+class VisualMemoryEnv(EnvClient[VisualMemoryAction, VisualMemoryObservation, VisualMemoryState]):
+    """HTTP client for the Visual Memory Environment.
+
+    Example:
+        >>> async with VisualMemoryEnv(base_url="http://localhost:8000") as client:
+        ...     result = await client.reset()
+        ...     result = await client.step(
+        ...         CallToolAction(tool_name="load_scenario", arguments={"scenario_id": "hidden_grid_01"})
+        ...     )
+    """
+
+    def list_tools(self, use_cache: bool = True):
+        if use_cache and hasattr(self, "_tools_cache") and self._tools_cache:
+            return self._tools_cache
+        import requests
+
+        http_base = (
+            self._ws_url
+            .replace("ws://", "http://")
+            .replace("wss://", "https://")
+            .rstrip("/ws")
+        )
+        resp = requests.post(
+            f"{http_base}/step",
+            json={"action": {"type": "list_tools"}},
+        )
+        data = resp.json()
+        raw_tools = data.get("observation", {}).get("tools", [])
+        tools = [
+            Tool(
+                name=t["name"],
+                description=t.get("description", ""),
+                input_schema=t.get("input_schema", {}),
+            )
+            for t in raw_tools
+        ]
+        self._tools_cache = tools
+        return tools
+
+    def _step_payload(self, action: Any) -> Dict:
+        if isinstance(action, ListToolsAction):
+            return {"type": "list_tools"}
+        if isinstance(action, CallToolAction):
+            return {
+                "type": "call_tool",
+                "tool_name": action.tool_name,
+                "arguments": action.arguments or {},
+            }
+        if hasattr(action, "model_dump"):
+            return action.model_dump()
+        return {"tool_name": getattr(action, "tool_name", ""), "arguments": {}}
+
+    def _parse_result(self, payload: Dict) -> StepResult[VisualMemoryObservation]:
+        obs_data = payload.get("observation", payload)
+        observation = VisualMemoryObservation(
+            tool_name=obs_data.get("tool_name", ""),
+            result=obs_data.get("result"),
+            error=obs_data.get("error"),
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+            metadata=obs_data.get("metadata", {}),
+        )
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict[str, Any]) -> VisualMemoryState:
+        return VisualMemoryState(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+        )

comparison.md

@@ -0,0 +1,168 @@
+# Visual Memory Gym — Model Comparison
+
+**Date**: 2026-03-18  
+**Gym Version**: `0.1.0`  
+**Scenarios**: 10 (across 4 task families)  
+**Models**: 5 (3 Anthropic, 2 OpenAI)  
+**Reward Modes**: custom (episode-level) and openenv (per-step transforms)
+
+---
+
+## Overall Results
+
+### Custom Rewards (episode-level from `rewards/base.py`)
+
+Reward components: Structural (0.25) + Ground Truth (0.60) + Efficiency (0.15) - Hallucination Penalty (up to -1.0)
+
+| # | Model | Avg Reward | Best Scenario | Worst Scenario | Total Time |
+|---|-------|:---:|---|---|---:|
+| 1 | `claude-opus-4-6` | **0.08** | flash_fade_minefield (0.63) | cascading_deduction (-0.83) | 1518.9s |
+| 2 | `gpt-5` | **-0.13** | flash_fade_minefield (0.69) | decoy_minefield (-0.78) | 2967.2s |
+| 3 | `gpt-5.4` | **-0.16** | partial_intel (0.63) | directional_trap (-0.81) | 225.1s |
+| 4 | `claude-opus-4-20250514` | **-0.17** | ambiguous_cluster (0.60) | cascading_deduction (-0.80) | 1197.4s |
+| 5 | `claude-sonnet-4-6` | **-0.33** | partial_intel (0.40) | directional_trap (-0.83) | 1105.2s |
+
+### OpenEnv Transform Rewards (per-step from `rewards/transforms/`)
+
+Reward components: Step Rewards (0.40) + Ground Truth (0.60) - Hallucination Penalty (up to -1.0)
+
+| # | Model | Avg Reward | Best Scenario | Worst Scenario | Total Time |
+|---|-------|:---:|---|---|---:|
+| 1 | `claude-opus-4-6` | **0.31** | directional_trap (0.37) | decoy_minefield (0.14) | 1584.6s |
+| 2 | `claude-opus-4-20250514` | **0.31** | ambiguous_cluster (0.55) | delayed_recall_keys (0.13) | 1185.2s |
+| 3 | `gpt-5` | **0.28** | flash_fade_minefield (0.53) | ambiguous_cluster (0.12) | 3770.8s |
+| 4 | `gpt-5.4` | **0.27** | fog_labyrinth (0.52) | directional_trap (0.08) | 287.4s |
+| 5 | `claude-sonnet-4-6` | **0.26** | ambiguous_cluster (0.35) | directional_trap (0.14) | 1048.0s |
+
+---
+
+## Per-Scenario Breakdown — Custom Rewards
+
+| Scenario | gpt-5.4 | gpt-5 | claude-sonnet-4-6 | claude-opus-4-6 | claude-opus-4-20250514 | Avg |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|
+| ambiguous_cluster_10x10 | 0.40 | -0.75 | 0.38 | 0.36 | 0.60 | **0.20** |
+| directional_trap_8x8 | -0.81 | 0.41 | -0.83 | 0.61 | 0.42 | **-0.04** |
+| partial_intel_9x9 | 0.63 | 0.42 | 0.40 | 0.41 | 0.44 | **0.46** |
+| flash_fade_minefield_7x7 | 0.42 | 0.69 | -0.78 | 0.63 | -0.76 | **0.04** |
+| delayed_recall_keys_8x8 | 0.45 | 0.53 | -0.80 | 0.43 | -0.79 | **-0.04** |
+| decoy_minefield_8x10 | -0.80 | -0.78 | -0.81 | -0.82 | -0.79 | **-0.80** |
+| fog_labyrinth_10x10 | -0.74 | 0.44 | 0.39 | 0.40 | 0.40 | **0.18** |
+| fog_key_hunt_8x8 | -0.73 | -0.77 | -0.79 | -0.80 | -0.79 | **-0.78** |
+| cascading_deduction_11x11 | -0.78 | -0.76 | -0.79 | -0.83 | -0.80 | **-0.79** |
+| safe_zone_identification_9x9 | 0.40 | -0.77 | 0.37 | 0.38 | 0.41 | **0.16** |
+
+### Hardest Scenarios (Custom)
+1. **decoy_minefield_8x10** (avg -0.80): All 5 models fail — hallucination penalty triggered universally
+2. **cascading_deduction_11x11** (avg -0.79): Large board with partial signals defeats all models
+3. **fog_key_hunt_8x8** (avg -0.78): Tiny viewport + fatal hazards — no model survives
+
+### Easiest Scenario (Custom)
+1. **partial_intel_9x9** (avg 0.46): Most models achieve positive rewards here
+
+---
+
+## Per-Scenario Breakdown — OpenEnv Transform Rewards
+
+| Scenario | gpt-5.4 | gpt-5 | claude-sonnet-4-6 | claude-opus-4-6 | claude-opus-4-20250514 | Avg |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|
+| ambiguous_cluster_10x10 | 0.33 | 0.12 | 0.35 | 0.35 | 0.55 | **0.34** |
+| directional_trap_8x8 | 0.08 | 0.36 | 0.14 | 0.37 | 0.36 | **0.26** |
+| partial_intel_9x9 | 0.32 | 0.34 | 0.34 | 0.36 | 0.36 | **0.34** |
+| flash_fade_minefield_7x7 | 0.35 | 0.53 | 0.34 | 0.34 | 0.35 | **0.38** |
+| delayed_recall_keys_8x8 | 0.34 | 0.34 | 0.34 | 0.36 | 0.13 | **0.30** |
+| decoy_minefield_8x10 | 0.14 | 0.14 | 0.14 | 0.14 | 0.34 | **0.18** |
+| fog_labyrinth_10x10 | 0.52 | 0.34 | 0.34 | 0.35 | 0.35 | **0.38** |
+| fog_key_hunt_8x8 | 0.13 | 0.13 | 0.15 | 0.15 | 0.15 | **0.14** |
+| cascading_deduction_11x11 | 0.13 | 0.14 | 0.15 | 0.35 | 0.14 | **0.18** |
+| safe_zone_identification_9x9 | 0.34 | 0.34 | 0.34 | 0.34 | 0.35 | **0.34** |
+
+### Hardest Scenarios (OpenEnv)
+1. **fog_key_hunt_8x8** (avg 0.14): Tiny viewport + fatal hazards — universally low
+2. **decoy_minefield_8x10** (avg 0.18): Decoy-key confusion trips all models
+3. **cascading_deduction_11x11** (avg 0.18): Large partial-signal board overwhelms reasoning
+
+### Easiest Scenarios (OpenEnv)
+1. **flash_fade_minefield_7x7** (avg 0.38): Pattern memory — some models excel here
+2. **fog_labyrinth_10x10** (avg 0.38): Fog navigation with reasonable viewport
+
+---
+
+## SOTA Average Assessment
+
+**SOTA models** (gpt-5.4, claude-sonnet-4-6, claude-opus-4-6):
+
+| Reward Mode | SOTA Average | Target Band | Status |
+|---|:---:|:---:|---|
+| Custom | **-0.14** | 0.60–0.70 | Well below target — no hardening needed |
+| OpenEnv | **0.28** | 0.60–0.70 | Below target — no hardening needed |
+
+**All 5 models average:**
+
+| Reward Mode | Overall Average |
+|---|:---:|
+| Custom | **-0.14** |
+| OpenEnv | **0.28** |
+
+The gym is currently **harder than target** across both reward modes. No hardening adjustments are required.
+
+---
+
+## Reward Mode Comparison
+
+| Metric | Custom | OpenEnv |
+|---|:---:|:---:|
+| Mean across all models | -0.14 | 0.28 |
+| Std deviation (models) | 0.15 | 0.02 |
+| Min model avg | -0.33 | 0.26 |
+| Max model avg | 0.08 | 0.31 |
+| Hallucination penalties hit | Frequent (-1.0) | None triggered |
+| Reward spread | Very high (variance from penalties) | Compressed (narrow 0.12–0.55 range) |
+
+**Key insight**: Custom rewards produce highly volatile scores driven by the -1.0 hallucination penalty. When models make even one incorrect assertion (tools report success but ground truth disagrees), the entire scenario score collapses. OpenEnv transform rewards are more granular and forgiving, rewarding incremental progress per-step.
+
+---
+
+## Model Speed Rankings
+
+| Model | Custom Time | OpenEnv Time | Avg per Scenario |
+|---|:---:|:---:|:---:|
+| `gpt-5.4` | 225.1s | 287.4s | ~26s |
+| `claude-sonnet-4-6` | 1105.2s | 1048.0s | ~108s |
+| `claude-opus-4-20250514` | 1197.4s | 1185.2s | ~119s |
+| `claude-opus-4-6` | 1518.9s | 1584.6s | ~155s |
+| `gpt-5` | 2967.2s | 3770.8s | ~337s |
+
+GPT-5.4 is 6x faster than the next model while achieving competitive results.
+
+---
+
+## Distractor Tool Usage
+
+Models occasionally used distractor/trap tools, which indicates susceptibility to misleading tool descriptions:
+
+- **`peek_hidden_cell`**: Used by claude-opus-4-6 and claude-sonnet-4-6 (cheating tool — gives hidden info but penalized)
+- **`undo_last_action`**: Used by claude-sonnet-4-6 (no-op trap)
+- **`reset_scenario`**: Used by multiple models (resets game state — wastes steps)
+- **`auto_solve`**: Not used by any model (good — most egregious trap avoided)
+
+---
+
+## Task Family Analysis
+
+| Task Family | Scenarios | Custom Avg | OpenEnv Avg | Difficulty |
+|---|---|:---:|:---:|---|
+| Hidden Grid (5) | ambiguous, directional, partial, cascading, safe_zone | -0.06 | 0.29 | Medium-Hard |
+| Pattern Memory (2) | flash_fade, delayed_recall | 0.00 | 0.34 | Medium |
+| Fog of War (2) | fog_labyrinth, fog_key_hunt | -0.30 | 0.26 | Hard |
+| Distractor Search (1) | decoy_minefield | -0.80 | 0.18 | Very Hard |
+
+---
+
+## Files
+
+| Type | Path |
+|---|---|
+| Custom results (all 5 models) | `results/visual_memory/run_visual_memory_custom.md` |
+| OpenEnv results (all 5 models) | `results/visual_memory/run_visual_memory_openenv.md` |
+| Custom trajectories (all 5 models) | `trajectories/visual_memory/run_visual_memory_custom/` |
+| OpenEnv trajectories (all 5 models) | `trajectories/visual_memory/run_visual_memory_openenv/` |

models.py

@@ -0,0 +1,82 @@
+"""
+Data models for the Visual Memory Environment.
+
+VisualMemoryAction has explicit Pydantic fields so the OpenEnv web
+interface renders interactive form inputs on HF Spaces.
+"""
+
+from __future__ import annotations
+
+import json as _json
+from typing import Any, Union
+
+from pydantic import ConfigDict, Field, TypeAdapter
+
+from openenv.core.env_server.mcp_types import (
+    CallToolAction,
+    CallToolObservation,
+    ListToolsAction,
+    ListToolsObservation,
+)
+from openenv.core.env_server.types import Action, Observation, State
+
+_mcp_action_adapter = TypeAdapter(Union[ListToolsAction, CallToolAction])
+
+_AVAILABLE_TOOLS = (
+    "list_tools, get_session_info, list_scenarios, load_scenario, "
+    "reset_scenario, get_board_view, get_status, reveal_cell, "
+    "inspect_region, flag_cell, unflag_cell, move_viewport, "
+    "submit_solution, recall_log, get_action_history, get_progress_stats, "
+    "auto_solve, peek_hidden_cell, undo_last_action"
+)
+
+
+class VisualMemoryAction(Action):
+    """Action with explicit fields for the web UI and MCP compatibility."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+        validate_assignment=True,
+        arbitrary_types_allowed=True,
+    )
+
+    tool_name: str = Field(
+        default="list_tools",
+        description=f"MCP tool to invoke. Available: {_AVAILABLE_TOOLS}",
+    )
+    arguments_json: str = Field(
+        default="{}",
+        description=(
+            'Tool arguments as a JSON string. Examples: '
+            '"{}" for no args, '
+            '\'{"scenario_id":"hidden_grid_01"}\' for load_scenario, '
+            '\'{"row":2,"col":3}\' for reveal_cell or flag_cell, '
+            '\'{"flagged_positions":"[[0,1],[2,3]]"}\' for submit_solution'
+        ),
+    )
+
+    @classmethod
+    def model_validate(cls, data: Any, **kwargs: Any) -> Action:
+        if isinstance(data, dict) and data.get("type") in ("call_tool", "list_tools"):
+            return _mcp_action_adapter.validate_python(data)
+        return super().model_validate(data, **kwargs)
+
+    def to_mcp_action(self) -> Action:
+        if self.tool_name == "list_tools":
+            return ListToolsAction()
+        args = _json.loads(self.arguments_json) if self.arguments_json else {}
+        return CallToolAction(tool_name=self.tool_name, arguments=args)
+
+
+VisualMemoryObservation = CallToolObservation
+VisualMemoryState = State
+
+__all__ = [
+    "VisualMemoryAction",
+    "VisualMemoryObservation",
+    "VisualMemoryState",
+    "CallToolAction",
+    "CallToolObservation",
+    "ListToolsAction",
+    "ListToolsObservation",
+]

openenv.yaml

@@ -0,0 +1,11 @@
+# OpenEnv Environment Manifest
+# Tells OpenEnv how to find and run this environment.
+# AutoEnv discovery reads this file to auto-connect clients.
+
+spec_version: 1
+name: visual_memory
+description: "Visual Memory (Phantom Grid) — hidden-state visual reasoning and planning under partial observability"
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000

openenv_visual_memory.egg-info/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: openenv-visual-memory
+Version: 0.1.0
+Summary: Visual Memory environment for OpenEnv — hidden-state visual reasoning and planning under partial observability
+Requires-Python: >=3.10
+Requires-Dist: openenv-core @ git+https://github.com/meta-pytorch/OpenEnv.git@v0.2.1
+Requires-Dist: fastmcp>=0.2.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn>=0.24.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: svgwrite>=1.4.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"

openenv_visual_memory.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+README.md
+__init__.py
+client.py
+models.py
+openenv.yaml
+pyproject.toml
+./__init__.py
+./client.py
+./models.py
+./openenv.yaml
+openenv_visual_memory.egg-info/PKG-INFO
+openenv_visual_memory.egg-info/SOURCES.txt
+openenv_visual_memory.egg-info/dependency_links.txt
+openenv_visual_memory.egg-info/entry_points.txt
+openenv_visual_memory.egg-info/requires.txt
+openenv_visual_memory.egg-info/top_level.txt
+server/__init__.py
+server/app.py
+server/engine.py
+server/memory_environment.py
+server/renderer.py

openenv_visual_memory.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openenv_visual_memory.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+server = visual_memory.server.app:main

openenv_visual_memory.egg-info/requires.txt

@@ -0,0 +1,13 @@
+openenv-core @ git+https://github.com/meta-pytorch/OpenEnv.git@v0.2.1
+fastmcp>=0.2.0
+fastapi>=0.115.0
+uvicorn>=0.24.0
+pydantic>=2.5.0
+httpx>=0.25.0
+numpy>=1.24.0
+svgwrite>=1.4.0
+python-dotenv>=1.0.0
+
+[dev]
+pytest>=8.0.0
+pytest-cov>=4.0.0

openenv_visual_memory.egg-info/top_level.txt

@@ -0,0 +1 @@
+visual_memory

pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-visual-memory"
+version = "0.1.0"
+description = "Visual Memory environment for OpenEnv — hidden-state visual reasoning and planning under partial observability"
+requires-python = ">=3.10"
+dependencies = [
+    "openenv-core @ git+https://github.com/meta-pytorch/OpenEnv.git@v0.2.1",
+    "fastmcp>=0.2.0",
+    "fastapi>=0.115.0",
+    "uvicorn>=0.24.0",
+    "pydantic>=2.5.0",
+    "httpx>=0.25.0",
+    "numpy>=1.24.0",
+    "svgwrite>=1.4.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0", "pytest-cov>=4.0.0"]
+
+[project.scripts]
+server = "visual_memory.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["visual_memory", "visual_memory.server"]
+package-dir = {"visual_memory" = ".", "visual_memory.server" = "server"}
+
+[tool.setuptools.package-data]
+visual_memory = ["openenv.yaml"]

scenarios/ambiguous_cluster_10x10.json

@@ -0,0 +1,19 @@
+{
+    "scenario_id": "ambiguous_cluster_10x10",
+    "type": "hidden_grid",
+    "seed": 9173,
+    "board_width": 10,
+    "board_height": 10,
+    "hazard_count": 18,
+    "decoy_count": 6,
+    "max_steps": 35,
+    "max_hazard_reveals": 2,
+    "signal_mode": "range",
+    "flags_count": 22,
+    "difficulty": "hard",
+    "description": "10x10 grid, 18 hazards, 6 decoys. Signals give ambiguous ranges (e.g. 1-3). Decoys visually resemble keys. Only 2 hazard reveals allowed before game over. 35 steps forces efficient exploration. Models must cross-reference multiple range signals to narrow down hazard locations — single-cell reasoning fails because ranges overlap.",
+    "tags": ["partial_observability", "visual_clutter", "unsafe_guess_penalty"],
+    "win_condition": {
+        "type": "flag_all_hazards"
+    }
+}

scenarios/cascading_deduction_11x11.json

@@ -0,0 +1,19 @@
+{
+    "scenario_id": "cascading_deduction_11x11",
+    "type": "hidden_grid",
+    "seed": 8401,
+    "board_width": 11,
+    "board_height": 11,
+    "hazard_count": 25,
+    "decoy_count": 5,
+    "max_steps": 38,
+    "max_hazard_reveals": 2,
+    "signal_mode": "partial",
+    "flags_count": 28,
+    "difficulty": "hard",
+    "description": "11x11 grid, 25 hazards, 5 decoys. Partial signals reveal only a subset of hazard directions plus a total hint. With 121 cells and 25 hazards, over 20% of the board is dangerous. The agent must chain partial deductions: signal A reveals 'N,E' out of 3 total → signal B at the inferred position reveals 'S,W' out of 2 → confirming hazard at intersection. Single-step reasoning sees incomplete clues. Models must track partial constraint sets across many reveals.",
+    "tags": ["partial_observability", "multi_stage_solution", "unsafe_guess_penalty"],
+    "win_condition": {
+        "type": "flag_all_hazards"
+    }
+}

scenarios/decoy_minefield_8x10.json

@@ -0,0 +1,20 @@
+{
+    "scenario_id": "decoy_minefield_8x10",
+    "type": "distractor_search",
+    "seed": 7742,
+    "board_width": 10,
+    "board_height": 8,
+    "hazard_count": 15,
+    "key_count": 4,
+    "decoy_count": 8,
+    "max_steps": 32,
+    "max_hazard_reveals": 2,
+    "signal_mode": "directional",
+    "flags_count": 18,
+    "difficulty": "hard",
+    "description": "8x10 grid, 15 hazards, 4 real keys, 8 decoys that look like keys in the SVG render. Directional signals point toward hazards but decoys are placed to create false safe corridors. The agent must collect all 4 real keys while avoiding 15 hazards and ignoring 8 decoys. Models that treat decoys as keys will waste steps or walk into traps trying to reach them.",
+    "tags": ["visual_clutter", "partial_observability", "multi_stage_solution"],
+    "win_condition": {
+        "type": "collect_keys"
+    }
+}

scenarios/delayed_recall_keys_8x8.json

@@ -0,0 +1,21 @@
+{
+    "scenario_id": "delayed_recall_keys_8x8",
+    "type": "pattern_memory",
+    "seed": 2289,
+    "board_width": 8,
+    "board_height": 8,
+    "hazard_count": 12,
+    "key_count": 5,
+    "max_steps": 30,
+    "max_hazard_reveals": 2,
+    "signal_mode": "count",
+    "flags_count": 15,
+    "difficulty": "hard",
+    "description": "8x8 grid, 12 hazards, 5 keys. 10 cells flash for 4 steps showing a mix of keys, hazards, and signals — then disappear. The agent must collect all 5 keys to win. After the flash fades, the agent must recall which flashed cells contained keys (safe to reveal) vs hazards (fatal to reveal). Revealing a remembered-hazard cell costs a life. This tests long-horizon memory: the recall happens 10-20 steps after the flash.",
+    "tags": ["delayed_recall", "partial_observability", "multi_stage_solution"],
+    "flash_cells": [[0,0],[0,7],[1,3],[2,5],[3,1],[3,6],[5,2],[5,5],[7,0],[7,7]],
+    "flash_until_step": 4,
+    "win_condition": {
+        "type": "collect_keys"
+    }
+}

scenarios/directional_trap_8x8.json

@@ -0,0 +1,19 @@
+{
+    "scenario_id": "directional_trap_8x8",
+    "type": "hidden_grid",
+    "seed": 4821,
+    "board_width": 8,
+    "board_height": 8,
+    "hazard_count": 14,
+    "decoy_count": 4,
+    "max_steps": 28,
+    "max_hazard_reveals": 1,
+    "signal_mode": "directional",
+    "flags_count": 16,
+    "difficulty": "hard",
+    "description": "8x8 grid, 14 hazards, directional signals ('N','SE', etc). Only 1 hazard reveal allowed — a single mistake is fatal. Decoys placed adjacent to hazard clusters create false patterns. The agent must triangulate hazard positions from multiple directional clues. Greedy flagging based on one signal will flag decoys incorrectly.",
+    "tags": ["partial_observability", "unsafe_guess_penalty", "visual_clutter"],
+    "win_condition": {
+        "type": "flag_all_hazards"
+    }
+}

scenarios/flash_fade_minefield_7x7.json

@@ -0,0 +1,20 @@
+{
+    "scenario_id": "flash_fade_minefield_7x7",
+    "type": "pattern_memory",
+    "seed": 6654,
+    "board_width": 7,
+    "board_height": 7,
+    "hazard_count": 10,
+    "max_steps": 25,
+    "max_hazard_reveals": 2,
+    "signal_mode": "count",
+    "flags_count": 13,
+    "difficulty": "hard",
+    "description": "7x7 grid, 10 hazards. At the start, 8 cells flash their content (mix of hazards and signals) for 3 steps, then fade to hidden. The agent must memorize which flashed cells were hazards vs signals, then use that recalled info combined with new reveals to flag all hazards. Models that ignore or misremember the flash phase will miss critical hazard locations.",
+    "tags": ["delayed_recall", "partial_observability", "unsafe_guess_penalty"],
+    "flash_cells": [[0,2],[1,4],[2,1],[2,5],[3,3],[4,0],[4,6],[6,3]],
+    "flash_until_step": 3,
+    "win_condition": {
+        "type": "flag_all_hazards"
+    }
+}

scenarios/fog_key_hunt_8x8.json

@@ -0,0 +1,22 @@
+{
+    "scenario_id": "fog_key_hunt_8x8",
+    "type": "fog_of_war",
+    "seed": 1193,
+    "board_width": 8,
+    "board_height": 8,
+    "hazard_count": 14,
+    "key_count": 6,
+    "decoy_count": 4,
+    "max_steps": 35,
+    "max_hazard_reveals": 1,
+    "signal_mode": "directional",
+    "flags_count": 16,
+    "difficulty": "hard",
+    "description": "8x8 grid, 14 hazards, 6 keys, 4 decoys, fog viewport radius 1 (3x3 window). Agent starts center (4,4). Must find and collect all 6 keys with only a tiny viewport. One hazard hit is fatal. Decoys look like keys but waste steps. The agent must systematically explore, remember where keys and hazards were seen, avoid decoys, and plan a safe path. Impulsive exploration kills.",
+    "tags": ["fog_of_war", "visual_clutter", "unsafe_guess_penalty", "delayed_recall"],
+    "start_position": [4, 4],
+    "viewport_radius": 1,
+    "win_condition": {
+        "type": "collect_keys"
+    }
+}

scenarios/fog_labyrinth_10x10.json

@@ -0,0 +1,20 @@
+{
+    "scenario_id": "fog_labyrinth_10x10",
+    "type": "fog_of_war",
+    "seed": 5518,
+    "board_width": 10,
+    "board_height": 10,
+    "hazard_count": 20,
+    "max_steps": 40,
+    "max_hazard_reveals": 2,
+    "signal_mode": "count",
+    "flags_count": 23,
+    "difficulty": "hard",
+    "description": "10x10 grid, 20 hazards, fog-of-war with viewport radius 2. Agent starts at corner (0,0) and can only see a 5x5 window. Must move viewport across the board, memorize revealed information from previous positions, and flag all 20 hazards. Revisiting areas wastes steps. Models must build and maintain an internal spatial map across 40 steps — most will forget early reveals by the time they need to submit.",
+    "tags": ["fog_of_war", "delayed_recall", "multi_stage_solution"],
+    "start_position": [0, 0],
+    "viewport_radius": 2,
+    "win_condition": {
+        "type": "flag_all_hazards"
+    }
+}

scenarios/partial_intel_9x9.json

@@ -0,0 +1,18 @@
+{
+    "scenario_id": "partial_intel_9x9",
+    "type": "hidden_grid",
+    "seed": 3307,
+    "board_width": 9,
+    "board_height": 9,
+    "hazard_count": 16,
+    "max_steps": 30,
+    "max_hazard_reveals": 2,
+    "signal_mode": "partial",
+    "flags_count": 19,
+    "difficulty": "hard",
+    "description": "9x9 grid, 16 hazards. Partial signal mode: each signal cell only reveals SOME of the directions where hazards lie, plus a hint of the total count. The agent must combine partial clues from neighboring signal cells to reconstruct the full picture. No single signal cell gives complete info — models that act on incomplete data will flag wrong cells.",
+    "tags": ["partial_observability", "multi_stage_solution", "unsafe_guess_penalty"],
+    "win_condition": {
+        "type": "flag_all_hazards"
+    }
+}

scenarios/safe_zone_identification_9x9.json

@@ -0,0 +1,19 @@
+{
+    "scenario_id": "safe_zone_identification_9x9",
+    "type": "hidden_grid",
+    "seed": 3956,
+    "board_width": 9,
+    "board_height": 9,
+    "hazard_count": 22,
+    "decoy_count": 7,
+    "max_steps": 30,
+    "max_hazard_reveals": 1,
+    "signal_mode": "range",
+    "flags_count": 25,
+    "difficulty": "hard",
+    "description": "9x9 grid, 22 hazards, 7 decoys. Win condition: identify ALL safe cells (non-hazard). With 81 cells and 22 hazards, there are 59 safe cells to find — but range signals give fuzzy counts (e.g. '1-3 hazards nearby'), and 7 decoys look suspicious but are actually safe. One hazard hit is fatal. The agent must prove cells are safe by elimination rather than flagging hazards. This inverts the usual strategy and punishes models that default to hazard-flagging heuristics.",
+    "tags": ["partial_observability", "visual_clutter", "unsafe_guess_penalty", "multi_stage_solution"],
+    "win_condition": {
+        "type": "identify_safe_cells"
+    }
+}

server/app.py

@@ -0,0 +1,47 @@
+"""
+FastAPI application entrypoint for the Visual Memory environment.
+
+Uses OpenEnv's create_app() factory which auto-generates:
+  - POST /reset, POST /step, GET /state, GET /health
+  - WebSocket /ws for persistent connections
+  - /web interface (when ENABLE_WEB_INTERFACE=true on HF Spaces)
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from dotenv import load_dotenv
+from openenv.core.env_server.http_server import create_app
+
+load_dotenv(os.path.join(os.path.dirname(__file__), "..", ".env"))
+
+try:
+    from visual_memory.models import VisualMemoryAction, VisualMemoryObservation
+    from visual_memory.server.memory_environment import MemoryEnvironment
+except ImportError:
+    sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+    from models import VisualMemoryAction, VisualMemoryObservation
+    from server.memory_environment import MemoryEnvironment
+
+
+MAX_CONCURRENT_ENVS = int(os.getenv("MAX_CONCURRENT_ENVS", "8"))
+
+app = create_app(
+    MemoryEnvironment,
+    VisualMemoryAction,
+    VisualMemoryObservation,
+    env_name="visual_memory",
+    max_concurrent_envs=MAX_CONCURRENT_ENVS,
+)
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    import uvicorn
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

server/engine.py

@@ -0,0 +1,712 @@
+"""Hidden-state game engine for Visual Memory Gym.
+
+Manages in-memory board state, hidden cell contents, move validation,
+and win/loss conditions across four task families:
+
+  1. hidden_grid       — deduce hazard locations from signal clues
+  2. pattern_memory    — recall briefly-shown cell contents
+  3. distractor_search — identify targets among visually similar decoys
+  4. fog_of_war        — plan under limited viewport radius
+"""
+
+from __future__ import annotations
+
+import copy
+from enum import Enum
+from typing import Any
+
+import numpy as np
+from pydantic import BaseModel, Field
+
+
+class CellType(str, Enum):
+    EMPTY = "empty"
+    HAZARD = "hazard"
+    SIGNAL = "signal"
+    KEY = "key"
+    DECOY = "decoy"
+    GOAL = "goal"
+
+
+class CellState(str, Enum):
+    HIDDEN = "hidden"
+    REVEALED = "revealed"
+    FLAGGED = "flagged"
+    FADED = "faded"
+
+
+class ScenarioType(str, Enum):
+    HIDDEN_GRID = "hidden_grid"
+    PATTERN_MEMORY = "pattern_memory"
+    DISTRACTOR_SEARCH = "distractor_search"
+    FOG_OF_WAR = "fog_of_war"
+
+
+class SignalMode(str, Enum):
+    COUNT = "count"
+    DIRECTIONAL = "directional"
+    RANGE = "range"
+    PARTIAL = "partial"
+
+
+class WinCondition(str, Enum):
+    FLAG_ALL_HAZARDS = "flag_all_hazards"
+    COLLECT_KEYS = "collect_keys"
+    IDENTIFY_SAFE = "identify_safe_cells"
+    REACH_GOAL = "reach_goal"
+
+
+class BoardState(BaseModel):
+    """Serializable snapshot of the game state (visible portion only)."""
+
+    session_id: str = ""
+    scenario_id: str = ""
+    scenario_type: str = "hidden_grid"
+    step_count: int = 0
+    board_width: int = 0
+    board_height: int = 0
+    visible_cells: list[list[dict]] = Field(default_factory=list)
+    discovered_signals: list[dict] = Field(default_factory=list)
+    memory_events: list[dict] = Field(default_factory=list)
+    game_over: bool = False
+    won: bool = False
+    flags_remaining: int = 0
+    cells_revealed: int = 0
+    hazard_hits: int = 0
+    keys_collected: int = 0
+    max_steps: int = 50
+
+
+NEIGHBOR_OFFSETS = [
+    (-1, -1), (-1, 0), (-1, 1),
+    (0, -1),           (0, 1),
+    (1, -1),  (1, 0),  (1, 1),
+]
+
+DIRECTION_NAMES = {
+    (-1, -1): "NW", (-1, 0): "N", (-1, 1): "NE",
+    (0, -1): "W",                   (0, 1): "E",
+    (1, -1): "SW",  (1, 0): "S",  (1, 1): "SE",
+}
+
+
+class GameEngine:
+    """In-memory game engine for the Visual Memory gym.
+
+    Deterministic given a seed. All state lives in Python memory.
+    """
+
+    def __init__(self, scenario: dict, seed: int | None = None):
+        self.scenario_id: str = scenario["scenario_id"]
+        self.scenario_type = ScenarioType(scenario.get("type", "hidden_grid"))
+        self.width: int = scenario["board_width"]
+        self.height: int = scenario["board_height"]
+        self.max_steps: int = scenario.get("max_steps", 50)
+        self.max_hazard_reveals: int = scenario.get("max_hazard_reveals", 3)
+        self.signal_mode = SignalMode(scenario.get("signal_mode", "count"))
+        self.win_condition = WinCondition(
+            scenario.get("win_condition", {}).get("type", "flag_all_hazards")
+        )
+
+        resolved_seed = seed if seed is not None else scenario.get("seed", 42)
+        self._rng = np.random.default_rng(resolved_seed)
+
+        self.step_count: int = 0
+        self.hazard_hits: int = 0
+        self.keys_collected: int = 0
+        self.cells_revealed: int = 0
+        self.game_over: bool = False
+        self.won: bool = False
+
+        if "layout" in scenario:
+            self._hidden = self._load_explicit_layout(scenario["layout"])
+        else:
+            self._hidden = self._generate_board(scenario)
+
+        self._visible: list[list[dict]] = [
+            [{"state": CellState.HIDDEN.value, "content": None} for _ in range(self.width)]
+            for _ in range(self.height)
+        ]
+
+        total_hazards = sum(
+            1
+            for r in range(self.height)
+            for c in range(self.width)
+            if self._hidden[r][c]["type"] == CellType.HAZARD.value
+        )
+        self.total_flags: int = scenario.get("flags_count", total_hazards + 3)
+        self.flags_placed: int = 0
+
+        self.total_keys: int = sum(
+            1
+            for r in range(self.height)
+            for c in range(self.width)
+            if self._hidden[r][c]["type"] == CellType.KEY.value
+        )
+
+        self._discovered_signals: list[dict] = []
+        self._memory_events: list[dict] = []
+        self._action_log: list[dict] = []
+
+        self._viewport_center: list[int] | None = scenario.get("start_position")
+        self._viewport_radius: int | None = scenario.get("viewport_radius")
+
+        self._flash_cells: list[list[int]] = scenario.get("flash_cells", [])
+        self._flash_until_step: int = scenario.get("flash_until_step", 0)
+        if self.scenario_type == ScenarioType.PATTERN_MEMORY and self._flash_cells:
+            for rc in self._flash_cells:
+                r, c = rc[0], rc[1]
+                cell = self._hidden[r][c]
+                self._visible[r][c] = {
+                    "state": CellState.REVEALED.value,
+                    "content": copy.deepcopy(cell),
+                }
+                self._memory_events.append({
+                    "step": 0,
+                    "event": "flash_shown",
+                    "row": r,
+                    "col": c,
+                    "content": copy.deepcopy(cell),
+                })
+
+    # ─── Board Generation ───────────────────────────────────────────
+
+    def _load_explicit_layout(self, layout: list[list[dict]]) -> list[list[dict]]:
+        board: list[list[dict]] = []
+        for row_data in layout:
+            row: list[dict] = []
+            for cell in row_data:
+                row.append({
+                    "type": cell.get("type", CellType.EMPTY.value),
+                    "value": cell.get("value"),
+                    "properties": cell.get("properties", {}),
+                })
+            board.append(row)
+        return board
+
+    def _generate_board(self, scenario: dict) -> list[list[dict]]:
+        hazard_count = scenario.get("hazard_count", 10)
+        key_count = scenario.get("key_count", 0)
+        decoy_count = scenario.get("decoy_count", 0)
+        goal_count = 1 if self.win_condition == WinCondition.REACH_GOAL else 0
+
+        total_cells = self.width * self.height
+        total_special = hazard_count + key_count + decoy_count + goal_count
+        if total_special > total_cells:
+            raise ValueError(
+                f"Cannot place {total_special} special cells on a "
+                f"{self.width}x{self.height} board ({total_cells} cells)"
+            )
+
+        positions = self._rng.permutation(total_cells)
+        board: list[list[dict]] = [
+            [{"type": CellType.EMPTY.value, "value": None, "properties": {}} for _ in range(self.width)]
+            for _ in range(self.height)
+        ]
+
+        idx = 0
+        for _ in range(hazard_count):
+            r, c = divmod(int(positions[idx]), self.width)
+            board[r][c] = {"type": CellType.HAZARD.value, "value": None, "properties": {}}
+            idx += 1
+
+        for i in range(key_count):
+            r, c = divmod(int(positions[idx]), self.width)
+            board[r][c] = {"type": CellType.KEY.value, "value": f"key_{i}", "properties": {}}
+            idx += 1
+
+        for i in range(decoy_count):
+            r, c = divmod(int(positions[idx]), self.width)
+            board[r][c] = {"type": CellType.DECOY.value, "value": f"decoy_{i}", "properties": {}}
+            idx += 1
+
+        if goal_count:
+            r, c = divmod(int(positions[idx]), self.width)
+            board[r][c] = {"type": CellType.GOAL.value, "value": None, "properties": {}}
+            idx += 1
+
+        self._compute_signals(board)
+        return board
+
+    def _compute_signals(self, board: list[list[dict]]) -> None:
+        for r in range(self.height):
+            for c in range(self.width):
+                if board[r][c]["type"] != CellType.EMPTY.value:
+                    continue
+
+                if self.signal_mode == SignalMode.COUNT:
+                    count = self._count_adjacent_hazards(board, r, c)
+                    if count > 0:
+                        board[r][c] = {
+                            "type": CellType.SIGNAL.value,
+                            "value": count,
+                            "properties": {"mode": "count"},
+                        }
+
+                elif self.signal_mode == SignalMode.DIRECTIONAL:
+                    directions = self._get_hazard_directions(board, r, c)
+                    if directions:
+                        board[r][c] = {
+                            "type": CellType.SIGNAL.value,
+                            "value": directions,
+                            "properties": {"mode": "directional"},
+                        }
+
+                elif self.signal_mode == SignalMode.RANGE:
+                    count = self._count_adjacent_hazards(board, r, c)
+                    if count > 0:
+                        noise = int(self._rng.integers(0, 2))
+                        low = max(0, count - noise)
+                        high = count + int(self._rng.integers(0, 2))
+                        board[r][c] = {
+                            "type": CellType.SIGNAL.value,
+                            "value": {"min": low, "max": high},
+                            "properties": {"mode": "range"},
+                        }
+
+                elif self.signal_mode == SignalMode.PARTIAL:
+                    directions = self._get_hazard_directions(board, r, c)
+                    if directions:
+                        shown = max(1, len(directions) // 2)
+                        indices = self._rng.choice(
+                            len(directions), size=shown, replace=False
+                        )
+                        subset = [directions[i] for i in sorted(indices)]
+                        board[r][c] = {
+                            "type": CellType.SIGNAL.value,
+                            "value": subset,
+                            "properties": {
+                                "mode": "partial",
+                                "total_hint": len(directions),
+                            },
+                        }
+
+    def _count_adjacent_hazards(self, board: list[list[dict]], r: int, c: int) -> int:
+        count = 0
+        for dr, dc in NEIGHBOR_OFFSETS:
+            nr, nc = r + dr, c + dc
+            if 0 <= nr < self.height and 0 <= nc < self.width:
+                if board[nr][nc]["type"] == CellType.HAZARD.value:
+                    count += 1
+        return count
+
+    def _get_hazard_directions(self, board: list[list[dict]], r: int, c: int) -> list[str]:
+        dirs: list[str] = []
+        for (dr, dc), name in DIRECTION_NAMES.items():
+            nr, nc = r + dr, c + dc
+            if 0 <= nr < self.height and 0 <= nc < self.width:
+                if board[nr][nc]["type"] == CellType.HAZARD.value:
+                    dirs.append(name)
+        return dirs
+
+    # ─── Pattern Memory Phase ───────────────────────────────────────
+
+    def _tick_pattern_memory(self) -> None:
+        if self.scenario_type != ScenarioType.PATTERN_MEMORY:
+            return
+        if self.step_count != self._flash_until_step:
+            return
+        for rc in self._flash_cells:
+            r, c = rc[0], rc[1]
+            if self._visible[r][c]["state"] == CellState.REVEALED.value:
+                self._visible[r][c] = {"state": CellState.FADED.value, "content": None}
+                self._memory_events.append({
+                    "step": self.step_count,
+                    "event": "flash_faded",
+                    "row": r,
+                    "col": c,
+                })
+
+    # ─── Core Actions ───────────────────────────────────────────────
+
+    def reveal_cell(self, row: int, col: int) -> dict:
+        if self.game_over:
+            return {"error": "Game is already over.", "row": row, "col": col}
+
+        if not self._in_bounds(row, col):
+            return {"error": f"({row},{col}) is out of bounds.", "row": row, "col": col}
+
+        vis = self._visible[row][col]
+        if vis["state"] in (CellState.REVEALED.value, CellState.FLAGGED.value):
+            return {
+                "error": f"Cell ({row},{col}) is already {vis['state']}.",
+                "row": row,
+                "col": col,
+            }
+
+        if self._viewport_radius is not None and self._viewport_center is not None:
+            vr, vc = self._viewport_center
+            if abs(row - vr) > self._viewport_radius or abs(col - vc) > self._viewport_radius:
+                return {
+                    "error": f"({row},{col}) is outside your current viewport.",
+                    "row": row,
+                    "col": col,
+                }
+
+        self.step_count += 1
+        self._tick_pattern_memory()
+
+        hidden = self._hidden[row][col]
+        cell_type = hidden["type"]
+
+        self._visible[row][col] = {
+            "state": CellState.REVEALED.value,
+            "content": copy.deepcopy(hidden),
+        }
+        self.cells_revealed += 1
+
+        result: dict[str, Any] = {
+            "row": row,
+            "col": col,
+            "type": cell_type,
+            "value": hidden.get("value"),
+            "properties": hidden.get("properties", {}),
+        }
+
+        if cell_type == CellType.SIGNAL.value:
+            self._discovered_signals.append(result)
+
+        if cell_type == CellType.HAZARD.value:
+            self.hazard_hits += 1
+            result["hazard_hit"] = True
+            if self.hazard_hits >= self.max_hazard_reveals:
+                self.game_over = True
+                self.won = False
+                result["game_over"] = True
+                result["message"] = "Too many hazards revealed. Game over."
+
+        if cell_type == CellType.KEY.value:
+            self.keys_collected += 1
+            result["key_collected"] = True
+            if (
+                self.win_condition == WinCondition.COLLECT_KEYS
+                and self.keys_collected >= self.total_keys
+            ):
+                self.game_over = True
+                self.won = True
+                result["game_over"] = True
+                result["message"] = "All keys collected. You win!"
+
+        if cell_type == CellType.GOAL.value and self.win_condition == WinCondition.REACH_GOAL:
+            self.game_over = True
+            self.won = True
+            result["game_over"] = True
+            result["message"] = "Goal reached. You win!"
+
+        if self.step_count >= self.max_steps and not self.game_over:
+            self.game_over = True
+            self.won = False
+            result["game_over"] = True
+            result["message"] = "Max steps exceeded. Game over."
+
+        self._action_log.append({
+            "action": "reveal",
+            "row": row,
+            "col": col,
+            "step": self.step_count,
+            "result_type": cell_type,
+        })
+        return result
+
+    def flag_cell(self, row: int, col: int) -> dict:
+        if self.game_over:
+            return {"error": "Game is already over.", "row": row, "col": col}
+
+        if not self._in_bounds(row, col):
+            return {"error": f"({row},{col}) is out of bounds.", "row": row, "col": col}
+
+        vis = self._visible[row][col]
+        if vis["state"] == CellState.REVEALED.value:
+            return {"error": f"Cell ({row},{col}) is already revealed; cannot flag.", "row": row, "col": col}
+        if vis["state"] == CellState.FLAGGED.value:
+            return {"error": f"Cell ({row},{col}) is already flagged.", "row": row, "col": col}
+
+        if self.flags_placed >= self.total_flags:
+            return {"error": "No flags remaining.", "row": row, "col": col}
+
+        self.step_count += 1
+        self._tick_pattern_memory()
+
+        self._visible[row][col] = {"state": CellState.FLAGGED.value, "content": None}
+        self.flags_placed += 1
+
+        self._action_log.append({"action": "flag", "row": row, "col": col, "step": self.step_count})
+        self._check_flag_win()
+
+        result: dict[str, Any] = {
+            "row": row,
+            "col": col,
+            "flagged": True,
+            "flags_remaining": self.total_flags - self.flags_placed,
+        }
+        if self.game_over and self.won:
+            result["game_over"] = True
+            result["message"] = "All hazards correctly flagged. You win!"
+
+        if self.step_count >= self.max_steps and not self.game_over:
+            self.game_over = True
+            self.won = False
+            result["game_over"] = True
+            result["message"] = "Max steps exceeded. Game over."
+
+        return result
+
+    def unflag_cell(self, row: int, col: int) -> dict:
+        if self.game_over:
+            return {"error": "Game is already over.", "row": row, "col": col}
+
+        if not self._in_bounds(row, col):
+            return {"error": f"({row},{col}) is out of bounds.", "row": row, "col": col}
+
+        if self._visible[row][col]["state"] != CellState.FLAGGED.value:
+            return {"error": f"Cell ({row},{col}) is not flagged.", "row": row, "col": col}
+
+        self.step_count += 1
+        self._tick_pattern_memory()
+
+        self._visible[row][col] = {"state": CellState.HIDDEN.value, "content": None}
+        self.flags_placed -= 1
+
+        self._action_log.append({"action": "unflag", "row": row, "col": col, "step": self.step_count})
+
+        result: dict[str, Any] = {
+            "row": row,
+            "col": col,
+            "unflagged": True,
+            "flags_remaining": self.total_flags - self.flags_placed,
+        }
+
+        if self.step_count >= self.max_steps and not self.game_over:
+            self.game_over = True
+            self.won = False
+            result["game_over"] = True
+            result["message"] = "Max steps exceeded. Game over."
+
+        return result
+
+    def move_viewport(self, row: int, col: int) -> dict:
+        if self.scenario_type != ScenarioType.FOG_OF_WAR:
+            return {"error": "move_viewport is only available in fog_of_war scenarios."}
+
+        if self.game_over:
+            return {"error": "Game is already over."}
+
+        if not self._in_bounds(row, col):
+            return {"error": f"({row},{col}) is out of bounds."}
+
+        self.step_count += 1
+        self._tick_pattern_memory()
+
+        self._viewport_center = [row, col]
+        self._action_log.append({
+            "action": "move_viewport",
+            "row": row,
+            "col": col,
+            "step": self.step_count,
+        })
+
+        if self.step_count >= self.max_steps and not self.game_over:
+            self.game_over = True
+            self.won = False
+
+        return {
+            "viewport_center": [row, col],
+            "viewport_radius": self._viewport_radius,
+            "visible_area": self._get_viewport_bounds(),
+        }
+
+    def submit_solution(
+        self,
+        flagged_positions: list[list[int]] | None = None,
+        safe_positions: list[list[int]] | None = None,
+    ) -> dict:
+        if self.game_over:
+            return {"error": "Game is already over."}
+
+        self.step_count += 1
+        self.game_over = True
+
+        if self.win_condition == WinCondition.FLAG_ALL_HAZARDS:
+            return self._judge_flag_solution(flagged_positions or [])
+        elif self.win_condition == WinCondition.IDENTIFY_SAFE:
+            return self._judge_safe_solution(safe_positions or [])
+        elif self.win_condition == WinCondition.COLLECT_KEYS:
+            success = self.keys_collected >= self.total_keys
+            self.won = success
+            return {
+                "correct": success,
+                "keys_collected": self.keys_collected,
+                "keys_required": self.total_keys,
+            }
+        elif self.win_condition == WinCondition.REACH_GOAL:
+            self.won = False
+            return {"correct": False, "message": "Goal was not reached before submission."}
+
+        return {"error": "Unknown win condition."}
+
+    # ─── State Queries ──────────────────────────────────────────────
+
+    def get_visible_board(self) -> list[list[dict]]:
+        if self._viewport_radius is None or self._viewport_center is None:
+            return copy.deepcopy(self._visible)
+
+        vr, vc = self._viewport_center
+        rad = self._viewport_radius
+        fog_board: list[list[dict]] = [
+            [{"state": "fog", "content": None} for _ in range(self.width)]
+            for _ in range(self.height)
+        ]
+        for r in range(max(0, vr - rad), min(self.height, vr + rad + 1)):
+            for c in range(max(0, vc - rad), min(self.width, vc + rad + 1)):
+                fog_board[r][c] = copy.deepcopy(self._visible[r][c])
+        return fog_board
+
+    def get_status(self) -> dict:
+        return {
+            "scenario_id": self.scenario_id,
+            "scenario_type": self.scenario_type.value,
+            "step_count": self.step_count,
+            "max_steps": self.max_steps,
+            "board_size": f"{self.width}x{self.height}",
+            "cells_revealed": self.cells_revealed,
+            "hazard_hits": self.hazard_hits,
+            "max_hazard_reveals": self.max_hazard_reveals,
+            "keys_collected": self.keys_collected,
+            "total_keys": self.total_keys,
+            "flags_placed": self.flags_placed,
+            "flags_remaining": self.total_flags - self.flags_placed,
+            "game_over": self.game_over,
+            "won": self.won,
+            "win_condition": self.win_condition.value,
+        }
+
+    def get_board_state(self, session_id: str = "") -> BoardState:
+        return BoardState(
+            session_id=session_id,
+            scenario_id=self.scenario_id,
+            scenario_type=self.scenario_type.value,
+            step_count=self.step_count,
+            board_width=self.width,
+            board_height=self.height,
+            visible_cells=self.get_visible_board(),
+            discovered_signals=copy.deepcopy(self._discovered_signals),
+            memory_events=copy.deepcopy(self._memory_events),
+            game_over=self.game_over,
+            won=self.won,
+            flags_remaining=self.total_flags - self.flags_placed,
+            cells_revealed=self.cells_revealed,
+            hazard_hits=self.hazard_hits,
+            keys_collected=self.keys_collected,
+            max_steps=self.max_steps,
+        )
+
+    def get_hidden_board(self) -> list[list[dict]]:
+        """Full hidden board — for reward computation only, never sent to agent."""
+        return copy.deepcopy(self._hidden)
+
+    def get_action_log(self) -> list[dict]:
+        return copy.deepcopy(self._action_log)
+
+    # ─── Internal Helpers ───────────────────────────────────────────
+
+    def _in_bounds(self, row: int, col: int) -> bool:
+        return 0 <= row < self.height and 0 <= col < self.width
+
+    def _get_viewport_bounds(self) -> dict:
+        if self._viewport_center is None or self._viewport_radius is None:
+            return {
+                "r_min": 0,
+                "r_max": self.height - 1,
+                "c_min": 0,
+                "c_max": self.width - 1,
+            }
+        vr, vc = self._viewport_center
+        rad = self._viewport_radius
+        return {
+            "r_min": max(0, vr - rad),
+            "r_max": min(self.height - 1, vr + rad),
+            "c_min": max(0, vc - rad),
+            "c_max": min(self.width - 1, vc + rad),
+        }
+
+    def _check_flag_win(self) -> None:
+        if self.win_condition != WinCondition.FLAG_ALL_HAZARDS:
+            return
+
+        for r in range(self.height):
+            for c in range(self.width):
+                is_hazard = self._hidden[r][c]["type"] == CellType.HAZARD.value
+                is_flagged = self._visible[r][c]["state"] == CellState.FLAGGED.value
+                if is_hazard and not is_flagged:
+                    return
+
+        wrong_flags = sum(
+            1
+            for r in range(self.height)
+            for c in range(self.width)
+            if self._visible[r][c]["state"] == CellState.FLAGGED.value
+            and self._hidden[r][c]["type"] != CellType.HAZARD.value
+        )
+        if wrong_flags == 0:
+            self.game_over = True
+            self.won = True
+
+    def _judge_flag_solution(self, flagged: list[list[int]]) -> dict:
+        actual_hazards: set[tuple[int, int]] = set()
+        for r in range(self.height):
+            for c in range(self.width):
+                if self._hidden[r][c]["type"] == CellType.HAZARD.value:
+                    actual_hazards.add((r, c))
+
+        submitted: set[tuple[int, int]] = {(p[0], p[1]) for p in flagged}
+        for r in range(self.height):
+            for c in range(self.width):
+                if self._visible[r][c]["state"] == CellState.FLAGGED.value:
+                    submitted.add((r, c))
+
+        correct = submitted & actual_hazards
+        missed = actual_hazards - submitted
+        wrong = submitted - actual_hazards
+
+        precision = len(correct) / len(submitted) if submitted else 0.0
+        recall = len(correct) / len(actual_hazards) if actual_hazards else 1.0
+
+        self.won = len(missed) == 0 and len(wrong) == 0
+
+        return {
+            "correct": self.won,
+            "hazards_found": len(correct),
+            "hazards_total": len(actual_hazards),
+            "missed": len(missed),
+            "wrong_flags": len(wrong),
+            "precision": round(precision, 3),
+            "recall": round(recall, 3),
+        }
+
+    def _judge_safe_solution(self, safe_positions: list[list[int]]) -> dict:
+        actual_safe: set[tuple[int, int]] = set()
+        for r in range(self.height):
+            for c in range(self.width):
+                if self._hidden[r][c]["type"] != CellType.HAZARD.value:
+                    actual_safe.add((r, c))
+
+        submitted: set[tuple[int, int]] = {(p[0], p[1]) for p in safe_positions}
+
+        correct = submitted & actual_safe
+        false_safe = submitted - actual_safe
+        missed_safe = actual_safe - submitted
+
+        precision = len(correct) / len(submitted) if submitted else 0.0
+        recall = len(correct) / len(actual_safe) if actual_safe else 1.0
+
+        self.won = len(false_safe) == 0 and len(missed_safe) == 0
+
+        return {
+            "correct": self.won,
+            "safe_found": len(correct),
+            "safe_total": len(actual_safe),
+            "false_safe": len(false_safe),
+            "missed_safe": len(missed_safe),
+            "precision": round(precision, 3),
+            "recall": round(recall, 3),
+        }

server/memory_environment.py

@@ -0,0 +1,620 @@
+"""Visual Memory Environment — built on OpenEnv's MCPEnvironment.
+
+Exposes MCP tools for hidden-state visual reasoning under partial
+observability. Supports four task families: hidden-grid deduction,
+pattern memory, distractor search, and fog-of-war planning.
+
+Tool categories:
+  - Session: get_session_info, list_scenarios, load_scenario, reset_scenario
+  - Observation: get_board_view, get_status, reveal_cell, inspect_region
+  - Action: flag_cell, unflag_cell, move_viewport, submit_solution
+  - Memory: recall_log, get_action_history, get_progress_stats
+  - Distractor (traps): auto_solve, peek_hidden_cell, undo_last_action
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any, Optional
+from uuid import uuid4
+
+from fastmcp import FastMCP
+
+from openenv.core.env_server.mcp_environment import MCPEnvironment
+from openenv.core.env_server.types import Action, EnvironmentMetadata, Observation, State
+
+from .engine import GameEngine
+from .renderer import Renderer
+
+logger = logging.getLogger(__name__)
+
+def _resolve_scenarios_dir() -> str:
+    """Find scenarios/ dir — works both locally and inside Docker."""
+    candidates = [
+        os.environ.get("VISUAL_MEMORY_SCENARIOS_DIR", ""),
+        os.path.join(os.path.dirname(__file__), "..", "scenarios"),
+        os.path.join(os.getcwd(), "scenarios"),
+        "/app/env/scenarios",
+    ]
+    for path in candidates:
+        if path and os.path.isdir(path):
+            return path
+    return os.path.join(os.path.dirname(__file__), "..", "scenarios")
+
+
+SCENARIOS_DIR = _resolve_scenarios_dir()
+
+
+def _load_scenario_file(scenario_id: str) -> dict:
+    path = os.path.join(SCENARIOS_DIR, f"{scenario_id}.json")
+    if not os.path.isfile(path):
+        raise FileNotFoundError(f"Scenario '{scenario_id}' not found at {path}")
+    with open(path, "r") as f:
+        return json.load(f)
+
+
+def _list_available_scenarios() -> list[dict]:
+    if not os.path.isdir(SCENARIOS_DIR):
+        return []
+    scenarios: list[dict] = []
+    for fname in sorted(os.listdir(SCENARIOS_DIR)):
+        if not fname.endswith(".json"):
+            continue
+        try:
+            data = _load_scenario_file(fname.replace(".json", ""))
+            scenarios.append({
+                "scenario_id": data.get("scenario_id", fname.replace(".json", "")),
+                "type": data.get("type", "hidden_grid"),
+                "difficulty": data.get("difficulty", "hard"),
+                "board_size": f"{data.get('board_width', '?')}x{data.get('board_height', '?')}",
+                "description": data.get("description", ""),
+                "tags": data.get("tags", []),
+            })
+        except Exception:
+            continue
+    return scenarios
+
+
+class MemoryEnvironment(MCPEnvironment):
+    """OpenEnv environment for Visual Memory Gym.
+
+    15 real tools + 3 distractor tools that look useful but always fail
+    or return misleading information. Models must learn to avoid them.
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self):
+        mcp = FastMCP("visual_memory")
+
+        self._engine: Optional[GameEngine] = None
+        self._renderer = Renderer()
+        self._session_id: Optional[str] = None
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._action_history: list[dict] = []
+        self._last_action_tool: Optional[str] = None
+        self._recall_used_recently: bool = False
+
+        # ────────────────────────────────────────
+        # Session Tools
+        # ────────────────────────────────────────
+
+        @mcp.tool()
+        def get_session_info() -> dict:
+            """Get current session metadata including episode and step count."""
+            return {
+                "session_id": self._session_id,
+                "episode_id": self._state.episode_id,
+                "step_count": self._state.step_count,
+                "scenario_loaded": self._engine is not None,
+                "scenario_id": self._engine.scenario_id if self._engine else None,
+            }
+
+        @mcp.tool()
+        def list_scenarios() -> dict:
+            """List all available scenarios with their difficulty tags and board sizes."""
+            scenarios = _list_available_scenarios()
+            return {"scenarios": scenarios, "count": len(scenarios)}
+
+        @mcp.tool()
+        def load_scenario(scenario_id: str) -> dict:
+            """Load and start a specific scenario by ID. Resets any in-progress game."""
+            try:
+                data = _load_scenario_file(scenario_id)
+            except FileNotFoundError as e:
+                return {"error": str(e)}
+
+            self._engine = GameEngine(data)
+            self._action_history = []
+            self._recall_used_recently = False
+
+            board_state = self._engine.get_board_state(self._session_id or "")
+            view = self._renderer.get_board_view(
+                board_state.visible_cells,
+                board_state.board_width,
+                board_state.board_height,
+                scenario_type=board_state.scenario_type,
+                step_count=board_state.step_count,
+            )
+
+            return {
+                "loaded": True,
+                "scenario_id": scenario_id,
+                "board_size": f"{self._engine.width}x{self._engine.height}",
+                "scenario_type": self._engine.scenario_type.value,
+                "win_condition": self._engine.win_condition.value,
+                "max_steps": self._engine.max_steps,
+                "board_view": view,
+            }
+
+        @mcp.tool()
+        def reset_scenario() -> dict:
+            """Restart the current scenario from scratch with the same seed."""
+            if self._engine is None:
+                return {"error": "No scenario loaded. Use load_scenario first."}
+
+            scenario_id = self._engine.scenario_id
+            try:
+                data = _load_scenario_file(scenario_id)
+            except FileNotFoundError as e:
+                return {"error": str(e)}
+
+            self._engine = GameEngine(data)
+            self._action_history = []
+            self._recall_used_recently = False
+
+            return {
+                "reset": True,
+                "scenario_id": scenario_id,
+                "board_size": f"{self._engine.width}x{self._engine.height}",
+            }
+
+        # ────────────────────────────────────────
+        # Observation Tools
+        # ────────────────────────────────────────
+
+        @mcp.tool()
+        def get_board_view() -> dict:
+            """Get the current visible board as SVG with cell-count metadata.
+            Does not consume a game step."""
+            if self._engine is None:
+                return {"error": "No scenario loaded."}
+
+            board_state = self._engine.get_board_state(self._session_id or "")
+            return self._renderer.get_board_view(
+                board_state.visible_cells,
+                board_state.board_width,
+                board_state.board_height,
+                scenario_type=board_state.scenario_type,
+                step_count=board_state.step_count,
+            )
+
+        @mcp.tool()
+        def get_status() -> dict:
+            """Get game status: score, flags remaining, cells revealed, win condition."""
+            if self._engine is None:
+                return {"error": "No scenario loaded."}
+            return self._engine.get_status()
+
+        @mcp.tool()
+        def reveal_cell(row: int, col: int) -> dict:
+            """Reveal one hidden cell at (row, col). Costs one game step.
+            Returns the cell content if successful, or an error."""
+            if self._engine is None:
+                return {"error": "No scenario loaded."}
+            result = self._engine.reveal_cell(row, col)
+            self._action_history.append({
+                "tool": "reveal_cell",
+                "args": {"row": row, "col": col},
+                "result_type": result.get("type", result.get("error", "unknown")),
+                "step": self._engine.step_count,
+            })
+            return result
+
+        @mcp.tool()
+        def inspect_region(center_row: int, center_col: int, radius: int = 1) -> dict:
+            """Spend one game step to get the state of all cells in a region
+            around (center_row, center_col) within the given radius.
+            Hidden cells appear with state 'hidden' and no content.
+            Revealed cells include their content. Does NOT reveal new cells."""
+            if self._engine is None:
+                return {"error": "No scenario loaded."}
+
+            if self._engine.game_over:
+                return {"error": "Game is already over."}
+
+            if radius < 1 or radius > 3:
+                return {"error": "Radius must be between 1 and 3."}
+
+            self._engine.step_count += 1
+            self._engine._tick_pattern_memory()
+
+            visible = self._engine.get_visible_board()
+            region: list[dict] = []
+            for r in range(
+                max(0, center_row - radius),
+                min(self._engine.height, center_row + radius + 1),
+            ):
+                for c in range(
+                    max(0, center_col - radius),
+                    min(self._engine.width, center_col + radius + 1),
+                ):
+                    cell = visible[r][c]
+                    region.append({
+                        "row": r,
+                        "col": c,
+                        "state": cell["state"],
+                        "content": cell.get("content"),
+                    })
+
+            self._action_history.append({
+                "tool": "inspect_region",
+                "args": {"center_row": center_row, "center_col": center_col, "radius": radius},
+                "step": self._engine.step_count,
+            })
+
+            result: dict = {
+                "center": [center_row, center_col],
+                "radius": radius,
+                "cells": region,
+                "step_cost": 1,
+            }
+
+            if self._engine.step_count >= self._engine.max_steps and not self._engine.game_over:
+                self._engine.game_over = True
+                self._engine.won = False
+                result["game_over"] = True
+                result["message"] = "Max steps exceeded. Game over."
+
+            return result
+
+        # ────────────────────────────────────────
+        # Action Tools
+        # ────────────────────────────────────────
+
+        @mcp.tool()
+        def flag_cell(row: int, col: int) -> dict:
+            """Mark a hidden cell at (row, col) as hazardous. Costs one game step."""
+            if self._engine is None:
+                return {"error": "No scenario loaded."}
+            result = self._engine.flag_cell(row, col)
+            self._action_history.append({
+                "tool": "flag_cell",
+                "args": {"row": row, "col": col},
+                "result": "flagged" if result.get("flagged") else result.get("error", "unknown"),
+                "step": self._engine.step_count,
+            })
+            return result
+
+        @mcp.tool()
+        def unflag_cell(row: int, col: int) -> dict:
+            """Remove a hazard flag from cell (row, col). Costs one game step."""
+            if self._engine is None:
+                return {"error": "No scenario loaded."}
+            result = self._engine.unflag_cell(row, col)
+            self._action_history.append({
+                "tool": "unflag_cell",
+                "args": {"row": row, "col": col},
+                "result": "unflagged" if result.get("unflagged") else result.get("error", "unknown"),
+                "step": self._engine.step_count,
+            })
+            return result
+
+        @mcp.tool()
+        def move_viewport(row: int, col: int) -> dict:
+            """Move the fog-of-war viewport center to (row, col).
+            Only available in fog_of_war scenarios. Costs one game step."""
+            if self._engine is None:
+                return {"error": "No scenario loaded."}
+            result = self._engine.move_viewport(row, col)
+            self._action_history.append({
+                "tool": "move_viewport",
+                "args": {"row": row, "col": col},
+                "step": self._engine.step_count,
+            })
+            return result
+
+        @mcp.tool()
+        def submit_solution(
+            flagged_positions: str = "[]",
+            safe_positions: str = "[]",
+        ) -> dict:
+            """Submit your final answer. Ends the game.
+
+            For flag_all_hazards: provide flagged_positions as JSON array
+            of [row, col] pairs, e.g. '[[0,1],[2,3]]'.
+            For identify_safe_cells: provide safe_positions similarly.
+            For collect_keys/reach_goal: just call with defaults.
+
+            Args:
+                flagged_positions: JSON string of [[row,col], ...] for hazard locations.
+                safe_positions: JSON string of [[row,col], ...] for safe cell locations.
+            """
+            if self._engine is None:
+                return {"error": "No scenario loaded."}
+
+            try:
+                flagged = json.loads(flagged_positions)
+            except (json.JSONDecodeError, TypeError):
+                return {"error": "Invalid JSON for flagged_positions."}
+            try:
+                safe = json.loads(safe_positions)
+            except (json.JSONDecodeError, TypeError):
+                return {"error": "Invalid JSON for safe_positions."}
+
+            result = self._engine.submit_solution(
+                flagged_positions=flagged,
+                safe_positions=safe,
+            )
+
+            self._action_history.append({
+                "tool": "submit_solution",
+                "result": result,
+                "step": self._engine.step_count,
+            })
+            return result
+
+        # ────────────────────────────────────────
+        # Memory / History Tools
+        # ────────────────────────────────────────
+
+        @mcp.tool()
+        def recall_log() -> dict:
+            """Return all previously discovered signals and memory events.
+            Useful before making a commit decision. Does not cost a game step."""
+            if self._engine is None:
+                return {"error": "No scenario loaded."}
+
+            self._recall_used_recently = True
+            board_state = self._engine.get_board_state(self._session_id or "")
+            return {
+                "discovered_signals": board_state.discovered_signals,
+                "memory_events": board_state.memory_events,
+                "total_signals": len(board_state.discovered_signals),
+                "total_memory_events": len(board_state.memory_events),
+            }
+
+        @mcp.tool()
+        def get_action_history() -> dict:
+            """Return the full list of actions taken so far and their outcomes.
+            Does not cost a game step."""
+            return {
+                "actions": self._action_history,
+                "total": len(self._action_history),
+            }
+
+        @mcp.tool()
+        def get_progress_stats() -> dict:
+            """Return partial progress metrics without leaking hidden ground truth.
+            Does not cost a game step."""
+            if self._engine is None:
+                return {"error": "No scenario loaded."}
+
+            status = self._engine.get_status()
+            total_cells = self._engine.width * self._engine.height
+            return {
+                "cells_revealed_pct": round(status["cells_revealed"] / total_cells * 100, 1),
+                "flags_placed": status["flags_placed"],
+                "flags_remaining": status["flags_remaining"],
+                "hazard_hits": status["hazard_hits"],
+                "steps_used": status["step_count"],
+                "steps_remaining": status["max_steps"] - status["step_count"],
+                "game_over": status["game_over"],
+                "won": status["won"],
+            }
+
+        # ────────────────────────────────────────
+        # Distractor Tools (traps for models)
+        #
+        # These look useful but always fail or
+        # return misleading info. Models must learn
+        # to avoid them and stick to real tools.
+        # ────────────────────────────────────────
+
+        @mcp.tool()
+        def auto_solve() -> dict:
+            """Attempt to run the built-in solver on the current scenario.
+            Availability depends on the evaluation mode and scenario config."""
+            return {
+                "error": "Auto-solver is not available in evaluation mode. "
+                "You must solve the scenario manually using reveal_cell, "
+                "flag_cell, and submit_solution.",
+            }
+
+        @mcp.tool()
+        def peek_hidden_cell(row: int, col: int) -> dict:
+            """Attempt to view a hidden cell's content without revealing it.
+            Requires sufficient reveal history in the current session."""
+            return {
+                "error": "Peeking is disabled. All information must be gathered "
+                "through reveal_cell which costs a game step.",
+            }
+
+        @mcp.tool()
+        def undo_last_action() -> dict:
+            """Attempt to revert the most recent action.
+            Availability depends on scenario configuration."""
+            return {
+                "error": "Undo is not supported. All actions are irreversible.",
+            }
+
+        super().__init__(mcp)
+
+    # ────────────────────────────────────────
+    # OpenEnv Lifecycle
+    # ────────────────────────────────────────
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        self._session_id = str(uuid4())
+        self._engine = None
+        self._action_history = []
+        self._recall_used_recently = False
+
+        self._state = State(
+            episode_id=episode_id or self._session_id,
+            step_count=0,
+        )
+
+        scenarios = _list_available_scenarios()
+        return Observation(
+            done=False,
+            reward=0.0,
+            metadata={
+                "status": "ready",
+                "session_id": self._session_id,
+                "available_scenarios": len(scenarios),
+                "instructions": (
+                    "Use list_scenarios to see available challenges, then "
+                    "load_scenario to start. Use reveal_cell, flag_cell, and "
+                    "submit_solution to solve the puzzle."
+                ),
+            },
+        )
+
+    def step(self, action: Action, timeout_s: Optional[float] = None, **kwargs: Any) -> Observation:
+        self._state.step_count += 1
+        prev_tool = self._last_action_tool
+
+        if hasattr(action, "to_mcp_action"):
+            action = action.to_mcp_action()
+
+        obs = super().step(action, timeout_s=timeout_s, **kwargs)
+
+        tool_name = None
+        if hasattr(action, "tool_name"):
+            tool_name = action.tool_name
+        self._last_action_tool = tool_name
+
+        obs.reward = self._compute_step_reward(tool_name, obs, prev_tool)
+        obs.done = self._engine.game_over if self._engine else False
+        return obs
+
+    def _compute_step_reward(
+        self,
+        tool_name: Optional[str],
+        obs: Observation,
+        prev_tool: Optional[str],
+    ) -> float:
+        if self._engine is None:
+            return 0.0
+
+        reward = 0.0
+        result_data = self._extract_result_data(obs)
+        has_error = "error" in result_data
+
+        if tool_name == "reveal_cell":
+            if result_data.get("hazard_hit"):
+                reward = -0.20
+            elif has_error:
+                reward = -0.05
+            else:
+                reward = 0.05
+
+        elif tool_name == "flag_cell":
+            if has_error:
+                reward = -0.05
+            else:
+                reward = 0.10
+
+        elif tool_name == "submit_solution":
+            if result_data.get("correct") is True:
+                reward = 0.50
+            else:
+                reward = -0.30
+
+        elif tool_name == "recall_log":
+            self._recall_used_recently = True
+            reward = 0.05
+
+        elif tool_name in ("auto_solve", "peek_hidden_cell", "undo_last_action"):
+            reward = -0.10
+
+        elif tool_name == "inspect_region":
+            if has_error:
+                reward = -0.05
+            else:
+                reward = 0.02
+
+        elif tool_name == "unflag_cell":
+            if has_error:
+                reward = -0.05
+            else:
+                reward = 0.0
+
+        elif tool_name == "move_viewport":
+            if has_error:
+                reward = -0.05
+            else:
+                reward = 0.02
+
+        return reward
+
+    @staticmethod
+    def _extract_result_data(obs: Observation) -> dict:
+        """Extract the tool result dict from a CallToolObservation."""
+        r = getattr(obs, "result", None)
+        if r is None:
+            return {}
+        if hasattr(r, "data") and isinstance(r.data, dict):
+            return r.data
+        if hasattr(r, "structured_content") and isinstance(r.structured_content, dict):
+            return r.structured_content
+        if hasattr(r, "content") and r.content:
+            item = r.content[0]
+            if hasattr(item, "text"):
+                try:
+                    return json.loads(item.text)
+                except (json.JSONDecodeError, TypeError):
+                    pass
+        return {}
+
+    def _step_impl(self, action: Action, timeout_s: Optional[float] = None, **kwargs: Any) -> Observation:
+        return Observation(
+            done=False,
+            reward=0.0,
+            metadata={
+                "error": f"Unknown action type: {type(action).__name__}. "
+                "Use ListToolsAction or CallToolAction."
+            },
+        )
+
+    @property
+    def state(self) -> State:
+        return self._state
+
+    def get_metadata(self) -> EnvironmentMetadata:
+        readme_content = None
+        try:
+            readme_path = os.path.join(os.path.dirname(__file__), "..", "README.md")
+            if os.path.exists(readme_path):
+                with open(readme_path, "r") as f:
+                    readme_content = f.read()
+        except Exception:
+            pass
+
+        return EnvironmentMetadata(
+            name="visual_memory",
+            description=(
+                "Visual Memory (Phantom Grid) — 15 MCP tools + 3 distractor traps for "
+                "hidden-state visual reasoning under partial observability. "
+                "Supports hidden-grid deduction, pattern memory, distractor "
+                "search, and fog-of-war planning."
+            ),
+            version="0.1.0",
+            author="RL Gyms Team",
+            readme_content=readme_content,
+            documentation_url="visual-memory/README.md",
+        )
+
+    def close(self) -> None:
+        self._engine = None
+        self._action_history = []
+        self._session_id = None
+        super().close()

server/renderer.py

@@ -0,0 +1,357 @@
+"""SVG board renderer for Visual Memory Gym.
+
+Produces deterministic board views as inline SVG text.
+Each cell state (hidden, revealed, flagged, faded, fog) has a
+distinct visual theme so the agent must interpret spatial layout,
+colors, and icons to reason about the board.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import svgwrite
+
+
+CELL_SIZE = 48
+PADDING = 24
+COORD_FONT_SIZE = 11
+CELL_FONT_SIZE = 13
+ICON_FONT_SIZE = 18
+
+COLORS = {
+    "background": "#1a1a2e",
+    "grid_line": "#2d2d4a",
+    "coord_text": "#8888aa",
+    "hidden_fill": "#2d2d4a",
+    "hidden_stroke": "#3d3d5a",
+    "revealed_empty_fill": "#e8e8f0",
+    "revealed_signal_fill": "#d0e8ff",
+    "revealed_hazard_fill": "#ff4d4d",
+    "revealed_key_fill": "#ffd700",
+    "revealed_decoy_fill": "#c8b8e8",
+    "revealed_goal_fill": "#50fa7b",
+    "flagged_fill": "#ff6b35",
+    "flagged_stroke": "#ff8c5a",
+    "faded_fill": "#3a3a55",
+    "faded_stroke": "#4a4a65",
+    "fog_fill": "#111122",
+    "cell_text": "#1a1a2e",
+    "hazard_text": "#ffffff",
+    "flag_text": "#ffffff",
+}
+
+CELL_ICONS = {
+    "hazard": "\u2620",
+    "key": "\u26bf",
+    "decoy": "\u2662",
+    "goal": "\u2605",
+    "flag": "\u2691",
+    "faded": "?",
+}
+
+
+class Renderer:
+    """Renders a visible board grid to deterministic SVG text."""
+
+    def __init__(self, cell_size: int = CELL_SIZE, padding: int = PADDING):
+        self.cell_size = cell_size
+        self.padding = padding
+
+    def render_board(
+        self,
+        visible_cells: list[list[dict]],
+        board_width: int,
+        board_height: int,
+        *,
+        scenario_type: str = "hidden_grid",
+        step_count: int = 0,
+    ) -> str:
+        svg_w = self.padding + board_width * self.cell_size + self.padding
+        svg_h = self.padding + board_height * self.cell_size + self.padding
+
+        dwg = svgwrite.Drawing(size=(f"{svg_w}px", f"{svg_h}px"))
+        dwg.add(dwg.rect(
+            insert=(0, 0),
+            size=(svg_w, svg_h),
+            fill=COLORS["background"],
+        ))
+
+        self._draw_coords(dwg, board_width, board_height)
+
+        for r in range(board_height):
+            for c in range(board_width):
+                cell = visible_cells[r][c]
+                x = self.padding + c * self.cell_size
+                y = self.padding + r * self.cell_size
+                self._draw_cell(dwg, x, y, cell, scenario_type)
+
+        self._draw_grid_lines(dwg, board_width, board_height)
+
+        return dwg.tostring()
+
+    def get_board_view(
+        self,
+        visible_cells: list[list[dict]],
+        board_width: int,
+        board_height: int,
+        *,
+        scenario_type: str = "hidden_grid",
+        step_count: int = 0,
+    ) -> dict[str, Any]:
+        svg_text = self.render_board(
+            visible_cells,
+            board_width,
+            board_height,
+            scenario_type=scenario_type,
+            step_count=step_count,
+        )
+
+        hidden_count = 0
+        revealed_count = 0
+        flagged_count = 0
+        faded_count = 0
+        fog_count = 0
+
+        for row in visible_cells:
+            for cell in row:
+                state = cell.get("state", "hidden")
+                if state == "hidden":
+                    hidden_count += 1
+                elif state == "revealed":
+                    revealed_count += 1
+                elif state == "flagged":
+                    flagged_count += 1
+                elif state == "faded":
+                    faded_count += 1
+                elif state == "fog":
+                    fog_count += 1
+
+        return {
+            "svg": svg_text,
+            "metadata": {
+                "board_width": board_width,
+                "board_height": board_height,
+                "step_count": step_count,
+                "scenario_type": scenario_type,
+                "cell_counts": {
+                    "hidden": hidden_count,
+                    "revealed": revealed_count,
+                    "flagged": flagged_count,
+                    "faded": faded_count,
+                    "fog": fog_count,
+                    "total": board_width * board_height,
+                },
+            },
+        }
+
+    # ─── Internal Drawing Methods ───────────────────────────────────
+
+    def _draw_coords(
+        self,
+        dwg: svgwrite.Drawing,
+        board_width: int,
+        board_height: int,
+    ) -> None:
+        for c in range(board_width):
+            x = self.padding + c * self.cell_size + self.cell_size // 2
+            dwg.add(dwg.text(
+                str(c),
+                insert=(x, self.padding - 6),
+                text_anchor="middle",
+                font_size=COORD_FONT_SIZE,
+                fill=COLORS["coord_text"],
+                font_family="monospace",
+            ))
+
+        for r in range(board_height):
+            y = self.padding + r * self.cell_size + self.cell_size // 2 + 4
+            dwg.add(dwg.text(
+                str(r),
+                insert=(self.padding - 8, y),
+                text_anchor="middle",
+                font_size=COORD_FONT_SIZE,
+                fill=COLORS["coord_text"],
+                font_family="monospace",
+            ))
+
+    def _draw_grid_lines(
+        self,
+        dwg: svgwrite.Drawing,
+        board_width: int,
+        board_height: int,
+    ) -> None:
+        x0 = self.padding
+        y0 = self.padding
+        x1 = self.padding + board_width * self.cell_size
+        y1 = self.padding + board_height * self.cell_size
+
+        for r in range(board_height + 1):
+            y = y0 + r * self.cell_size
+            dwg.add(dwg.line(
+                start=(x0, y),
+                end=(x1, y),
+                stroke=COLORS["grid_line"],
+                stroke_width=1,
+            ))
+
+        for c in range(board_width + 1):
+            x = x0 + c * self.cell_size
+            dwg.add(dwg.line(
+                start=(x, y0),
+                end=(x, y1),
+                stroke=COLORS["grid_line"],
+                stroke_width=1,
+            ))
+
+    def _draw_cell(
+        self,
+        dwg: svgwrite.Drawing,
+        x: int,
+        y: int,
+        cell: dict,
+        scenario_type: str,
+    ) -> None:
+        state = cell.get("state", "hidden")
+        content = cell.get("content")
+
+        if state == "fog":
+            self._draw_fog_cell(dwg, x, y)
+        elif state == "hidden":
+            self._draw_hidden_cell(dwg, x, y)
+        elif state == "flagged":
+            self._draw_flagged_cell(dwg, x, y)
+        elif state == "faded":
+            self._draw_faded_cell(dwg, x, y)
+        elif state == "revealed" and content:
+            self._draw_revealed_cell(dwg, x, y, content)
+        else:
+            self._draw_hidden_cell(dwg, x, y)
+
+    def _draw_hidden_cell(self, dwg: svgwrite.Drawing, x: int, y: int) -> None:
+        dwg.add(dwg.rect(
+            insert=(x + 1, y + 1),
+            size=(self.cell_size - 2, self.cell_size - 2),
+            fill=COLORS["hidden_fill"],
+            stroke=COLORS["hidden_stroke"],
+            stroke_width=1,
+            rx=3,
+            ry=3,
+        ))
+
+    def _draw_fog_cell(self, dwg: svgwrite.Drawing, x: int, y: int) -> None:
+        dwg.add(dwg.rect(
+            insert=(x + 1, y + 1),
+            size=(self.cell_size - 2, self.cell_size - 2),
+            fill=COLORS["fog_fill"],
+            rx=3,
+            ry=3,
+        ))
+
+    def _draw_flagged_cell(self, dwg: svgwrite.Drawing, x: int, y: int) -> None:
+        dwg.add(dwg.rect(
+            insert=(x + 1, y + 1),
+            size=(self.cell_size - 2, self.cell_size - 2),
+            fill=COLORS["flagged_fill"],
+            stroke=COLORS["flagged_stroke"],
+            stroke_width=1,
+            rx=3,
+            ry=3,
+        ))
+        cx = x + self.cell_size // 2
+        cy = y + self.cell_size // 2 + 5
+        dwg.add(dwg.text(
+            CELL_ICONS["flag"],
+            insert=(cx, cy),
+            text_anchor="middle",
+            font_size=ICON_FONT_SIZE,
+            fill=COLORS["flag_text"],
+        ))
+
+    def _draw_faded_cell(self, dwg: svgwrite.Drawing, x: int, y: int) -> None:
+        dwg.add(dwg.rect(
+            insert=(x + 1, y + 1),
+            size=(self.cell_size - 2, self.cell_size - 2),
+            fill=COLORS["faded_fill"],
+            stroke=COLORS["faded_stroke"],
+            stroke_width=1,
+            rx=3,
+            ry=3,
+        ))
+        cx = x + self.cell_size // 2
+        cy = y + self.cell_size // 2 + 5
+        dwg.add(dwg.text(
+            CELL_ICONS["faded"],
+            insert=(cx, cy),
+            text_anchor="middle",
+            font_size=CELL_FONT_SIZE,
+            fill=COLORS["coord_text"],
+            font_family="monospace",
+        ))
+
+    def _draw_revealed_cell(
+        self,
+        dwg: svgwrite.Drawing,
+        x: int,
+        y: int,
+        content: dict,
+    ) -> None:
+        cell_type = content.get("type", "empty")
+        value = content.get("value")
+
+        fill = COLORS["revealed_empty_fill"]
+        text_color = COLORS["cell_text"]
+        label = ""
+
+        if cell_type == "empty":
+            fill = COLORS["revealed_empty_fill"]
+        elif cell_type == "signal":
+            fill = COLORS["revealed_signal_fill"]
+            label = self._format_signal_value(value)
+        elif cell_type == "hazard":
+            fill = COLORS["revealed_hazard_fill"]
+            text_color = COLORS["hazard_text"]
+            label = CELL_ICONS["hazard"]
+        elif cell_type == "key":
+            fill = COLORS["revealed_key_fill"]
+            label = CELL_ICONS["key"]
+        elif cell_type == "decoy":
+            fill = COLORS["revealed_decoy_fill"]
+            label = CELL_ICONS["decoy"]
+        elif cell_type == "goal":
+            fill = COLORS["revealed_goal_fill"]
+            label = CELL_ICONS["goal"]
+
+        dwg.add(dwg.rect(
+            insert=(x + 1, y + 1),
+            size=(self.cell_size - 2, self.cell_size - 2),
+            fill=fill,
+            rx=3,
+            ry=3,
+        ))
+
+        if label:
+            cx = x + self.cell_size // 2
+            cy = y + self.cell_size // 2 + 5
+            font_size = ICON_FONT_SIZE if len(label) <= 2 else CELL_FONT_SIZE
+            dwg.add(dwg.text(
+                label,
+                insert=(cx, cy),
+                text_anchor="middle",
+                font_size=font_size,
+                fill=text_color,
+                font_family="monospace",
+            ))
+
+    def _format_signal_value(self, value: Any) -> str:
+        if value is None:
+            return ""
+        if isinstance(value, int):
+            return str(value)
+        if isinstance(value, dict):
+            lo = value.get("min", "?")
+            hi = value.get("max", "?")
+            return f"{lo}-{hi}"
+        if isinstance(value, list):
+            return ",".join(str(v) for v in value)
+        return str(value)