code-sandboxes 1.4.5__tar.gz → 1.4.6__tar.gz

{code_sandboxes-1.4.5 → code_sandboxes-1.4.6}/CHANGELOG.md

@@ -8,6 +8,35 @@
 
 ## Unreleased
 
+- **Every variant has a real interrupt now, and can be reached to give it.**
+  `Sandbox.interrupt` is two gates — `_executing_event` must be set, then
+  `_do_interrupt` must answer — and seven variants failed one of them, each in
+  a way that looked like success:
+
+  - `docker`, `google_colab`, `kaggle` and `monty` had no `_do_interrupt`, so
+    the base default ran: set a flag, return `True`, stop nothing. `True` means
+    "the interrupt was delivered", and nothing had been. `google_colab` and
+    `kaggle` did read the flag, but only *after* the run, to label a finished
+    result as `interrupted` — labelling a run is not stopping one.
+  - `cloudflare`, `coreweave`, `daytona`, `e2b` and `modal` answered honestly
+    (`False`: this provider takes no interrupt) but never marked their execution
+    window, so `interrupt()` returned at the first gate and their answer was
+    never reached — and `is_executing` was always False, which every status
+    above them believed.
+
+  Docker, Colab and Kaggle now interrupt for real, delegating to the
+  `JupyterKernelClient` that already knows how to authenticate to their server
+  rather than rebuilding the request. Monty answers `False` with its reason:
+  `feed_run` executes a snippet in one blocking call with no limits and no
+  callable hook, so there is no point at which a flag could be read.
+
+  The execution window is `@marks_execution` on `run_code` rather than a line
+  in each body, because it has to close on *every* path out — including the
+  early `return ExecutionResult(...)` each adapter uses for an infrastructure
+  failure — and a `finally` in the decorator cannot be forgotten in one branch
+  of one variant. Both invariants are asserted across the package with no
+  pinned exceptions left.
+
 - A Datalayer sandbox says when it is running code, so an interrupt can reach
   it. `Sandbox.interrupt` refuses before it delegates — `if not
   self._executing_event.is_set(): return False` — and `run_code` never set that

{code_sandboxes-1.4.5 → code_sandboxes-1.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code_sandboxes
-Version: 1.4.5
+Version: 1.4.6
 Project-URL: Home, https://github.com/datalayer/code-sandboxes
 Author-email: Datalayer <info@datalayer.io>
 License: BSD 3-Clause License

{code_sandboxes-1.4.5 → code_sandboxes-1.4.6}/code_sandboxes/__version__.py

@@ -3,4 +3,4 @@
 
 """Code Sandboxes."""
 
-__version__ = "1.4.5"
+__version__ = "1.4.6"

{code_sandboxes-1.4.5 → code_sandboxes-1.4.6}/code_sandboxes/base.py

@@ -6,6 +6,7 @@
 
 from __future__ import annotations
 
+import functools
 import threading
 import uuid
 from abc import ABC, abstractmethod
@@ -82,6 +83,49 @@ def generate_sandbox_name() -> str:
 DEFAULT_ENVIRONMENT = "ai-agents-env"
 
 
+def marks_execution(run):
+    """Say, for the duration of the call, that this sandbox is running code.
+
+    `Sandbox.interrupt` refuses before it delegates::
+
+        if not self._executing_event.is_set():
+            return False
+        self._interrupt_requested.set()
+        return self._do_interrupt()
+
+    So a variant that never sets the event has an interrupt nothing can
+    reach, and an `is_executing` that is always False — every status and
+    every cancel decision above it silently wrong. `DatalayerSandbox` was in
+    exactly that state, and implementing `_do_interrupt` for it changed the
+    measurement on prod1 from 60.8 seconds to 60.5: a fix that reads as
+    complete and measures as nothing.
+
+    A decorator rather than a line in each body, because the window has to
+    close on *every* path out — including the several early `return
+    ExecutionResult(...)`s that each adapter uses for an infrastructure
+    failure — and a `finally` here cannot be forgotten in one branch of one
+    variant. It also gives the invariant something to test that is not a
+    grep for a line of source.
+
+    `_interrupt_requested` is cleared on the way in, so a stale request from
+    a previous call cannot stop this one, and deliberately *not* on the way
+    out: the cooperative variants read it after the run to report that the
+    execution was interrupted.
+    """
+
+    @functools.wraps(run)
+    def marked(self, *args, **kwargs):
+        self._interrupt_requested.clear()
+        self._executing_event.set()
+        try:
+            return run(self, *args, **kwargs)
+        finally:
+            self._executing_event.clear()
+
+    marked._marks_execution = True
+    return marked
+
+
 class Sandbox(ABC):
     """Abstract base class for code execution sandboxes.
 

{code_sandboxes-1.4.5 → code_sandboxes-1.4.6}/code_sandboxes/cloudflare_sandbox.py

@@ -43,7 +43,7 @@ from collections.abc import Iterator
 from typing import Any
 from urllib.parse import quote
 
-from .base import Sandbox
+from .base import Sandbox, marks_execution
 from .exceptions import (
     SandboxConfigurationError,
     SandboxConnectionError,
@@ -370,6 +370,7 @@ class CloudflareSandbox(Sandbox):
         except Exception:
             return False
 
+    @marks_execution
     def run_code(
         self,
         code: str,

{code_sandboxes-1.4.5 → code_sandboxes-1.4.6}/code_sandboxes/coreweave_sandbox.py

@@ -31,7 +31,7 @@ import math
 import time
 from typing import Any
 
-from .base import Sandbox
+from .base import Sandbox, marks_execution
 from .exceptions import (
     SandboxConfigurationError,
     SandboxExecutionError,
@@ -521,6 +521,7 @@ class CoreWeaveSandbox(Sandbox):
         if self._info:
             self._info.status = SandboxStatus.STOPPED
 
+    @marks_execution
     def run_code(
         self,
         code: str,

{code_sandboxes-1.4.5 → code_sandboxes-1.4.6}/code_sandboxes/datalayer_sandbox.py

@@ -17,7 +17,7 @@ from typing import TYPE_CHECKING, Any, Optional
 if TYPE_CHECKING:
     from .filesystem import SandboxFileHandle
 
-from .base import Sandbox
+from .base import Sandbox, marks_execution
 from .contents import (
     FILESYSTEM_PRIMITIVES,
     LOCAL_BRIDGE_MOUNT,
@@ -761,6 +761,7 @@ class DatalayerSandbox(Sandbox):
             return None
         return 0
 
+    @marks_execution
     def run_code(
         self,
         code: str,
@@ -801,17 +802,9 @@ class DatalayerSandbox(Sandbox):
 
         started_at = time.time()
 
-        # **Say that code is running, because `interrupt()` will not act
-        # unless it can see that.** `Sandbox.interrupt` returns `False`
-        # before reaching `_do_interrupt` when `_executing_event` is clear,
-        # and this variant never set it — so `is_executing` was always False,
-        # every interrupt was refused at the door, and the refusal was
-        # reported as "no code was running" to a caller watching a cell run.
-        # Implementing `_do_interrupt` alone did not fix cancellation for
-        # exactly this reason: nothing ever called it.
+        # The execution window is `@marks_execution`'s, not this body's — see
+        # its docstring for why the interrupt is refused without one.
         execution_timeout = timeout or self.config.timeout
-        self._interrupt_requested.clear()
-        self._executing_event.set()
         try:
             # Set environment variables if provided
             if envs:
@@ -831,8 +824,6 @@ class DatalayerSandbox(Sandbox):
                 started_at=started_at,
                 completed_at=time.time(),
             )
-        finally:
-            self._executing_event.clear()
 
         # Parse the response
         stdout_messages: list[OutputMessage] = []

{code_sandboxes-1.4.5 → code_sandboxes-1.4.6}/code_sandboxes/daytona_sandbox.py

@@ -30,7 +30,7 @@ import textwrap
 import time
 from typing import Any
 
-from .base import Sandbox
+from .base import Sandbox, marks_execution
 from .contents import (
     FILESYSTEM_PRIMITIVES,
     ContentAttachmentSpec,
@@ -701,6 +701,7 @@ class DaytonaSandbox(Sandbox):
             self._contexts[context.id] = existing
         return existing
 
+    @marks_execution
     def run_code(  # noqa: C901
         self,
         code: str,

{code_sandboxes-1.4.5 → code_sandboxes-1.4.6}/code_sandboxes/docker_sandbox.py

@@ -15,9 +15,12 @@ import tempfile
 import time
 import uuid
 
+import logging
+
 import requests
 
-from .base import Sandbox
+from .base import Sandbox, marks_execution
+from .jupyter_ingress import interrupt_kernel_client
 from .exceptions import SandboxConfigurationError, SandboxNotStartedError
 from .interfaces import ISandboxClient
 from .models import (
@@ -34,6 +37,8 @@ from .models import (
     SandboxStatus,
 )
 
+logger = logging.getLogger(__name__)
+
 DEFAULT_IMAGE = "code-sandboxes-jupyter:latest"
 DEFAULT_PORT = 8888
 
@@ -194,6 +199,18 @@ class DockerSandbox(Sandbox):
         """The underlying kernel client for this sandbox, if started."""
         return self._client
 
+    def _do_interrupt(self) -> bool:
+        """Interrupt the container's kernel, through the client that runs it.
+
+        This variant runs a Jupyter Server in a container and executes
+        through `jupyter-kernel-client`, so it can be interrupted — and it
+        had no `_do_interrupt` at all, so the base class's default ran: sets
+        a flag, returns `True`, stops nothing. A caller that cancelled a long
+        cell here was told the interrupt had been delivered while the
+        container went on computing.
+        """
+        return interrupt_kernel_client(self._client, variant="container's")
+
     def stop(self) -> None:
         if not self._started:
             return
@@ -225,6 +242,7 @@ class DockerSandbox(Sandbox):
         if self._info:
             self._info.status = SandboxStatus.STOPPED
 
+    @marks_execution
     def run_code(
         self,
         code: str,

{code_sandboxes-1.4.5 → code_sandboxes-1.4.6}/code_sandboxes/e2b_sandbox.py

@@ -28,7 +28,7 @@ import logging
 import time
 from typing import Any
 
-from .base import Sandbox
+from .base import Sandbox, marks_execution
 from .contents import (
     FILESYSTEM_PRIMITIVES,
     ContentAttachmentSpec,
@@ -471,6 +471,7 @@ class E2BSandbox(Sandbox):
             self._contexts[context.id] = existing
         return existing
 
+    @marks_execution
     def run_code(
         self,
         code: str,

{code_sandboxes-1.4.5 → code_sandboxes-1.4.6}/code_sandboxes/eval_sandbox.py

@@ -24,7 +24,7 @@ import uuid
 from contextlib import contextmanager, redirect_stderr, redirect_stdout
 from typing import Any, Optional
 
-from .base import Sandbox
+from .base import Sandbox, marks_execution
 from .exceptions import SandboxNotStartedError
 from .models import (
     CodeError,
@@ -139,6 +139,7 @@ class EvalSandbox(Sandbox):
             self._execution_count[context.id] = 0
         return context
 
+    @marks_execution
     def run_code(
         self,
         code: str,

{code_sandboxes-1.4.5 → code_sandboxes-1.4.6}/code_sandboxes/google_colab_sandbox.py

@@ -19,7 +19,8 @@ import logging
 import time
 import uuid
 
-from .base import Sandbox
+from .base import Sandbox, marks_execution
+from .jupyter_ingress import interrupt_kernel_client
 from .exceptions import SandboxConfigurationError, SandboxNotStartedError
 from .google_colab import GoogleColabKernelClient, parse_google_colab_channels_url
 from .interfaces import ISandboxClient
@@ -140,6 +141,17 @@ class GoogleColabSandbox(Sandbox):
         """Keep tool calling on the client side for Colab sandboxes."""
         return
 
+    def _do_interrupt(self) -> bool:
+        """Interrupt the Colab kernel, through the client that runs it.
+
+        There was no override here, so the base class's default ran: it sets
+        a flag, returns `True`, and stops nothing. This variant *does* read
+        that flag — but only after the fact, to label a result as
+        `interrupted`. Labelling a run is not stopping one: the notebook kept
+        executing, and the caller had been told the interrupt was delivered.
+        """
+        return interrupt_kernel_client(self._client, variant="Colab")
+
     def stop(self) -> None:
         if not self._started:
             return
@@ -154,6 +166,7 @@ class GoogleColabSandbox(Sandbox):
         if self._info:
             self._info.status = SandboxStatus.STOPPED
 
+    @marks_execution
     def run_code(  # noqa: C901
         self,
         code: str,

{code_sandboxes-1.4.5 → code_sandboxes-1.4.6}/code_sandboxes/jupyter_ingress.py

@@ -6,11 +6,15 @@
 
 from __future__ import annotations
 
+import logging
 import secrets
 import shlex
+from typing import Any
 
 from .models import JupyterServerOptions
 
+logger = logging.getLogger(__name__)
+
 
 def resolved_options(options: JupyterServerOptions | None) -> JupyterServerOptions:
     """Return options carrying a fresh Jupyter token when none was supplied."""
@@ -72,3 +76,29 @@ def websocket_url(http_url: str) -> str:
     if http_url.startswith("http://"):
         return "ws://" + http_url.removeprefix("http://")
     raise ValueError(f"Provider returned a non-HTTP ingress URL: {http_url!r}")
+
+
+def interrupt_kernel_client(client: Any, *, variant: str) -> bool:
+    """Interrupt the kernel a `JupyterKernelClient` is connected to.
+
+    Every Jupyter-backed variant reaches its kernel through a client that
+    already knows how to authenticate to that server — Colab's proxy token
+    header and query parameter, Kaggle's signed proxy URL, Docker's Jupyter
+    token. `JupyterKernelClient.interrupt` uses exactly that, so this
+    delegates rather than rebuilding the request: a second copy of the auth
+    is a second thing to keep in step with the first.
+
+    The client's `interrupt` answers `None` and raises when it fails, so this
+    turns it into the boolean `_do_interrupt` owes its caller. It never
+    raises: a cancel that could not reach the kernel is a cancel that failed,
+    and the caller decides what that means.
+    """
+    if client is None:
+        return False
+    try:
+        client.interrupt()
+    except Exception as error:  # noqa: BLE001 - a failed interrupt is an answer
+        logger.warning("The %s kernel could not be interrupted: %s", variant, error)
+        return False
+    return True
+

{code_sandboxes-1.4.5 → code_sandboxes-1.4.6}/code_sandboxes/jupyter_server_sandbox.py

@@ -29,7 +29,7 @@ from urllib.parse import parse_qs, urlparse, urlunparse
 
 import requests
 
-from .base import Sandbox
+from .base import Sandbox, marks_execution
 from .exceptions import SandboxConfigurationError, SandboxNotStartedError
 from .interfaces import ISandboxClient
 from .models import (
@@ -572,6 +572,7 @@ class JupyterServerSandbox(Sandbox):
             logger.warning(f"Failed to interrupt Jupyter kernel: {e}")
             return False
 
+    @marks_execution
     def run_code(  # noqa: C901
         self,
         code: str,

{code_sandboxes-1.4.5 → code_sandboxes-1.4.6}/code_sandboxes/kaggle_sandbox.py

@@ -33,7 +33,8 @@ from collections.abc import AsyncIterator, Iterator
 from pathlib import Path
 from typing import Any
 
-from .base import Sandbox
+from .base import Sandbox, marks_execution
+from .jupyter_ingress import interrupt_kernel_client
 from .exceptions import SandboxConfigurationError, SandboxNotStartedError
 from .interfaces import ISandboxClient
 from .kaggle import KaggleKernelClient, parse_kaggle_channels_url
@@ -261,6 +262,17 @@ class KaggleSandbox(Sandbox):
                 except (OSError, ValueError):
                     pass
 
+    def _do_interrupt(self) -> bool:
+        """Interrupt the Kaggle kernel, through the client that runs it.
+
+        There was no override here, so the base class's default ran: it sets
+        a flag, returns `True`, and stops nothing. This variant *does* read
+        that flag — but only after the fact, to label a result as
+        `interrupted`. Labelling a run is not stopping one: the notebook kept
+        executing, and the caller had been told the interrupt was delivered.
+        """
+        return interrupt_kernel_client(self._client, variant="Kaggle")
+
     def stop(self) -> None:
         if not self._started:
             return
@@ -277,6 +289,7 @@ class KaggleSandbox(Sandbox):
         if self._info:
             self._info.status = SandboxStatus.STOPPED
 
+    @marks_execution
     def run_code(  # noqa: C901
         self,
         code: str,

{code_sandboxes-1.4.5 → code_sandboxes-1.4.6}/code_sandboxes/modal_sandbox.py

@@ -25,7 +25,7 @@ import time
 import uuid
 from typing import Any
 
-from .base import Sandbox
+from .base import Sandbox, marks_execution
 from .contents import (
     CREDENTIAL_DELIVERY_UNSUPPORTED,
     FILESYSTEM_PRIMITIVES,
@@ -472,6 +472,7 @@ class ModalSandbox(Sandbox):
         if self._info:
             self._info.status = SandboxStatus.STOPPED
 
+    @marks_execution
     def run_code(  # noqa: C901
         self,
         code: str,

{code_sandboxes-1.4.5 → code_sandboxes-1.4.6}/code_sandboxes/monty_sandbox.py

@@ -25,7 +25,7 @@ import time
 import uuid
 from typing import Any
 
-from .base import Sandbox
+from .base import Sandbox, marks_execution
 from .exceptions import SandboxConfigurationError, SandboxNotStartedError
 from .models import (
     CodeError,
@@ -126,6 +126,25 @@ class MontySandbox(Sandbox):
         )
         self._started = True
 
+    def _do_interrupt(self) -> bool:
+        """Monty's REPL takes no interrupt; a timeout is the only stop.
+
+        `False` is the honest answer, and it is the point of writing this at
+        all. Without an override the base class's default ran — set a flag,
+        return `True` — so a caller that cancelled a long run here was told
+        the interrupt had been delivered while the interpreter went on.
+        Answering `False` lets the caller say "this could not be stopped"
+        instead of "this was stopped".
+
+        `MontyRepl.feed_run` executes the whole snippet in one blocking call.
+        It takes no limits (only `Monty.run` does) and its `print_callback`
+        is a `CollectStreams` object the interpreter writes into rather than
+        a callable it invokes, so there is no point at which a flag could be
+        read. If a later Monty exposes a step or callback hook, this is where
+        a cooperative interrupt goes.
+        """
+        return False
+
     def stop(self) -> None:
         if not self._started:
             return
@@ -142,6 +161,7 @@ class MontySandbox(Sandbox):
             return value.decode("utf-8", errors="replace")
         return str(value)
 
+    @marks_execution
     def run_code(  # noqa: C901
         self,
         code: str,

{code_sandboxes-1.4.5 → code_sandboxes-1.4.6}/tests/test_a_datalayer_sandbox_can_be_interrupted.py

@@ -4,13 +4,16 @@
 """A sandbox that cannot be interrupted, and said it had been.
 
 `Sandbox.interrupt` sets a flag and calls `_do_interrupt`, whose default
-"simply sets the interrupt flag" and returns `True`. A variant is entitled to
-that default only if it *reads* the flag — `google_colab` and `kaggle` poll
-`_interrupt_requested` and interrupt cooperatively. `datalayer_sandbox` did
-neither: no override, no read. So on a Datalayer runtime the interrupt was
-delivered nowhere and reported success, and everything above believed it:
-`agent_runtimes`' `interrupt_kernel` delegates straight to it, and so does
-the interrupt `execute_cell` registers for `tasks/cancel`.
+"simply sets the interrupt flag" and returns `True`. `datalayer_sandbox` had
+no override, so on a Datalayer runtime the interrupt was delivered nowhere
+and reported success, and everything above believed it: `agent_runtimes`'
+`interrupt_kernel` delegates straight to it, and so does the interrupt
+`execute_cell` registers for `tasks/cancel`.
+
+This variant, in detail. The invariants that hold for the whole package —
+that no variant inherits the lying default, and that each marks the window
+its interrupt is reachable through — are in
+`test_every_variant_has_a_real_interrupt.py`.
 
 Measured on prod1 on 2026-09-07: a cell looping for two minutes, cancelled
 ten seconds in. `tasks/cancel` and `tasks/get` both answered `cancelled`,
@@ -51,51 +54,12 @@ def _sandbox(runtime):
     return made
 
 
-class TestEveryVariantCanBeInterrupted:
+class TestItHasOneAtAll:
     def test_datalayer_overrides_it_like_the_others(self):
         """The assertion that would have caught this: it is about the class,
         not about a call, because the default *succeeds* silently."""
         assert "_do_interrupt" in DatalayerSandbox.__dict__
 
-    def test_no_variant_quietly_acknowledges_an_interrupt(self):
-        """Held across the package, so the next variant added without one
-        fails here rather than on a runtime somebody is paying for.
-
-        A variant may either override `_do_interrupt` or consult the flag the
-        base sets; doing neither means `interrupt()` returns True having done
-        nothing. `docker` and `monty` do neither today — pinned rather than
-        hidden, so the set cannot grow silently and shrinks visibly when one
-        is fixed.
-        """
-        import importlib
-        import inspect
-        import pkgutil
-
-        import code_sandboxes
-        from code_sandboxes.base import Sandbox
-
-        deaf = set()
-        for module in pkgutil.iter_modules(code_sandboxes.__path__):
-            if not module.name.endswith("_sandbox"):
-                continue
-            loaded = importlib.import_module(f"code_sandboxes.{module.name}")
-            reads_flag = "_interrupt_requested" in inspect.getsource(loaded)
-            for name in dir(loaded):
-                value = getattr(loaded, name)
-                if (
-                    isinstance(value, type)
-                    and issubclass(value, Sandbox)
-                    and value is not Sandbox
-                    and value.__module__ == loaded.__name__
-                    and "_do_interrupt" not in value.__dict__
-                    and not reads_flag
-                ):
-                    deaf.add(f"{module.name}.{name}")
-
-        known = {"docker_sandbox.DockerSandbox", "monty_sandbox.MontySandbox"}
-        assert deaf - known == set(), f"new variants cannot be interrupted: {deaf - known}"
-        assert known - deaf == set(), f"fixed — drop from the pinned set: {known - deaf}"
-
 
 class TestWhatItDoes:
     def test_it_asks_the_runtime_s_own_client(self):
@@ -208,49 +172,3 @@ class TestTheInterruptIsReached:
 
         assert seen == [True], "the sandbox ran code without saying it was running"
         assert not sandbox._executing_event.is_set(), "the flag outlived the execution"
-
-    def test_every_variant_that_can_be_interrupted_says_when_it_runs(self):
-        """The pair, held together: implementing `_do_interrupt` while never
-        setting the event is a fix that changes nothing, and that is the
-        mistake this file exists to stop repeating."""
-        import importlib
-        import inspect
-        import pkgutil
-
-        import code_sandboxes
-        from code_sandboxes.base import Sandbox
-
-        mute = set()
-        for module in pkgutil.iter_modules(code_sandboxes.__path__):
-            if not module.name.endswith("_sandbox"):
-                continue
-            loaded = importlib.import_module(f"code_sandboxes.{module.name}")
-            source = inspect.getsource(loaded)
-            for name in dir(loaded):
-                value = getattr(loaded, name)
-                if (
-                    isinstance(value, type)
-                    and issubclass(value, Sandbox)
-                    and value is not Sandbox
-                    and value.__module__ == loaded.__name__
-                    and "_do_interrupt" in value.__dict__
-                    and "_executing_event.set()" not in source
-                ):
-                    mute.add(f"{module.name}.{name}")
-
-        # Not exemptions — the same unreachable interrupt, pinned. The gate in
-        # `Sandbox.interrupt` is held for every variant, so these five ask a
-        # provider to stop work and are refused before they can: each one has
-        # a written interrupt that nothing can call. Left as found rather than
-        # fixed blind, because none of them can be measured from here.
-        known = {
-            "cloudflare_sandbox.CloudflareSandbox",
-            "coreweave_sandbox.CoreWeaveSandbox",
-            "daytona_sandbox.DaytonaSandbox",
-            "e2b_sandbox.E2BSandbox",
-            "modal_sandbox.ModalSandbox",
-        }
-        assert mute - known == set(), (
-            f"these implement an interrupt nothing can reach: {mute - known}"
-        )
-        assert known - mute == set(), f"reachable now — drop from the pinned set: {known - mute}"