Add RLM-specific exception hierarchy to rlm_env.py (#892)

Replace generic vf.SandboxError raises with specific exception types:
- RLMWorkerError: worker not running, crashed, or failed to start
- RLMSessionError: session/sandbox/venv not initialized
- RLMSetupError: package install, setup hook, or command failures
- RLMCodeExecutionTimeout: now inherits from vf.ToolCallError instead
  of bare Exception, and propagates directly in abort path

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: snimu

verifiers/envs/experimental/rlm_env.py

@@ -146,14 +146,26 @@ def _merge_tool_lists(
     return deduped_all, deduped_map
 
 
-class RLMCodeExecutionTimeout(Exception):
+class RLMCodeExecutionTimeout(vf.ToolCallError):
     """Raised when code execution exceeds the configured timeout."""
 
 
-class RLMWorkerRecoveryError(vf.SandboxError):
+class RLMWorkerError(vf.SandboxError):
+    """Raised when the RLM worker is not running, crashes, or fails to start."""
+
+
+class RLMWorkerRecoveryError(RLMWorkerError):
     """Raised when the RLM worker cannot be restarted after a failure."""
 
 
+class RLMSessionError(vf.SandboxError):
+    """Raised when the RLM session, sandbox, or venv is not initialized."""
+
+
+class RLMSetupError(vf.SandboxError):
+    """Raised when RLM environment setup fails (package install, setup hook, etc.)."""
+
+
 @dataclass(frozen=True)
 class RLMWorkerPaths:
     base_dir: str
@@ -1566,9 +1578,9 @@ async def setup(self, state: State) -> None:
     async def execute(self, payload: dict[str, Any], state: State) -> RLMExecResult:
         session = self._get_session(state)
         if session.worker_process is None:
-            raise vf.SandboxError() from Exception("RLM worker process not running")
+            raise RLMWorkerError("RLM worker process not running")
         if session.worker_process.poll() is not None:
-            raise vf.SandboxError() from Exception("RLM worker process not running")
+            raise RLMWorkerError("RLM worker process not running")
 
         def _do_io() -> str:
             payload_json = json.dumps(payload)
@@ -1751,7 +1763,7 @@ def _get_or_create_session(self, state: State) -> LocalRLMReplSession:
     def _get_session(self, state: State) -> LocalRLMReplSession:
         rollout_id = state.get("rollout_id")
         if not rollout_id or rollout_id not in self._sessions:
-            raise vf.SandboxError() from Exception("Local session not initialized")
+            raise RLMSessionError("Local session not initialized")
         return self._sessions[rollout_id]
 
     async def _ensure_venv(self, session: LocalRLMReplSession) -> str | None:
@@ -1791,18 +1803,16 @@ def _run() -> subprocess.CompletedProcess:
 
         try:
             result = await asyncio.to_thread(_run)
-        except FileNotFoundError:
-            raise vf.SandboxError() from RuntimeError(
+        except FileNotFoundError as e:
+            raise RLMSetupError(
                 "uv not found on PATH; local execution requires uv installed"
-            )
-        except subprocess.TimeoutExpired:
-            raise vf.SandboxError() from RuntimeError(
-                f"uv command timed out after {timeout} seconds"
-            )
+            ) from e
+        except subprocess.TimeoutExpired as e:
+            raise RLMSetupError(f"uv command timed out after {timeout} seconds") from e
         if result.returncode != 0:
             stderr = (result.stderr or "").strip()
             stdout = (result.stdout or "").strip()
-            raise vf.SandboxError() from Exception(
+            raise RLMSetupError(
                 f"uv command failed: {' '.join(args)}\nstdout: {stdout}\nstderr: {stderr}"
             )
 
@@ -1827,7 +1837,7 @@ async def _write_local_files(
 
     async def _start_worker(self, state: State, session: LocalRLMReplSession) -> None:
         if self.env.repl_language == "python" and not session.venv_path:
-            raise vf.SandboxError() from Exception("Local venv not initialized")
+            raise RLMSessionError("Local venv not initialized")
         worker_script = _render_worker_script(
             session.paths, repl_language=self.env.repl_language
         )
@@ -1840,7 +1850,7 @@ async def _start_worker(self, state: State, session: LocalRLMReplSession) -> Non
         if self.env.repl_language == "python":
             venv_path = session.venv_path
             if venv_path is None:
-                raise vf.SandboxError() from Exception("Local venv not initialized")
+                raise RLMSessionError("Local venv not initialized")
             python_path = self._venv_python(venv_path)
         else:
             python_path = sys.executable
@@ -1870,11 +1880,11 @@ async def _wait_for_ready(self, session: LocalRLMReplSession) -> None:
                     ]
                 except Exception:
                     pass
-                raise vf.SandboxError() from Exception(
+                raise RLMWorkerError(
                     f"RLM worker exited before ready. Log tail:\n{log_tail}"
                 )
             if perf_counter() - start > max_wait_seconds:
-                raise vf.SandboxError() from Exception("RLM worker failed to start")
+                raise RLMWorkerError("RLM worker failed to start")
             await asyncio.sleep(0.1)
 
     def _stop_worker(self, session: LocalRLMReplSession) -> None:
@@ -1932,7 +1942,7 @@ async def prepare_filesystem(self, state: State) -> None:
             state["sandbox_state"]["ready"] = True
 
         if not session.sandbox_id:
-            raise vf.SandboxError() from Exception("Sandbox not initialized")
+            raise RLMSessionError("Sandbox not initialized")
 
         sandbox_fs_root = state.get("rlm_fs_root_remote")
         sandbox_control_dir = state.get("rlm_control_dir_remote")
@@ -1965,9 +1975,9 @@ async def prepare_filesystem(self, state: State) -> None:
     async def setup(self, state: State) -> None:
         session = self._get_session(state)
         if not session.sandbox_id:
-            raise vf.SandboxError() from Exception("Sandbox not initialized")
+            raise RLMSessionError("Sandbox not initialized")
         if not session.paths:
-            raise vf.SandboxError() from Exception("Sandbox paths not initialized")
+            raise RLMSessionError("Sandbox paths not initialized")
 
         await self._install_packages(session)
         await self._write_sandbox_files(session, state)
@@ -1976,7 +1986,7 @@ async def setup(self, state: State) -> None:
     async def execute(self, payload: dict[str, Any], state: State) -> RLMExecResult:
         session = self._get_session(state)
         if not session.sandbox_id or not session.paths:
-            raise vf.SandboxError() from Exception("Sandbox session not initialized")
+            raise RLMSessionError("Sandbox session not initialized")
 
         try:
             raw = await self._send_worker_request(session, payload)
@@ -2114,7 +2124,7 @@ def _get_or_create_session(self, state: State) -> SandboxRLMReplSession:
     def _get_session(self, state: State) -> SandboxRLMReplSession:
         rollout_id = state.get("rollout_id")
         if not rollout_id or rollout_id not in self._sessions:
-            raise vf.SandboxError() from Exception("Sandbox session not initialized")
+            raise RLMSessionError("Sandbox session not initialized")
         return self._sessions[rollout_id]
 
     def _build_sandbox_request(self, state: State) -> CreateSandboxRequest:
@@ -2123,12 +2133,12 @@ def _build_sandbox_request(self, state: State) -> CreateSandboxRequest:
     async def post_sandbox_setup(self, state: State) -> None:
         sandbox_id = state.get("sandbox_id")
         if not sandbox_id:
-            raise vf.SandboxError() from Exception("Sandbox not initialized")
+            raise RLMSessionError("Sandbox not initialized")
         try:
             # Allow environments to run repo/tool setup before the worker starts.
             await self.env.on_sandbox_ready(state, sandbox_id)
         except Exception as exc:
-            raise vf.SandboxError(f"Sandbox setup hook failed: {exc}") from exc
+            raise RLMSetupError(f"Sandbox setup hook failed: {exc}") from exc
 
     async def _execute_sandbox_command(
         self,
@@ -2153,7 +2163,7 @@ async def _execute_sandbox_command(
     async def _install_packages(self, session: SandboxRLMReplSession) -> None:
         sandbox_id = session.sandbox_id
         if not sandbox_id:
-            raise vf.SandboxError() from Exception("Sandbox not initialized")
+            raise RLMSessionError("Sandbox not initialized")
         packages = ["requests"]
         extras = [p.strip() for p in self.env.pip_install_packages.split() if p.strip()]
         packages.extend(extras)
@@ -2233,7 +2243,7 @@ async def _start_worker(self, session: SandboxRLMReplSession, state: State) -> N
         assert session.paths is not None
         sandbox_id = session.sandbox_id
         if not sandbox_id:
-            raise vf.SandboxError() from Exception("Sandbox not initialized")
+            raise RLMSessionError("Sandbox not initialized")
         env_vars = self.env._build_worker_env_vars(state)
 
         exports = " ".join(
@@ -2262,7 +2272,7 @@ async def _wait_for_ready(self, session: SandboxRLMReplSession) -> None:
         assert session.paths is not None
         sandbox_id = session.sandbox_id
         if not sandbox_id:
-            raise vf.SandboxError() from Exception("Sandbox not initialized")
+            raise RLMSessionError("Sandbox not initialized")
         cmd = (
             "bash -lc '"
             f"for i in $(seq 1 {self.env.max_startup_wait_seconds * 10}); do "
@@ -2278,14 +2288,14 @@ async def _wait_for_ready(self, session: SandboxRLMReplSession) -> None:
             )
         except CommandTimeoutError as exc:
             log_tail = await self._read_worker_log_tail(session)
-            raise vf.SandboxError(
+            raise RLMWorkerError(
                 "RLM worker failed to become ready before timeout."
                 + (f"\nLog tail:\n{log_tail}" if log_tail else "")
             ) from exc
         exit_code = getattr(result, "exit_code", 0)
         if exit_code != 0:
             log_tail = await self._read_worker_log_tail(session)
-            raise vf.SandboxError(
+            raise RLMWorkerError(
                 "RLM worker failed to become ready."
                 + (f"\nLog tail:\n{log_tail}" if log_tail else "")
             )
@@ -2321,9 +2331,7 @@ def _raise_on_command_error(self, result: Any, context: str) -> None:
             detail += f"\nstdout:\n{stdout}"
         if stderr:
             detail += f"\nstderr:\n{stderr}"
-        raise vf.SandboxError() from RuntimeError(
-            f"{context} failed with exit code {exit_code}.{detail}"
-        )
+        raise RLMSetupError(f"{context} failed with exit code {exit_code}.{detail}")
 
     async def _read_worker_log_tail(self, session: SandboxRLMReplSession) -> str:
         if not session.sandbox_id or not session.paths:
@@ -2346,7 +2354,7 @@ async def _send_worker_request(
         assert session.paths is not None
         sandbox_id = session.sandbox_id
         if not sandbox_id:
-            raise vf.SandboxError() from Exception("Sandbox not initialized")
+            raise RLMSessionError("Sandbox not initialized")
         payload_json = json.dumps(payload)
         payload_b64 = base64.b64encode(payload_json.encode("utf-8")).decode("utf-8")
         timeout_seconds = int(self.env.code_execution_timeout)
@@ -3953,8 +3961,7 @@ async def _execute_code(self, code: str, state: State) -> dict[str, Any]:
                 "Code execution timed out after %ss", self.code_execution_timeout
             )
             if self.abort_on_code_timeout:
-                # Abort rollout immediately on timeout
-                raise vf.SandboxError() from e
+                raise
             recovered = await self._recover_from_code_timeout(state)
             if not recovered:
                 raise RLMWorkerRecoveryError(