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

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

@@ -8,6 +8,53 @@
 
 ## Unreleased
 
+## 1.7.0
+
+- **A version is resolved into one lock** (`code_sandboxes.environments.resolve`,
+  PLAN_ENV.md E1-04, D-9). Datalayer's protected constraints are merged over the
+  user's requirements — a requirement that agrees with a pin is dropped for it,
+  one that contradicts it is `DL_ENV_PROTECTED_PACKAGE` with the supported range
+  — the base is resolved to a digest per requested variant, and uv's refusals
+  are read into the error taxonomy: a conflict with the pair that cannot hold, a
+  package no index has, a protected pin, and `DL_ENV_PROVIDER_ERROR`, which is
+  retryable, for a failure that is not about the version.
+
+  The lock is uv's hashed output with the apt pins and the protected pins above
+  it as comments: one document that says everything a build installs, and still
+  a requirements file. `BuildkitResolveRunner` is D-9's solve, `FROM` the
+  resolved base digest; `LocalResolveRunner` runs `uv` where it is called, for
+  `plane local`, and refuses to pin apt rather than lock another
+  distribution's versions.
+
+- **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.7.0}/Makefile

@@ -32,10 +32,28 @@ build:
 test:
 	pytest -q
 
+## Build the datalayer-sandbox doctor as a single-file zipapp.
+doctor-zipapp:
+	python -m code_sandboxes.environments.doctor.build dist/datalayer-sandbox
+
+## Regenerate the Environment JSON Schema and the sandbox contract page.
+environments-generate:
+	python -m code_sandboxes.environments schema --write
+	python -m code_sandboxes.environments contract --markdown docs/docs/environments/contract.mdx
+
+## Fail when the Environment JSON Schema or the sandbox contract page has drifted.
+environments-check:
+	python -m code_sandboxes.environments schema --check
+	python -m code_sandboxes.environments contract --check docs/docs/environments/contract.mdx
+
 ## The Contents provider matrix against the real providers (skips those without credentials).
 live-matrix:
 	CODE_SANDBOXES_LIVE=1 pytest -q -m live tests/test_contents_live_matrix.py
 
+## Lose a sandbox on each live provider and check the harness says so.
+kill-relaunch:
+	CODE_SANDBOXES_LIVE=1 pytest -q -m live tests/test_the_kill_relaunch_drill.py
+
 clean: ## clean
 	git clean -fdx
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code_sandboxes
-Version: 1.4.5
+Version: 1.7.0
 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.7.0}/code_sandboxes/__version__.py

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

{code_sandboxes-1.4.5 → code_sandboxes-1.7.0}/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.
 
@@ -455,6 +499,7 @@ class Sandbox(ABC):
         timeout: float | None = None,
         name: str | None = None,
         environment: str | None = None,
+        environment_version: str | int | None = None,
         gpu: str | None = None,
         cpu: float | None = None,
         memory: int | None = None,
@@ -481,7 +526,12 @@ class Sandbox(ABC):
             config: Optional full configuration object (overrides individual params).
             timeout: Default timeout for code execution in seconds.
             name: Optional name for the sandbox.
-            environment: Runtime environment (e.g., "ai-agents-env").
+            environment: Runtime environment (e.g., "ai-agents-env"), or a user
+                environment as "<account-handle>/<name>" or by its uid.
+            environment_version: Which version of a user environment to launch:
+                its number, or a version uid. Without one the promoted version
+                launches, which is what a platform environment always does.
+                Only the datalayer variant has versions (PLAN_ENV.md, E1-19).
             gpu: GPU type to use (e.g., "T4", "A100", "H100"). Only for datalayer.
             cpu: CPU cores to allocate.
             memory: Memory limit in MB.
@@ -515,6 +565,7 @@ class Sandbox(ABC):
             config = SandboxConfig(
                 timeout=timeout or 30.0,
                 environment=environment or DEFAULT_ENVIRONMENT,
+                environment_version=environment_version,
                 memory_limit=memory * 1024 * 1024 if memory else None,
                 cpu_limit=cpu,
                 env_vars=env or {},

{code_sandboxes-1.4.5 → code_sandboxes-1.7.0}/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.7.0}/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.7.0}/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,
@@ -475,11 +475,19 @@ class DatalayerSandbox(Sandbox):
             # Build sandbox name
             sandbox_name = self.config.name or f"sandbox-{self._sandbox_id[:8]}"
 
+            # Which VERSION of that environment, passed through as the
+            # environment is (PLAN_ENV.md, E1-19). `None` means the promoted
+            # version, which is what every platform environment launches — and
+            # what every sandbox launched before there were versions asked for.
+            # The GPU rewrite above is left exactly as it is until E4-11 (D-20).
+            environment_version = self.config.environment_version
+
             # Create the runtime (optionally from snapshot)
             if self._snapshot_name:
                 self._runtime = self._client.create_runtime(
                     name=sandbox_name,
                     environment=environment,
+                    version=environment_version,
                     time_reservation=time_reservation,
                     snapshot_name=self._snapshot_name,
                 )
@@ -487,6 +495,7 @@ class DatalayerSandbox(Sandbox):
                 self._runtime = self._client.create_runtime(
                     name=sandbox_name,
                     environment=environment,
+                    version=environment_version,
                     time_reservation=time_reservation,
                 )
 
@@ -761,6 +770,7 @@ class DatalayerSandbox(Sandbox):
             return None
         return 0
 
+    @marks_execution
     def run_code(
         self,
         code: str,
@@ -801,17 +811,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 +833,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.7.0}/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.7.0}/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.7.0}/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.7.0/code_sandboxes/environments/__init__.py

@@ -0,0 +1,119 @@
+# Copyright (c) 2025-2026 Datalayer, Inc.
+#
+# BSD 3-Clause License
+
+"""Environments: define once, resolve once, build an immutable artifact per variant.
+
+An **Environment** is the stable object a person names. An **Environment
+Version** is immutable once it leaves draft: its spec, the lock resolved from
+it, and its build outcome. An **Environment Artifact** is the build output of
+one version on one variant — an OCI digest for Datalayer, a build id for E2B,
+a snapshot id for Daytona, an image id for Modal.
+
+This package holds what every party to that life shares, and nothing
+provider-specific:
+
+- :mod:`.spec` — the canonical specification and its rules;
+- :mod:`.resolve` — the lock a version is resolved into, once (D-9);
+- :mod:`.contract` — ``sandbox-contract/v1`` and the Dockerfile validator;
+- :mod:`.lifecycle` — the version states and their legal moves;
+- :mod:`.errors` — the error taxonomy every provider error maps into;
+- :mod:`.builders` — the builder interface and its neutral types;
+- :mod:`.conformance` — the checks an artifact passes before it is ready;
+- :mod:`.redact` — a build's log with its secrets taken out before it is stored;
+- :mod:`.doctor` — the in-sandbox contract checker.
+
+The builders themselves are in :mod:`.adapters`, loaded by variant.
+"""
+
+from __future__ import annotations
+
+from .bases import APPROVED_BASES, ApprovedBase
+from .builders import (
+    ArtifactReference,
+    BuildRequest,
+    CapabilityReport,
+    CapabilitySet,
+    CheckResult,
+    EnvironmentBuilder,
+    ValidationResult,
+    get_builder,
+)
+from .canonical import canonical_digest, canonical_json
+from .contract import (
+    CONTRACT_V1,
+    SANDBOX_CONTRACT_V1,
+    SUPPORTED_CONTRACTS,
+    SandboxContract,
+    check_dockerfile,
+    validate_dockerfile,
+)
+from .errors import ERROR_CODES, EnvironmentsError, ErrorCode, map_provider_error
+from .lifecycle import VersionState, build_outcome, can_transition, transition
+from .resolve import (
+    LOCK_FORMAT,
+    BuildkitResolveRunner,
+    LocalResolveRunner,
+    ResolveRunner,
+    locked_versions,
+    merge_requirements,
+    parse_resolver_failure,
+    protected_pins,
+    resolve_environment,
+)
+from .spec import (
+    API_VERSION,
+    VARIANTS,
+    Environment,
+    EnvironmentSpec,
+    parse_environment,
+    spec_digest,
+    spec_findings,
+    validate_environment,
+)
+
+__all__ = [
+    "API_VERSION",
+    "APPROVED_BASES",
+    "CONTRACT_V1",
+    "ERROR_CODES",
+    "LOCK_FORMAT",
+    "SANDBOX_CONTRACT_V1",
+    "SUPPORTED_CONTRACTS",
+    "VARIANTS",
+    "ApprovedBase",
+    "ArtifactReference",
+    "BuildkitResolveRunner",
+    "BuildRequest",
+    "CapabilityReport",
+    "CapabilitySet",
+    "CheckResult",
+    "Environment",
+    "EnvironmentBuilder",
+    "EnvironmentSpec",
+    "EnvironmentsError",
+    "ErrorCode",
+    "LocalResolveRunner",
+    "ResolveRunner",
+    "SandboxContract",
+    "ValidationResult",
+    "VersionState",
+    "build_outcome",
+    "can_transition",
+    "canonical_digest",
+    "canonical_json",
+    "check_dockerfile",
+    "get_builder",
+    "locked_versions",
+    "merge_requirements",
+    "map_provider_error",
+    "parse_environment",
+    "parse_resolver_failure",
+    "protected_pins",
+    "resolve_environment",
+    "spec_digest",
+    "spec_findings",
+    "transition",
+    "validate_dockerfile",
+    "validate_environment",
+]

code_sandboxes-1.7.0/code_sandboxes/environments/__main__.py

@@ -0,0 +1,31 @@
+# Copyright (c) 2025-2026 Datalayer, Inc.
+#
+# BSD 3-Clause License
+
+"""Generate what is generated from the Environment models.
+
+python -m code_sandboxes.environments schema --write [PATH]
+python -m code_sandboxes.environments schema --check [PATH]
+python -m code_sandboxes.environments contract --markdown docs/docs/environments/contract.mdx
+python -m code_sandboxes.environments contract --check docs/docs/environments/contract.mdx
+"""
+
+from __future__ import annotations
+
+import sys
+
+from . import contract, schema
+
+_COMMANDS = {"schema": schema.main, "contract": contract.main}
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    if not arguments or arguments[0] not in _COMMANDS:
+        print(__doc__.strip(), file=sys.stderr)  # noqa: T201 - a command's own output
+        return 2
+    return _COMMANDS[arguments[0]](arguments[1:])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

code_sandboxes-1.7.0/code_sandboxes/environments/adapters/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) 2025-2026 Datalayer, Inc.
+#
+# BSD 3-Clause License
+
+"""The provider-specific Environment builders, one module per variant.
+
+Not neutral: each module speaks its provider's SDK. They are loaded only by
+:func:`code_sandboxes.environments.builders.get_builder`, and only where the
+build runs — the durable worker — never by a service that merely describes
+or launches an Environment.
+"""