fix: #2962 normalize sandbox paths and add Windows CI

Author: seratch

.github/workflows/tests.yml

@@ -104,6 +104,33 @@ jobs:
         if: steps.changes.outputs.run != 'true'
         run: echo "Skipping tests for non-code changes."
 
+  tests-windows:
+    runs-on: windows-latest
+    env:
+      OPENAI_API_KEY: fake-for-tests
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - name: Detect code changes
+        id: changes
+        shell: bash
+        run: ./.github/scripts/detect-changes.sh code "${{ github.event.pull_request.base.sha || github.event.before }}" "${{ github.sha }}"
+      - name: Setup uv
+        if: steps.changes.outputs.run == 'true'
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57
+        with:
+          enable-cache: true
+          python-version: "3.14"
+      - name: Install dependencies
+        if: steps.changes.outputs.run == 'true'
+        run: uv sync --all-extras --all-packages --group dev
+      - name: Run tests
+        if: steps.changes.outputs.run == 'true'
+        run: uv run pytest
+      - name: Skip tests
+        if: steps.changes.outputs.run != 'true'
+        run: echo "Skipping tests for non-code changes."
+
   build-docs:
     runs-on: ubuntu-latest
     env:

src/agents/extensions/sandbox/modal/sandbox.py

@@ -418,7 +418,8 @@ async def _ensure_backend_started(self) -> None:
 
     async def _prepare_backend_workspace(self) -> None:
         # Ensure workspace root exists before the base workspace flow needs it.
-        await self.exec("mkdir", "-p", "--", str(Path(self.state.manifest.root)), shell=False)
+        root = self._workspace_path_policy().sandbox_root().as_posix()
+        await self.exec("mkdir", "-p", "--", root, shell=False)
 
     async def _after_start(self) -> None:
         self._running = True

src/agents/sandbox/session/base_sandbox_session.py

@@ -6,7 +6,7 @@
 import shutil
 import tempfile
 from collections.abc import Awaitable, Callable, Mapping, Sequence
-from pathlib import Path
+from pathlib import Path, PurePath, PurePosixPath
 from typing import Literal, TypeVar, cast
 
 from typing_extensions import Self
@@ -109,7 +109,7 @@ class BaseSandboxSession(abc.ABC):
     _runtime_persist_workspace_skip_relpaths: set[Path] | None = None
     _pre_stop_hooks: list[Callable[[], Awaitable[None]]] | None = None
     _pre_stop_hooks_ran: bool = False
-    _runtime_helpers_installed: set[Path] | None = None
+    _runtime_helpers_installed: set[PurePath] | None = None
     _runtime_helper_cache_key: object = _RUNTIME_HELPER_CACHE_KEY_UNSET
     _workspace_path_policy_cache: (
         tuple[str, tuple[tuple[str, bool], ...], WorkspacePathPolicy] | None
@@ -631,7 +631,7 @@ def _sync_runtime_helper_install_cache(self) -> None:
             self._runtime_helpers_installed = None
             self._runtime_helper_cache_key = current_key
 
-    async def _ensure_runtime_helper_installed(self, helper: RuntimeHelperScript) -> Path:
+    async def _ensure_runtime_helper_installed(self, helper: RuntimeHelperScript) -> PurePath:
         self._sync_runtime_helper_install_cache()
         installed = self._runtime_helpers_installed
         if installed is None:
@@ -701,20 +701,20 @@ async def _validate_remote_path_access(
         target, while still rejecting paths whose resolved remote target escapes all allowed roots.
         """
 
-        original_path = Path(path)
-        root = Path(self.state.manifest.root)
+        original_path = PurePosixPath(path.as_posix() if isinstance(path, PurePath) else path)
         path_policy = self._workspace_path_policy()
-        workspace_path = path_policy.normalize_path(original_path, for_write=for_write)
+        root = path_policy.sandbox_root()
+        workspace_path = path_policy.normalize_sandbox_path(original_path, for_write=for_write)
         helper_path = await self._ensure_runtime_helper_installed(RESOLVE_WORKSPACE_PATH_HELPER)
         extra_grant_args = tuple(
             arg
             for root, read_only in path_policy.extra_path_grant_rules()
-            for arg in (str(root), "1" if read_only else "0")
+            for arg in (root.as_posix(), "1" if read_only else "0")
         )
         command = (
             str(helper_path),
-            str(root),
-            str(workspace_path),
+            root.as_posix(),
+            workspace_path.as_posix(),
             "1" if for_write else "0",
             *extra_grant_args,
         )
@@ -724,12 +724,12 @@ async def _validate_remote_path_access(
             if resolved:
                 # Preserve the requested workspace path so leaf symlinks keep their normal
                 # semantics while the remote realpath check still enforces path confinement.
-                return workspace_path
+                return cast(Path, workspace_path)
             raise ExecTransportError(
                 command=(
                     "resolve_workspace_path",
-                    str(root),
-                    str(workspace_path),
+                    root.as_posix(),
+                    workspace_path.as_posix(),
                     "1" if for_write else "0",
                     *extra_grant_args,
                 ),
@@ -746,7 +746,7 @@ async def _validate_remote_path_access(
         )
         if result.exit_code == 111:
             raise InvalidManifestPathError(
-                rel=original_path,
+                rel=original_path.as_posix(),
                 reason=reason,
                 context={
                     "resolved_path": result.stderr.decode("utf-8", errors="replace").strip(),
@@ -762,13 +762,13 @@ async def _validate_remote_path_access(
                     context["grant_path"] = line.removeprefix("read-only extra path grant: ")
                 elif line.startswith("resolved path: "):
                     context["resolved_path"] = line.removeprefix("resolved path: ")
-            raise WorkspaceArchiveWriteError(path=workspace_path, context=context)
+            raise WorkspaceArchiveWriteError(path=Path(workspace_path.as_posix()), context=context)
         raise ExecNonZeroError(
             result,
             command=(
                 "resolve_workspace_path",
-                str(root),
-                str(workspace_path),
+                root.as_posix(),
+                workspace_path.as_posix(),
                 "1" if for_write else "0",
                 *extra_grant_args,
             ),

src/agents/sandbox/session/runtime_helpers.py

@@ -2,10 +2,10 @@
 
 import hashlib
 from dataclasses import dataclass
-from pathlib import Path
+from pathlib import PurePath, PurePosixPath
 from typing import Final
 
-_HELPER_INSTALL_ROOT: Final[Path] = Path("/tmp/openai-agents/bin")
+_HELPER_INSTALL_ROOT: Final[PurePosixPath] = PurePosixPath("/tmp/openai-agents/bin")
 _INSTALL_MARKER: Final[str] = "INSTALL_RUNTIME_HELPER_V1"
 
 _RESOLVE_WORKSPACE_PATH_SCRIPT: Final[str] = """
@@ -249,7 +249,7 @@
 class RuntimeHelperScript:
     name: str
     content: str
-    install_path: Path
+    install_path: PurePath
     install_marker: str = _INSTALL_MARKER
 
     @classmethod

src/agents/sandbox/workspace_paths.py

@@ -34,7 +34,7 @@ class SandboxPathGrant(BaseModel):
     @field_validator("path", mode="before")
     @classmethod
     def _coerce_path(cls, value: object) -> str:
-        if isinstance(value, Path):
+        if isinstance(value, PurePath):
             return value.as_posix()
         if isinstance(value, str):
             return value
@@ -56,10 +56,11 @@ class WorkspacePathPolicy:
     def __init__(
         self,
         *,
-        root: str | Path,
+        root: str | PurePath,
         extra_path_grants: tuple[SandboxPathGrant, ...] = (),
     ) -> None:
         self._root = Path(root)
+        self._sandbox_root = self._coerce_posix_path(root)
         self._extra_path_grants = extra_path_grants
 
     def absolute_workspace_path(self, path: str | Path) -> Path:
@@ -105,11 +106,31 @@ def normalize_path(
         if resolve_symlinks:
             result, grant = self._resolved_host_path_and_grant(original)
         else:
-            result, grant = self._sandbox_path_and_grant(original)
+            sandbox_result, grant = self._sandbox_path_and_grant(self._coerce_posix_path(original))
+            result = Path(sandbox_result.as_posix())
         if for_write:
             self._raise_if_read_only_grant(result, grant)
         return result
 
+    def normalize_sandbox_path(
+        self,
+        path: str | PurePath,
+        *,
+        for_write: bool = False,
+    ) -> PurePosixPath:
+        """Return a validated POSIX path for a Unix-like remote sandbox filesystem."""
+
+        original = self._coerce_posix_path(path)
+        result, grant = self._sandbox_path_and_grant(original)
+        if for_write:
+            self._raise_if_read_only_grant(Path(result.as_posix()), grant)
+        return result
+
+    def sandbox_root(self) -> PurePosixPath:
+        """Return the workspace root as a POSIX path for remote sandbox commands."""
+
+        return self._normalized_root()
+
     def _resolved_host_path_and_grant(
         self,
         original: Path,
@@ -130,18 +151,18 @@ def _resolved_host_path_and_grant(
 
     def _sandbox_path_and_grant(
         self,
-        original: Path,
-    ) -> tuple[Path, SandboxPathGrant | None]:
+        original: PurePath,
+    ) -> tuple[PurePosixPath, SandboxPathGrant | None]:
         normalized = (
             self._absolute_posix_path(original)
             if original.is_absolute()
             else self._absolute_workspace_posix_path(original)
         )
         if self._is_under(normalized, self._normalized_root()):
-            return Path(str(normalized)), None
+            return normalized, None
         grant = self._matching_grant(normalized)
         if original.is_absolute() and grant is not None:
-            return Path(str(normalized)), grant
+            return normalized, grant
         raise self._invalid_path_error(original)
 
     def _raise_if_read_only_grant(
@@ -159,17 +180,17 @@ def _raise_if_read_only_grant(
             },
         )
 
-    def extra_path_grant_rules(self) -> tuple[tuple[Path, bool], ...]:
+    def extra_path_grant_rules(self) -> tuple[tuple[PurePosixPath, bool], ...]:
         """Return normalized extra grant roots and access modes for remote realpath checks."""
 
-        rules: list[tuple[Path, bool]] = []
+        rules: list[tuple[PurePosixPath, bool]] = []
         for grant in self._extra_path_grants:
-            root = Path(grant.path)
+            root = self._coerce_posix_path(grant.path)
             _raise_if_filesystem_root(root)
             rules.append((root, grant.read_only))
         return tuple(rules)
 
-    def _absolute_workspace_posix_path(self, path: Path) -> PurePosixPath:
+    def _absolute_workspace_posix_path(self, path: PurePath) -> PurePosixPath:
         normalized = self._absolute_posix_path(path)
         root = self._normalized_root()
         try:
@@ -178,13 +199,13 @@ def _absolute_workspace_posix_path(self, path: Path) -> PurePosixPath:
             raise self._invalid_path_error(path, cause=exc) from exc
         return normalized
 
-    def _absolute_posix_path(self, path: Path) -> PurePosixPath:
+    def _absolute_posix_path(self, path: PurePath) -> PurePosixPath:
         root = self._normalized_root()
         raw_candidate = path.as_posix() if path.is_absolute() else str(root / path.as_posix())
         return PurePosixPath(posixpath.normpath(str(raw_candidate)))
 
     def _normalized_root(self) -> PurePosixPath:
-        return PurePosixPath(posixpath.normpath(self._root.as_posix()))
+        return PurePosixPath(posixpath.normpath(self._sandbox_root.as_posix()))
 
     def _matching_grant(
         self,
@@ -212,11 +233,17 @@ def _is_under(path: PurePath, root: PurePath) -> bool:
 
     def _invalid_path_error(
         self,
-        path: Path,
+        path: PurePath,
         *,
         cause: BaseException | None = None,
     ) -> InvalidManifestPathError:
         reason: Literal["absolute", "escape_root"] = (
             "absolute" if path.is_absolute() else "escape_root"
         )
-        return InvalidManifestPathError(rel=path, reason=reason, cause=cause)
+        return InvalidManifestPathError(rel=path.as_posix(), reason=reason, cause=cause)
+
+    @staticmethod
+    def _coerce_posix_path(path: str | PurePath) -> PurePosixPath:
+        if isinstance(path, PurePath):
+            path = path.as_posix()
+        return PurePosixPath(posixpath.normpath(path))

tests/conftest.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import sys
+
 import pytest
 
 from agents.models import _openai_shared
@@ -11,6 +13,27 @@
 
 from .testing_processor import SPAN_PROCESSOR_TESTING
 
+collect_ignore: list[str] = []
+
+if sys.platform == "win32":
+    collect_ignore.extend(
+        [
+            "test_example_workflows.py",
+            "test_run_state.py",
+            "test_sandbox_memory.py",
+            "sandbox/capabilities/test_filesystem_capability.py",
+            "sandbox/integration_tests/test_runner_pause_resume.py",
+            "sandbox/test_client_options.py",
+            "sandbox/test_exposed_ports.py",
+            "sandbox/test_extract.py",
+            "sandbox/test_runtime.py",
+            "sandbox/test_session_manager.py",
+            "sandbox/test_session_sinks.py",
+            "sandbox/test_snapshot.py",
+            "sandbox/test_unix_local.py",
+        ]
+    )
+
 
 # This fixture will run once before any tests are executed
 @pytest.fixture(scope="session", autouse=True)