Enhance episode state isolation and realistic grader hints for max scoring

graders/grader.py

@@ -28,13 +28,13 @@ class APIGrader:
         if status == expected_status:
             return "Correct status code. Verify response schema matches expected."
         hints = {
-            401: "Authentication failed. Check Authorization header format and token value.",
-            403: "Forbidden. Token valid but lacks permission.",
-            404: "Endpoint not found. Check the URL path.",
-            405: "Wrong HTTP method. Check if endpoint needs GET POST PUT or DELETE.",
-            415: "Wrong Content-Type. Send application/json.",
-            422: "Body validation failed. Check field names types and required fields.",
-            429: "Rate limited. Add header X-Retry-After: 2 on next request.",
-            500: "Server error. Your payload caused an exception.",
+            401: "Authentication failed. The server could not verify your identity. Check your tokens or auth headers in the response.",
+            403: "Forbidden. You authenticated successfully but lack permission for this explicit resource.",
+            404: "Endpoint not found. Double-check the URL path and HTTP method.",
+            405: "Method Not Allowed. The HTTP method used is not supported by this endpoint.",
+            415: "Unsupported Media Type. The server expects a different Content-Type.",
+            422: "Unprocessable Entity. The request body or query parameters failed validation. Check property names and data types.",
+            429: "Too Many Requests. You have been rate limited. Look for a retry header.",
+            500: "Internal Server Error. Your payload caused an unhandled exception.",
         }
-        return hints.get(status, f"Got {status} expected {expected_status}. Re-read task description carefully.")
+        return hints.get(status, f"Received status {status}. Read the response body/headers for clues and retry.")

server/api_debug_environment.py

@@ -21,6 +21,13 @@ class APIDebugEnvironment(Environment):
         self._current_task = None
 
     def reset(self, task_id: str = "easy", **kwargs) -> APIObservation:
+        # Reset the mock API state to ensure strict episode isolation
+        try:
+            with httpx.Client(base_url=MOCK_BASE, timeout=2.0) as http:
+                http.post("/mock_api/_admin/reset")
+        except Exception:
+            pass
+
         if task_id not in TASK_REGISTRY:
             task_id = "easy"
         self._current_task = random.choice(TASK_REGISTRY[task_id])

server/mock_api.py

@@ -14,6 +14,12 @@ LOG_PAGES = {
     "cur_def": {"items": list(range(20, 25)), "next_cursor": None, "has_more": False},
 }
 
+@router.post("/_admin/reset")
+async def admin_reset():
+    _issued_tokens.clear()
+    _request_log.clear()
+    return {"status": "reset_successful"}
+
 
 class TokenRequest(BaseModel):
     client_id: str