Backtestsopenai-agents-pythonrun-20261024-184640#4675

Issue #4675 Merged fix PR #4700 Run 24 Oct 2026 · run-20261024-184640 openai/openai-agents-python

UnixLocalSandbox blocks the event loop with synchronous filesystem and tar I/O

Better

Our patch was judged better than the merged fix.

In this judgment, Patch A = our agent, Patch B = the merged fix.

Both patches move the two unbounded tar paths onto a worker thread and keep waiting for the worker through cancellation, and the five independent tests (non-blocking persist/hydrate, cancellation waits for worker including double cancel, cancellation still reported when the worker fails) pass on both, so core correctness is equivalent for the scenarios in the issue. The differences are in robustness and tests. Patch A awaits a plain executor future behind asyncio.shield, so nothing but the worker itself can mark it done; Patch B wraps asyncio.to_thread in a Task, which loop shutdown (asyncio.run's cancel-all-tasks) can cancel while the thread is still extracting, after which the caller sees task.done(), re-raises the recorded cancellation, and resume's finally closes the stream under the running worker. Patch A's comment calls out exactly this and avoids it. On tests, Patch A adds five regression tests: two that verify the body runs off the loop thread and that the loop can release a gated worker (fails on base because the gate times out on the loop thread), two cancellation-waits tests for persist and hydrate (including a second cancel), and an error-mapping test. Patch B adds a single hydrate-cancellation test and nothing that directly checks the headline defect (event loop not stalled) or persist_workspace at all. On scope, B also offloads shutil.rmtree in the delete path and adds a new util module; that is unrequested but low risk, so neutral, while A stays inside unix_local.py consistent with the module's existing run_in_executor/to_thread usage. Craft is comparable: A's error mapping lives in the worker functions, B keeps the original try/except around the await; both clear. A wins on test coverage and the shutdown-cancellation edge.

Four judges ruled on this ticket in parallel, and the verdict comes from counting their votes. Each saw the issue and the two patches, labelled A and B in random order (two of them saw ours as A), with issue links and version numbers removed. Where tests could check the fix, they also saw the results of tests a separate agent wrote for the issue, run on both patches. None was told which patch was ours. The reasoning above is one judge's, shown verbatim.

Solve

8m 23s

Wall-clock time in the container

Full test suite

No new failures

1,389 passed · 4 skipped · 1,393 total

Contamination audit

Clean

No sign the agent saw the real fix

Patch size

282vs 104 merged

Changed lines, ours vs merged

Please read this first

  • Have you read the docs? Yes.
  • Have you searched for related issues? Yes. Nothing covers blocking filesystem work in the sandbox backends.

Describe the bug

UnixLocalSandboxSession calls synchronous pathlib and tarfile APIs directly from async def methods, so those methods block the event loop for the full duration of the I/O instead of yielding.

The two unbounded ones archive or extract the entire workspace tree:

async def persist_workspace(self) -> io.IOBase:
    root = Path(self.state.manifest.root)
    if not root.exists():                        # blocking stat
        ...
    buf = io.BytesIO()
    with tarfile.open(fileobj=buf, mode="w") as tar:
        tar.add(root, arcname=".", filter=...)   # blocking walk + read of the whole tree

async def hydrate_workspace(self, data: io.IOBase) -> None:
    root = Path(self.state.manifest.root)
    root.mkdir(parents=True, exist_ok=True)
    with tarfile.open(fileobj=data, mode="r:*") as tar:
        safe_extract_tarfile(tar, root=root, ...)  # blocking extraction of the whole tree

Both sit directly on the snapshot path: persist_snapshot() awaits session.persist_workspace() and restore_snapshot_into_workspace_on_resume() awaits session.hydrate_workspace() (src/agents/sandbox/session/snapshot_lifecycle.py). A workspace holding a node_modules, a build directory, or a model checkpoint takes seconds to minutes to tar, and the whole application's loop is stalled for that window: concurrent agent runs, streamed responses, MCP sessions, and tracing exports all freeze. That rules the local sandbox out of any server process handling more than one run at a time.

Scope note (edited after review feedback): this report originally also listed the bounded mkdir, exists, and resolve calls in _prepare_backend_workspace, _resolved_exec_context, _exec_internal, pty_exec_start and _write_stream_with_exec. Those are possible cleanup candidates, but a static ASYNC240 report on its own does not establish a user-visible defect for them, and I have no measurement showing one. The defect claimed here is limited to the two unbounded archive paths above.

The pattern already exists in this file

This is a gap rather than a design decision: the same module already offloads its other blocking work, with loop.run_in_executor(None, os.read, ...) for PTY reads (line 517) and asyncio.to_thread(_close_fd_quietly, fd) for fd cleanup (line 616). sandbox/session/sinks.py uses asyncio.to_thread too. The filesystem and tar paths were simply missed.

Why CI does not catch it

ruff --select ASYNC reports the two archive methods (along with five bounded sites that this report does not claim as a defect):

src/agents/sandbox/sandboxes/unix_local.py:1079:16: ASYNC240 Async functions should not use pathlib.Path methods
src/agents/sandbox/sandboxes/unix_local.py:1110:13: ASYNC240

make lint stays green because pyproject.toml pins ruff==0.9.2 in the dev group, which predates the ASYNC240 rule. Reproducing the report needs a newer ruff (checked with 0.16.3).

Debug information

  • Agents SDK version: main at e773b154, and v0.22.0
  • Python version: 3.13
  • Operating system: Linux (the module raises ImportError on Windows by design)
  • Model and model provider: n/a — no model or network involved
  • Does the issue reproduce with the latest Agents SDK release? Yes, and on main.
  • Does the issue occur consistently or intermittently? Consistently.

Repro steps

Any coroutine sharing the loop stops making progress for the duration of the archive:

import asyncio, time

async def heartbeat(stop):
    last = time.monotonic()
    worst = 0.0
    while not stop.is_set():
        await asyncio.sleep(0.05)
        now = time.monotonic()
        worst = max(worst, now - last)
        last = now
    print(f"worst loop stall: {worst:.2f}s")

async def main(session):          # a started UnixLocalSandboxSession whose
    stop = asyncio.Event()        # workspace holds a few hundred MB
    task = asyncio.create_task(heartbeat(stop))
    await session.persist_workspace()
    stop.set()
    await task

The reported stall tracks the tar duration, instead of staying near the 0.05s tick.

Expected behavior

These methods should not hold the event loop. Move the blocking bodies onto a worker thread, matching what the rest of the module already does.

That needs explicit cancellation ownership to be correct. asyncio.to_thread cannot interrupt the thread it starts, so a cancelled caller would return while the worker is still walking or writing the workspace — and callers act on that return immediately: restore_snapshot_into_workspace_on_resume closes the archive stream in a finally, and resume clears the workspace root. So these methods must wait for the worker to settle before reporting cancellation.

I have a fix with regression tests and will open a PR shortly.

The two patches

Our patch+239 −43
src/agents/sandbox/sandboxes/unix_local.pyindex 5cc77e2a..1858b53f 100644@@ -21,12 +21,12 @@ import termios import time import uuid from collections import deque-from collections.abc import Collection, Mapping, Sequence+from collections.abc import Callable, Collection, Mapping, Sequence from contextlib import suppress from dataclasses import dataclass, field from functools import partial from pathlib import Path-from typing import Literal, cast+from typing import Literal, TypeVar, cast  from ...logger import log_tool_action_warning from .._mount_security import redact_mount_error_data@@ -100,6 +100,7 @@ _HOST_ENVIRONMENT_ALLOWLIST = frozenset( )  logger = logging.getLogger(__name__)+_T = TypeVar("_T")   def _mount_path_diagnostic_extra(mount_path: Path) -> dict[str, object]:@@ -1076,50 +1077,83 @@ class UnixLocalSandboxSession(BaseSandboxSession):      async def persist_workspace(self) -> io.IOBase:         root = Path(self.state.manifest.root)-        if not root.exists():-            raise WorkspaceArchiveReadError(-                path=root, context={"reason": "workspace_root_not_found"}-            )-         skip = self._persist_workspace_skip_relpaths()-        buf = io.BytesIO()-        try:-            with tarfile.open(fileobj=buf, mode="w") as tar:-                tar.add(-                    root,-                    arcname=".",-                    filter=lambda ti: (-                        None-                        if should_skip_tar_member(-                            ti.name,-                            skip_rel_paths=skip,-                            root_name=None,-                        )-                        else ti-                    ),-                )-        except (tarfile.TarError, OSError) as e:-            raise WorkspaceArchiveReadError(path=root, cause=e) from e--        buf.seek(0)-        return buf+        return await _run_blocking_in_thread(_archive_workspace_root, root, skip)      async def hydrate_workspace(self, data: io.IOBase) -> None:         root = Path(self.state.manifest.root)-        try:-            root.mkdir(parents=True, exist_ok=True)-            with tarfile.open(fileobj=data, mode="r:*") as tar:-                safe_extract_tarfile(-                    tar,-                    root=root,-                    allow_external_symlink_targets=False,-                )-        except UnsafeTarMemberError as e:-            raise WorkspaceArchiveWriteError(-                path=root, context={"reason": e.reason, "member": e.member}, cause=e-            ) from e-        except (tarfile.TarError, OSError) as e:-            raise WorkspaceArchiveWriteError(path=root, cause=e) from e+        await _run_blocking_in_thread(_extract_workspace_archive, root, data)+++def _archive_workspace_root(root: Path, skip: set[Path]) -> io.IOBase:+    if not root.exists():+        raise WorkspaceArchiveReadError(path=root, context={"reason": "workspace_root_not_found"})++    buf = io.BytesIO()+    try:+        with tarfile.open(fileobj=buf, mode="w") as tar:+            tar.add(+                root,+                arcname=".",+                filter=lambda ti: (+                    None+                    if should_skip_tar_member(+                        ti.name,+                        skip_rel_paths=skip,+                        root_name=None,+                    )+                    else ti+                ),+            )+    except (tarfile.TarError, OSError) as e:+        raise WorkspaceArchiveReadError(path=root, cause=e) from e++    buf.seek(0)+    return buf+++def _extract_workspace_archive(root: Path, data: io.IOBase) -> None:+    try:+        root.mkdir(parents=True, exist_ok=True)+        with tarfile.open(fileobj=data, mode="r:*") as tar:+            safe_extract_tarfile(+                tar,+                root=root,+                allow_external_symlink_targets=False,+            )+    except UnsafeTarMemberError as e:+        raise WorkspaceArchiveWriteError(+            path=root, context={"reason": e.reason, "member": e.member}, cause=e+        ) from e+    except (tarfile.TarError, OSError) as e:+        raise WorkspaceArchiveWriteError(path=root, cause=e) from e+++async def _run_blocking_in_thread(func: Callable[..., _T], /, *args: object) -> _T:+    """Run blocking filesystem work on a worker thread without holding the event loop.++    A thread cannot be interrupted, so if the caller is cancelled we keep waiting until the+    worker settles before propagating the cancellation. Callers act on our return immediately+    (closing the archive stream, clearing the workspace root), so returning while the worker is+    still reading or writing the workspace would race with them.+    """+    # A plain executor future rather than a Task: loop shutdown cancels every pending Task, which+    # would mark the worker done while its thread is still touching the workspace.+    worker = asyncio.get_running_loop().run_in_executor(None, func, *args)+    try:+        return await asyncio.shield(worker)+    except asyncio.CancelledError:+        while not worker.done():+            try:+                await asyncio.wait((worker,))+            except asyncio.CancelledError:+                continue+        if not worker.cancelled() and worker.exception() is not None:+            logger.debug(+                "UnixLocal worker failed after its caller was cancelled",+                exc_info=worker.exception(),+            )+        raise   class UnixLocalSandboxClient(BaseSandboxClient[UnixLocalSandboxClientOptions | None]):tests/sandbox/test_unix_local.pyindex c8e9c654..18e8fb85 100644@@ -1,7 +1,10 @@ from __future__ import annotations  import asyncio+import io import signal+import tarfile+import threading from pathlib import Path from types import SimpleNamespace from typing import cast@@ -9,7 +12,11 @@ from typing import cast import pytest  from agents.sandbox import SandboxPathGrant-from agents.sandbox.errors import PtySessionNotFoundError+from agents.sandbox.errors import (+    PtySessionNotFoundError,+    WorkspaceArchiveReadError,+    WorkspaceArchiveWriteError,+) from agents.sandbox.manifest import Environment, Manifest from agents.sandbox.sandboxes import unix_local as unix_local_module from agents.sandbox.sandboxes.unix_local import (@@ -210,6 +217,161 @@ async def test_unix_local_rejects_host_path_before_creating_workspace(         )  +class _ThreadGate:+    """Blocks a worker until the event loop releases it, recording where it ran."""++    def __init__(self) -> None:+        self.started = threading.Event()+        self.release = threading.Event()+        self.released_by_loop: bool | None = None+        self.ran_on_loop_thread: bool | None = None+        self._loop_thread = threading.get_ident()++    def block(self) -> None:+        if self.started.is_set():+            return+        self.ran_on_loop_thread = threading.get_ident() == self._loop_thread+        self.started.set()+        # If this runs on the event loop thread, the loop can never set ``release``.+        self.released_by_loop = self.release.wait(timeout=5)+++def _workspace_tar(files: dict[str, bytes]) -> io.BytesIO:+    buf = io.BytesIO()+    with tarfile.open(fileobj=buf, mode="w") as tar:+        for name, payload in files.items():+            info = tarfile.TarInfo(name)+            info.size = len(payload)+            tar.addfile(info, io.BytesIO(payload))+    buf.seek(0)+    return buf+++def _gate_should_skip(monkeypatch: pytest.MonkeyPatch, gate: _ThreadGate) -> None:+    original = unix_local_module.should_skip_tar_member++    def gated(*args: object, **kwargs: object) -> bool:+        gate.block()+        return original(*args, **kwargs)  # type: ignore[arg-type]++    monkeypatch.setattr(unix_local_module, "should_skip_tar_member", gated)+++def _gate_safe_extract(monkeypatch: pytest.MonkeyPatch, gate: _ThreadGate) -> None:+    original = unix_local_module.safe_extract_tarfile++    def gated(*args: object, **kwargs: object) -> None:+        gate.block()+        original(*args, **kwargs)  # type: ignore[arg-type]++    monkeypatch.setattr(unix_local_module, "safe_extract_tarfile", gated)+++@pytest.mark.asyncio+async def test_unix_local_persist_workspace_does_not_block_event_loop(+    tmp_path: Path,+    monkeypatch: pytest.MonkeyPatch,+) -> None:+    (tmp_path / "file.txt").write_text("hello")+    session = _RecordingUnixLocalSession(tmp_path)+    gate = _ThreadGate()+    _gate_should_skip(monkeypatch, gate)++    task = asyncio.create_task(session.persist_workspace())+    assert await asyncio.to_thread(gate.started.wait, 5)+    gate.release.set()+    archive = await asyncio.wait_for(task, timeout=5)++    assert gate.ran_on_loop_thread is False+    assert gate.released_by_loop is True+    with tarfile.open(fileobj=archive, mode="r:*") as tar:+        member = tar.extractfile("./file.txt")+        assert member is not None+        assert member.read() == b"hello"+++@pytest.mark.asyncio+async def test_unix_local_hydrate_workspace_does_not_block_event_loop(+    tmp_path: Path,+    monkeypatch: pytest.MonkeyPatch,+) -> None:+    root = tmp_path / "workspace"+    session = _RecordingUnixLocalSession(root)+    gate = _ThreadGate()+    _gate_safe_extract(monkeypatch, gate)++    task = asyncio.create_task(session.hydrate_workspace(_workspace_tar({"file.txt": b"hi"})))+    assert await asyncio.to_thread(gate.started.wait, 5)+    gate.release.set()+    await asyncio.wait_for(task, timeout=5)++    assert gate.ran_on_loop_thread is False+    assert gate.released_by_loop is True+    assert (root / "file.txt").read_bytes() == b"hi"+++@pytest.mark.asyncio+async def test_unix_local_persist_workspace_cancellation_waits_for_worker(+    tmp_path: Path,+    monkeypatch: pytest.MonkeyPatch,+) -> None:+    (tmp_path / "file.txt").write_text("hello")+    session = _RecordingUnixLocalSession(tmp_path)+    gate = _ThreadGate()+    _gate_should_skip(monkeypatch, gate)++    task = asyncio.create_task(session.persist_workspace())+    assert await asyncio.to_thread(gate.started.wait, 5)+    task.cancel()+    await asyncio.sleep(0.1)+    # A second cancellation must not let the call return early either.+    task.cancel()+    await asyncio.sleep(0.1)+    assert not task.done()++    gate.release.set()+    with pytest.raises(asyncio.CancelledError):+        await asyncio.wait_for(task, timeout=5)+    assert gate.released_by_loop is True+++@pytest.mark.asyncio+async def test_unix_local_hydrate_workspace_cancellation_waits_for_worker(+    tmp_path: Path,+    monkeypatch: pytest.MonkeyPatch,+) -> None:+    root = tmp_path / "workspace"+    session = _RecordingUnixLocalSession(root)+    gate = _ThreadGate()+    _gate_safe_extract(monkeypatch, gate)+    data = _workspace_tar({"file.txt": b"hi"})++    task = asyncio.create_task(session.hydrate_workspace(data))+    assert await asyncio.to_thread(gate.started.wait, 5)+    task.cancel()+    await asyncio.sleep(0.1)+    assert not task.done()++    gate.release.set()+    with pytest.raises(asyncio.CancelledError):+        await asyncio.wait_for(task, timeout=5)+    # The extraction finished before cancellation was reported, so closing the stream and+    # touching the workspace afterwards cannot race the worker.+    assert (root / "file.txt").read_bytes() == b"hi"+    data.close()+++@pytest.mark.asyncio+async def test_unix_local_archive_errors_are_still_mapped_from_worker(tmp_path: Path) -> None:+    missing = _RecordingUnixLocalSession(tmp_path / "missing")+    with pytest.raises(WorkspaceArchiveReadError):+        await missing.persist_workspace()++    session = _RecordingUnixLocalSession(tmp_path / "workspace")+    with pytest.raises(WorkspaceArchiveWriteError):+        await session.hydrate_workspace(io.BytesIO(b"not a tar archive"))++ @pytest.mark.review_optional class TestUnixLocalPty:     @pytest.mark.asyncio 
Merged fix · PR #4700+101 −3
src/agents/sandbox/sandboxes/unix_local.pyindex 5cc77e2af..ea7f83e9d 100644@@ -62,6 +62,7 @@ from ..session.sandbox_client import BaseSandboxClient, BaseSandboxClientOptions from ..session.workspace_payloads import coerce_write_payload from ..snapshot import SnapshotBase, SnapshotSpec, resolve_snapshot from ..types import ExecResult, ExposedPortEndpoint, Permissions, User+from ..util.blocking_io import run_blocking_workspace_io from ..util.tar_utils import (     UnsafeTarMemberError,     safe_extract_tarfile,@@ -962,7 +963,7 @@ class UnixLocalSandboxSession(BaseSandboxSession):         try:             if normalized.is_dir() and not normalized.is_symlink():                 if recursive:-                    shutil.rmtree(normalized)+                    await run_blocking_workspace_io(shutil.rmtree, normalized)                 else:                     normalized.rmdir()             else:@@ -1083,7 +1084,8 @@ class UnixLocalSandboxSession(BaseSandboxSession):          skip = self._persist_workspace_skip_relpaths()         buf = io.BytesIO()-        try:++        def _archive_workspace() -> None:             with tarfile.open(fileobj=buf, mode="w") as tar:                 tar.add(                     root,@@ -1098,6 +1100,9 @@ class UnixLocalSandboxSession(BaseSandboxSession):                         else ti                     ),                 )++        try:+            await run_blocking_workspace_io(_archive_workspace)         except (tarfile.TarError, OSError) as e:             raise WorkspaceArchiveReadError(path=root, cause=e) from e @@ -1106,7 +1111,8 @@ class UnixLocalSandboxSession(BaseSandboxSession):      async def hydrate_workspace(self, data: io.IOBase) -> None:         root = Path(self.state.manifest.root)-        try:++        def _extract_workspace() -> None:             root.mkdir(parents=True, exist_ok=True)             with tarfile.open(fileobj=data, mode="r:*") as tar:                 safe_extract_tarfile(@@ -1114,6 +1120,9 @@ class UnixLocalSandboxSession(BaseSandboxSession):                     root=root,                     allow_external_symlink_targets=False,                 )++        try:+            await run_blocking_workspace_io(_extract_workspace)         except UnsafeTarMemberError as e:             raise WorkspaceArchiveWriteError(                 path=root, context={"reason": e.reason, "member": e.member}, cause=esrc/agents/sandbox/util/blocking_io.pynew file mode 100644index 000000000..ff8b58a32@@ -0,0 +1,40 @@+"""Run unbounded blocking workspace I/O off the event loop without abandoning it.++`asyncio.to_thread()` does not stop its worker when the awaiting task is cancelled, so a+cancelled caller can return while the thread is still writing. Snapshot resume closes the+archive stream and clears the workspace root as soon as its await returns, which would let a+surviving worker extract into a workspace that is being deleted.++Callers therefore keep waiting for the worker even while cancelled, matching the mutation+semantics the session backends already rely on in `agents.memory.sqlite_session`.+"""++from __future__ import annotations++import asyncio+from collections.abc import Callable+from typing import Any, TypeVar++_T = TypeVar("_T")+++async def run_blocking_workspace_io(function: Callable[..., _T], /, *args: Any) -> _T:+    """Run `function` in a worker thread and keep ownership until that worker finishes."""+    task = asyncio.ensure_future(asyncio.to_thread(function, *args))+    cancellation: asyncio.CancelledError | None = None+    while not task.done():+        try:+            await asyncio.wait({task})+        except asyncio.CancelledError as exc:+            if cancellation is None:+                cancellation = exc++    try:+        result = task.result()+    except BaseException:+        if cancellation is not None:+            raise cancellation from None+        raise+    if cancellation is not None:+        raise cancellation from None+    return resulttests/sandbox/test_unix_local.pyindex c8e9c654a..fb13be3c5 100644@@ -1,7 +1,11 @@ from __future__ import annotations  import asyncio+import io import signal+import tarfile+import threading+import time from pathlib import Path from types import SimpleNamespace from typing import cast@@ -464,3 +468,48 @@ class TestUnixLocalUserScopedFilesystem:         assert session.exec_commands[0][4:6] == ("sh", "-lc")         assert session.exec_commands[0][-2:] == (str(target), "0")         assert not any(part.startswith("rm ") for part in session.exec_commands[0])+++@pytest.mark.asyncio+async def test_hydrate_workspace_cancellation_waits_for_the_extracting_worker(+    tmp_path: Path,+    monkeypatch: pytest.MonkeyPatch,+) -> None:+    """A cancelled hydrate must not leave a worker writing into the workspace.++    `restore_snapshot_into_workspace_on_resume` closes the archive stream in a `finally` as+    soon as its await returns, so if cancellation propagated while the extractor was still+    running it would read a closed stream and write into a workspace resume then clears.+    """+    workspace = tmp_path / "workspace"+    session = _RecordingUnixLocalSession(workspace)++    started = threading.Event()+    events: list[str] = []++    def _slow_extract(tar: object, **kwargs: object) -> None:+        _ = tar, kwargs+        events.append("extract-start")+        started.set()+        time.sleep(0.2)+        events.append("extract-end")++    monkeypatch.setattr(unix_local_module, "safe_extract_tarfile", _slow_extract)++    buf = io.BytesIO()+    with tarfile.open(fileobj=buf, mode="w"):+        pass+    buf.seek(0)++    task = asyncio.create_task(session.hydrate_workspace(buf))+    while not started.is_set():+        await asyncio.sleep(0.005)+    task.cancel()++    with pytest.raises(asyncio.CancelledError):+        await task++    # The worker finished before the caller observed cancellation, so the archive stream and+    # the workspace root are only released once nothing is still writing to them.+    assert events == ["extract-start", "extract-end"]+    assert not buf.closed