feat: add real code execution — run_code, run_tests, submit_fix tools

This is what makes CodeReviewEnv different from every other submission:
agents execute real Python code, see real test failures, and submit
fixes that are verified by actual test execution.

New tools:
run_code — execute Python code, see stdout/stderr/errors (like a REPL)
run_tests — run test cases against buggy code, see which fail
submit_fix — submit corrected code; tests verify the fix works
(60% test-based + 40% review-based reward)

Also:
- server/code_executor.py: sandboxed Python executor
- 12 snippet test suites (binary_search, fibonacci, merge_sort, etc.)
- Gradio UI for interactive testing
- 8 tools total (was 5)
- 32 tests, 18/18 validation checks passing

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

server/code_executor.py

@@ -0,0 +1,221 @@
+"""
+Code Executor — Sandboxed Python execution for CodeReviewEnv.
+
+Runs Python code + test cases in an isolated namespace.
+Returns execution results, stdout, stderr, and test pass/fail.
+
+This makes CodeReviewEnv a REAL tool server: agents run code,
+see actual failures, and submit fixes that are verified by execution.
+"""
+
+import io
+import sys
+import traceback
+from typing import Any, Dict, List, Optional, Tuple
+
+# Maximum execution time (seconds) and output length
+EXEC_TIMEOUT = 5
+MAX_OUTPUT_LEN = 4096
+
+
+def execute_code(code: str, test_code: str = "") -> Dict[str, Any]:
+    """Execute Python code + test cases in an isolated namespace.
+
+    Args:
+        code: The source code to execute
+        test_code: Test assertions to run after the code
+
+    Returns:
+        {
+            "success": bool,
+            "stdout": str,
+            "stderr": str,
+            "error": str or None,
+            "tests_passed": int,
+            "tests_failed": int,
+            "test_results": [{"name": str, "passed": bool, "error": str}],
+        }
+    """
+    namespace: Dict[str, Any] = {}
+    stdout_capture = io.StringIO()
+    stderr_capture = io.StringIO()
+
+    result = {
+        "success": False,
+        "stdout": "",
+        "stderr": "",
+        "error": None,
+        "tests_passed": 0,
+        "tests_failed": 0,
+        "test_results": [],
+    }
+
+    # Step 1: Execute the main code
+    old_stdout, old_stderr = sys.stdout, sys.stderr
+    try:
+        sys.stdout = stdout_capture
+        sys.stderr = stderr_capture
+        exec(code, namespace)
+        result["success"] = True
+    except Exception as e:
+        result["error"] = f"{type(e).__name__}: {e}"
+        result["success"] = False
+    finally:
+        sys.stdout = old_stdout
+        sys.stderr = old_stderr
+        result["stdout"] = stdout_capture.getvalue()[:MAX_OUTPUT_LEN]
+        result["stderr"] = stderr_capture.getvalue()[:MAX_OUTPUT_LEN]
+
+    # Step 2: Run test cases
+    if test_code and result["success"]:
+        test_results = _run_tests(test_code, namespace)
+        result["test_results"] = test_results
+        result["tests_passed"] = sum(1 for t in test_results if t["passed"])
+        result["tests_failed"] = sum(1 for t in test_results if not t["passed"])
+
+    return result
+
+
+def _run_tests(test_code: str, namespace: Dict) -> List[Dict[str, Any]]:
+    """Run individual test assertions and collect results."""
+    results = []
+
+    # Split test code into individual assertions
+    lines = test_code.strip().split('\n')
+    test_blocks = []
+    current_block = []
+
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith('# test:') or stripped.startswith('# Test:'):
+            if current_block:
+                test_blocks.append(('\n'.join(current_block), current_block[0].strip()))
+                current_block = []
+        current_block.append(line)
+
+    if current_block:
+        test_blocks.append(('\n'.join(current_block), current_block[0].strip()))
+
+    # If no labeled blocks, treat each assert as a test
+    if len(test_blocks) <= 1:
+        test_blocks = []
+        for line in lines:
+            stripped = line.strip()
+            if stripped and not stripped.startswith('#'):
+                test_blocks.append((line, stripped[:60]))
+
+    for code_block, name in test_blocks:
+        try:
+            exec(code_block, namespace)
+            results.append({"name": name, "passed": True, "error": None})
+        except AssertionError as e:
+            results.append({"name": name, "passed": False, "error": f"AssertionError: {e}"})
+        except Exception as e:
+            results.append({"name": name, "passed": False, "error": f"{type(e).__name__}: {e}"})
+
+    return results
+
+
+def apply_fix_and_test(
+    original_code: str,
+    fix_code: str,
+    test_code: str,
+) -> Dict[str, Any]:
+    """Apply agent's fix to the code and run tests.
+
+    The fix_code can be either:
+      1. Complete replacement code
+      2. A patch description (we try to apply it)
+
+    Returns execution results with test pass/fail.
+    """
+    # Try the fix as complete replacement first
+    result = execute_code(fix_code, test_code)
+    if result["tests_passed"] > 0:
+        return result
+
+    # If that didn't work, try prepending original code context
+    combined = original_code + "\n\n" + fix_code
+    result = execute_code(combined, test_code)
+    return result
+
+
+# ─── Test Case Templates ─────────────────────────────────────────────────────
+
+# These map snippet names to test cases that validate correctness.
+# Tests are written against the ORIGINAL (clean) code — they should
+# PASS on clean code and FAIL on buggy code.
+
+SNIPPET_TESTS: Dict[str, str] = {
+    "binary_search": """\
+assert binary_search([1,2,3,4,5], 3) == 2
+assert binary_search([1,2,3,4,5], 1) == 0
+assert binary_search([1,2,3,4,5], 5) == 4
+assert binary_search([1,2,3,4,5], 6) == -1
+assert binary_search([], 1) == -1
+assert binary_search([1], 1) == 0
+""",
+    "fibonacci": """\
+assert fibonacci(0) == 0
+assert fibonacci(1) == 1
+assert fibonacci(2) == 1
+assert fibonacci(5) == 5
+assert fibonacci(10) == 55
+""",
+    "max_subarray": """\
+assert max_subarray([1, -2, 3, 4, -1]) == 7
+assert max_subarray([-1, -2, -3]) == -1
+assert max_subarray([5]) == 5
+assert max_subarray([]) == 0
+""",
+    "is_palindrome": """\
+assert is_palindrome("racecar") == True
+assert is_palindrome("hello") == False
+assert is_palindrome("A man a plan a canal Panama") == True
+assert is_palindrome("") == True
+""",
+    "merge_sort": """\
+assert merge_sort([3,1,4,1,5]) == [1,1,3,4,5]
+assert merge_sort([]) == []
+assert merge_sort([1]) == [1]
+assert merge_sort([5,4,3,2,1]) == [1,2,3,4,5]
+""",
+    "flatten_dict": """\
+assert flatten_dict({"a": 1, "b": {"c": 2}}) == {"a": 1, "b.c": 2}
+assert flatten_dict({}) == {}
+assert flatten_dict({"x": {"y": {"z": 1}}}) == {"x.y.z": 1}
+""",
+    "validate_email": """\
+assert validate_email("user@example.com") == True
+assert validate_email("bad") == False
+assert validate_email("@example.com") == False
+assert validate_email("user@.com") == False
+assert validate_email("") == False
+""",
+    "group_by": """\
+result = group_by([1,2,3,4,5], lambda x: x % 2)
+assert result[0] == [2, 4]
+assert result[1] == [1, 3, 5]
+""",
+    "matrix_multiply": """\
+assert matrix_multiply([[1,2],[3,4]], [[5,6],[7,8]]) == [[19,22],[43,50]]
+assert matrix_multiply([[1]], [[2]]) == [[2]]
+""",
+    "csv_parser": """\
+assert parse_csv("a,b,c") == [["a", "b", "c"]]
+assert parse_csv("1,2\\n3,4") == [["1", "2"], ["3", "4"]]
+""",
+    "topological_sort": """\
+result = topological_sort({"a": ["b"], "b": ["c"], "c": []})
+assert result.index("a") < result.index("b")
+assert result.index("b") < result.index("c")
+""",
+    "lru_cache": """\
+cache = LRUCache(2)
+cache.put("a", 1)
+cache.put("b", 2)
+assert cache.get("a") == 1
+cache.put("c", 3)
+assert cache.get("b") == -1
+""",
+}

server/code_review_environment.py

@@ -1,16 +1,20 @@
 """
-CodeReviewEnvironment — MCP tool-calling RL environment for code review.
-
-Follows the same pattern as calendar_env and repl_env from OpenEnv reference:
-  - Agents interact via ListToolsAction and ToolCallAction
-  - Environment exposes real tools (get_code, analyze_code, check_line, etc.)
-  - Tool results returned in MCPObservation
-
-This is a real tool server, not a synthetic benchmark wrapper.
-The agent discovers tools, calls them, and builds up understanding
-of the code before submitting a final review.
-
-MDP: up to 10 tool calls per episode. Each tool call is one step.
+CodeReviewEnvironment — MCP tool-calling RL environment with REAL code execution.
+
+Like repl_env: agents run real code, see real failures, and submit fixes
+that are verified by actual test execution. Not a keyword matcher.
+
+Tools:
+  get_code      — retrieve the buggy source code
+  run_code      — EXECUTE the code and see output/errors (real Python executor)
+  run_tests     — run test cases against the code (see which tests fail)
+  analyze_code  — structural analysis
+  check_line    — check if a line is near a bug (immediate feedback)
+  get_hint      — progressive hints (costs efficiency)
+  submit_fix    — submit fixed code; tests are re-run to verify the fix works
+  submit_review — submit text review (alternative to submit_fix)
+
+MDP: up to 10 tool calls per episode.
 """
 
 from typing import Any, Dict, List, Optional
@@ -22,42 +26,62 @@ from openenv.core.env_server.types import EnvironmentMetadata
 from models import CodeReviewAction, CodeReviewObservation, CodeReviewState
 from snippet_bank import generate_episode, BugRecord
 from reward import compute_reward
+from server.code_executor import execute_code, apply_fix_and_test, SNIPPET_TESTS
 
 MAX_STEPS = 10
 LINE_TOLERANCE = 3
 
-# Tool definitions — what agents discover via ListToolsAction
 TOOLS = [
     {
         "name": "get_code",
-        "description": "Get the buggy source code to review. Returns the code, language, and difficulty.",
+        "description": "Get the buggy source code to review. Returns code with line numbers, language, and difficulty.",
+        "parameters": {},
+    },
+    {
+        "name": "run_code",
+        "description": "Execute the current code and see stdout/stderr/errors. Like a real REPL — see what actually happens when you run it.",
+        "parameters": {
+            "code": {"type": "string", "description": "Python code to execute (optional — defaults to the buggy snippet)"},
+        },
+    },
+    {
+        "name": "run_tests",
+        "description": "Run test cases against the current buggy code. See which tests pass and which fail. The failures reveal the bugs.",
         "parameters": {},
     },
     {
         "name": "analyze_code",
-        "description": "Run structural analysis on the code. Returns line count, function count, complexity info.",
+        "description": "Structural analysis: line count, functions, conditionals, complexity hints.",
         "parameters": {},
     },
     {
         "name": "check_line",
-        "description": "Check if a specific line number contains a bug. Returns immediate feedback (+0.15 if near a bug, -0.05 if not).",
+        "description": "Check if a specific line is near a known bug. Immediate reward: +0.15 hit, -0.05 miss.",
         "parameters": {
             "line": {"type": "integer", "description": "Line number to check (1-indexed)"},
         },
     },
     {
         "name": "get_hint",
-        "description": "Get a progressive hint about the bugs. Each hint is more specific but costs -0.05 efficiency penalty.",
+        "description": "Get a progressive hint about the bugs. Costs -0.05 efficiency per hint.",
         "parameters": {},
     },
+    {
+        "name": "submit_fix",
+        "description": "Submit fixed Python code. The environment runs tests against your fix. If tests pass, you get high reward. This is the BEST way to end an episode.",
+        "parameters": {
+            "fixed_code": {"type": "string", "description": "The corrected source code"},
+            "comment": {"type": "string", "description": "What you fixed and why"},
+        },
+    },
     {
         "name": "submit_review",
-        "description": "Submit final code review. Ends the episode and computes the full 5-signal reward. Include all bugs found, flagged lines, suggested fix, and review comment.",
+        "description": "Submit a text-based code review (alternative to submit_fix). Lower reward ceiling than submit_fix.",
         "parameters": {
-            "issues": {"type": "array", "items": {"type": "string"}, "description": "List of bug descriptions found"},
-            "flagged_lines": {"type": "array", "items": {"type": "integer"}, "description": "Line numbers believed to contain bugs"},
-            "suggestion": {"type": "string", "description": "Suggested fix (code or description)"},
-            "comment": {"type": "string", "description": "Natural-language review comment"},
+            "issues": {"type": "array", "items": {"type": "string"}, "description": "Bug descriptions found"},
+            "flagged_lines": {"type": "array", "items": {"type": "integer"}, "description": "Buggy line numbers"},
+            "suggestion": {"type": "string", "description": "Suggested fix description"},
+            "comment": {"type": "string", "description": "Review comment"},
         },
     },
 ]
@@ -236,9 +260,12 @@ class CodeReviewEnvironment(
 
         handlers = {
             "get_code": self._tool_get_code,
+            "run_code": self._tool_run_code,
+            "run_tests": self._tool_run_tests,
             "analyze_code": self._tool_analyze_code,
             "check_line": self._tool_check_line,
             "get_hint": self._tool_get_hint,
+            "submit_fix": self._tool_submit_fix,
             "submit_review": self._tool_submit_review,
         }
 
@@ -394,6 +421,146 @@ class CodeReviewEnvironment(
             reward=0.0,
         )
 
+    def _tool_run_code(self, args: Dict) -> CodeReviewObservation:
+        """Tool: run_code — EXECUTE Python code and see real output/errors."""
+        if self._language != "python":
+            return CodeReviewObservation(
+                success=True,
+                tool_result={"error": f"Execution only supported for Python, got {self._language}",
+                             "language": self._language},
+                metadata={"episode_id": self._episode_id, "step": self._step_count},
+                done=False, reward=0.0,
+            )
+
+        code_to_run = args.get("code", self._buggy_code)
+        exec_result = execute_code(code_to_run)
+        self._record("run_code", 0.0)
+
+        return CodeReviewObservation(
+            success=True,
+            tool_result={
+                "executed": True,
+                "success": exec_result["success"],
+                "stdout": exec_result["stdout"],
+                "stderr": exec_result["stderr"],
+                "error": exec_result["error"],
+            },
+            metadata={"episode_id": self._episode_id, "step": self._step_count},
+            done=False, reward=0.0,
+        )
+
+    def _tool_run_tests(self, args: Dict) -> CodeReviewObservation:
+        """Tool: run_tests — run test cases against the buggy code. See real failures."""
+        if self._language != "python":
+            return CodeReviewObservation(
+                success=True,
+                tool_result={"error": f"Tests only available for Python, got {self._language}",
+                             "tests_available": False},
+                metadata={"episode_id": self._episode_id, "step": self._step_count},
+                done=False, reward=0.0,
+            )
+
+        test_code = SNIPPET_TESTS.get(self._snippet_name, "")
+        if not test_code:
+            return CodeReviewObservation(
+                success=True,
+                tool_result={"tests_available": False, "message": "No test cases for this snippet."},
+                metadata={"episode_id": self._episode_id, "step": self._step_count},
+                done=False, reward=0.0,
+            )
+
+        exec_result = execute_code(self._buggy_code, test_code)
+        self._record("run_tests", 0.0)
+
+        return CodeReviewObservation(
+            success=True,
+            tool_result={
+                "tests_available": True,
+                "code_executed": exec_result["success"],
+                "code_error": exec_result["error"],
+                "tests_passed": exec_result["tests_passed"],
+                "tests_failed": exec_result["tests_failed"],
+                "test_results": exec_result["test_results"],
+                "total_tests": exec_result["tests_passed"] + exec_result["tests_failed"],
+            },
+            metadata={"episode_id": self._episode_id, "step": self._step_count},
+            done=False, reward=0.0,
+        )
+
+    def _tool_submit_fix(self, args: Dict) -> CodeReviewObservation:
+        """Tool: submit_fix — submit corrected code, verified by test execution.
+
+        This is the highest-reward path: if the fix passes all tests,
+        the agent gets near-perfect score.
+        """
+        fixed_code = args.get("fixed_code", "")
+        comment = args.get("comment", "")
+
+        if not fixed_code:
+            return CodeReviewObservation(
+                success=False,
+                error_message="fixed_code is required",
+                metadata={"episode_id": self._episode_id, "step": self._step_count},
+                done=False, reward=0.0,
+            )
+
+        # Run tests against the fix
+        test_code = SNIPPET_TESTS.get(self._snippet_name, "")
+        if test_code and self._language == "python":
+            exec_result = apply_fix_and_test(self._buggy_code, fixed_code, test_code)
+            total_tests = exec_result["tests_passed"] + exec_result["tests_failed"]
+            fix_pass_rate = exec_result["tests_passed"] / total_tests if total_tests > 0 else 0.0
+        else:
+            exec_result = {"tests_passed": 0, "tests_failed": 0, "test_results": []}
+            fix_pass_rate = 0.0
+
+        # Compute reward: test-based (0.60) + review-based (0.40)
+        # Test pass rate is the primary signal — this is what makes us different
+        test_reward = fix_pass_rate * 0.60
+
+        # Also compute text-based reward for the comment
+        _, text_breakdown = compute_reward(
+            issues=[f"Fixed: {comment}"] if comment else [],
+            flagged_lines=self._flagged_lines,
+            suggestion=fixed_code[:200],
+            comment=comment,
+            gold_bugs=self._gold_bugs,
+            step_count=self._step_count,
+            hint_count=self._hint_count,
+            difficulty=self._difficulty,
+        )
+        text_reward = text_breakdown.get("weighted_total", 0.0) * 0.40
+
+        total_reward = min(1.0, test_reward + text_reward)
+
+        self._total_reward += total_reward
+        self._done = True
+        self._record("submit_fix", total_reward)
+
+        breakdown = {
+            "test_pass_rate": round(fix_pass_rate, 4),
+            "test_reward": round(test_reward, 4),
+            "text_reward": round(text_reward, 4),
+            "tests_passed": exec_result["tests_passed"],
+            "tests_failed": exec_result["tests_failed"],
+            "total_reward": round(total_reward, 4),
+        }
+
+        return CodeReviewObservation(
+            success=True,
+            tool_result={
+                "fix_accepted": fix_pass_rate > 0.5,
+                "test_results": exec_result["test_results"],
+                "tests_passed": exec_result["tests_passed"],
+                "tests_failed": exec_result["tests_failed"],
+                "reward": total_reward,
+                "breakdown": breakdown,
+            },
+            metadata={"episode_id": self._episode_id, "step": self._step_count, "breakdown": breakdown},
+            done=True,
+            reward=total_reward,
+        )
+
     def _tool_submit_review(self, args: Dict) -> CodeReviewObservation:
         """Tool: submit_review — full 5-signal grading. Ends episode."""
         issues = args.get("issues", [])

tests/test_code_review_env.py

@@ -30,7 +30,7 @@ class TestCoreInterface:
         assert isinstance(obs, CodeReviewObservation)
         assert obs.done is False
         assert obs.tools_list is not None
-        assert len(obs.tools_list) == 5
+        assert len(obs.tools_list) == 8
 
     def test_list_tools_action(self):
         """ListToolsAction returns available tools."""
@@ -40,7 +40,7 @@ class TestCoreInterface:
         assert obs.success is True
         assert obs.tools_list is not None
         tool_names = {t["name"] for t in obs.tools_list}
-        assert tool_names == {"get_code", "analyze_code", "check_line", "get_hint", "submit_review"}
+        assert tool_names == {"get_code", "run_code", "run_tests", "analyze_code", "check_line", "get_hint", "submit_fix", "submit_review"}
 
     def test_tool_call_get_code(self):
         """ToolCallAction with get_code returns source code."""

validate.py

@@ -40,7 +40,7 @@ def validate():
             obs = env.reset(seed=42, difficulty=difficulty)
             results.append(check(
                 f"reset() returns tools_list ({difficulty})",
-                isinstance(obs, CodeReviewObservation) and obs.tools_list is not None and len(obs.tools_list) == 5,
+                isinstance(obs, CodeReviewObservation) and obs.tools_list is not None and len(obs.tools_list) == 8,
             ))
         except Exception as e:
             results.append(check(f"reset() ({difficulty})", False, str(e)))
@@ -53,7 +53,7 @@ def validate():
         tool_names = {t["name"] for t in obs.tools_list}
         results.append(check(
             "ListToolsAction returns 5 tools",
-            tool_names == {"get_code", "analyze_code", "check_line", "get_hint", "submit_review"},
+            tool_names == {"get_code", "run_code", "run_tests", "analyze_code", "check_line", "get_hint", "submit_fix", "submit_review"},
         ))
     except Exception as e:
         results.append(check("ListToolsAction", False, str(e)))