modal 1.4.1.dev1__tar.gz → 1.4.1.dev3__tar.gz

{modal-1.4.1.dev1 → modal-1.4.1.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modal
-Version: 1.4.1.dev1
+Version: 1.4.1.dev3
 Summary: Python client library for Modal
 Author-email: Modal Labs <support@modal.com>
 License-Expression: Apache-2.0

{modal-1.4.1.dev1 → modal-1.4.1.dev3}/modal/__init__.py

@@ -38,7 +38,7 @@ try:
     from .proxy import Proxy
     from .queue import Queue
     from .retries import Retries
-    from .sandbox import Sandbox
+    from .sandbox import Probe, Sandbox
     from .schedule import Cron, Period
     from .scheduler_placement import SchedulerPlacement
     from .secret import Secret
@@ -68,6 +68,7 @@ __all__ = [
     "Image",
     "NetworkFileSystem",
     "Period",
+    "Probe",
     "Proxy",
     "Queue",
     "Retries",

{modal-1.4.1.dev1 → modal-1.4.1.dev3}/modal/_utils/sandbox_fs_utils.py

@@ -28,6 +28,7 @@ _EXEC_SANDBOX_UNAVAILABLE_ERROR_TYPES = (NotFoundError, ServiceError, Connection
 class ErrorPayload:
     error_kind: str
     message: str
+    detail: str = ""
 
 
 def _stderr_to_text(stderr: Union[str, bytes]) -> str:
@@ -51,11 +52,18 @@ def try_parse_error_payload(stderr: Union[str, bytes]) -> Optional[ErrorPayload]
         return None
     if not isinstance(message, str) or not message.strip():
         return None
-    return ErrorPayload(error_kind=error_kind, message=message)
+    detail = payload.get("detail", "")
+    if not isinstance(detail, str):
+        detail = ""
+    return ErrorPayload(error_kind=error_kind, message=message, detail=detail)
 
 
 def raise_read_file_error(returncode: int, stderr: Union[str, bytes], remote_path: str) -> NoReturn:
     if payload := try_parse_error_payload(stderr):
+        logger.debug(
+            f"sandbox-fs-tools read error: path={remote_path}, "
+            f"error_kind={payload.error_kind}, message={payload.message}, detail={payload.detail}"
+        )
         if payload.error_kind == "NotFound":
             raise SandboxFilesystemNotFoundError(f"{payload.message}: {remote_path}")
         if payload.error_kind == "IsDirectory":
@@ -106,6 +114,10 @@ def translate_exec_unexpected_error(operation: str, path: str, exc: Exception) -
 
 def raise_write_file_error(returncode: int, stderr: Union[str, bytes], remote_path: str) -> NoReturn:
     if payload := try_parse_error_payload(stderr):
+        logger.debug(
+            f"sandbox-fs-tools write error: path={remote_path}, "
+            f"error_kind={payload.error_kind}, message={payload.message}, detail={payload.detail}"
+        )
         if payload.error_kind == "NotDirectory" or payload.error_kind == "AlreadyExists":
             raise SandboxFilesystemNotADirectoryError(f"{payload.message}: {remote_path}")
         if payload.error_kind == "IsDirectory":

{modal-1.4.1.dev1 → modal-1.4.1.dev3}/modal/cli/run.py

@@ -7,7 +7,7 @@ import sys
 import time
 import typing
 from dataclasses import dataclass
-from typing import Any, Callable, Optional
+from typing import Any, Callable, Optional, get_args
 
 import click
 import typer
@@ -504,7 +504,9 @@ def deploy(
         False, "-m", help="Interpret argument as a Python module path instead of a file/script path"
     ),
     timestamps: bool = typer.Option(False, "--timestamps", help="Show timestamps for each log line."),
-    strategy: DEPLOYMENT_STRATEGY_TYPE = typer.Option("rolling", help="Deployment strategy"),
+    strategy: str = typer.Option(
+        "rolling", help="Deployment strategy", click_type=click.Choice(get_args(DEPLOYMENT_STRATEGY_TYPE))
+    ),
 ):
     """Deploy a Modal application.
 

{modal-1.4.1.dev1 → modal-1.4.1.dev3}/modal/client.py

@@ -22,7 +22,7 @@ from ._utils import async_utils
 from ._utils.async_utils import TaskContext, synchronize_api
 from ._utils.auth_token_manager import _AuthTokenManager
 from ._utils.grpc_utils import ConnectionManager
-from .config import _check_config, _is_remote, config, logger
+from .config import _agent_environment, _check_config, _is_remote, config, logger
 from .exception import AuthError, ClientClosed
 
 HEARTBEAT_INTERVAL: float = config.get("heartbeat_interval")
@@ -56,6 +56,9 @@ def _get_metadata(client_type: int, credentials: Optional[tuple[str, str]], vers
                 "x-modal-token-secret": token_secret,
             }
         )
+    agent_env = _agent_environment()
+    if agent_env:
+        metadata["x-modal-agent-harness"] = urllib.parse.quote(agent_env)
     return metadata
 
 

{modal-1.4.1.dev1 → modal-1.4.1.dev3}/modal/client.pyi

@@ -35,7 +35,7 @@ class _Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.4.1.dev1",
+        version: str = "1.4.1.dev3",
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.
@@ -171,7 +171,7 @@ class Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.4.1.dev1",
+        version: str = "1.4.1.dev3",
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.

{modal-1.4.1.dev1 → modal-1.4.1.dev3}/modal/config.py

@@ -121,6 +121,36 @@ def _is_remote() -> bool:
     return os.environ.get("MODAL_IS_REMOTE") == "1"
 
 
+def _agent_environment() -> Optional[str]:
+    """Detect if the current process is running inside an AI agent harness.
+
+    Returns the agent name if detected, or None otherwise.
+
+    Checks the emerging `AGENT` standard variable first, then falls back to
+    tool-specific environment variables used by known agent harnesses.
+    """
+    # Emerging standard: AGENT=<name>
+    if agent := os.environ.get("AGENT"):
+        return agent
+
+    # Tool-specific environment variables
+    _TOOL_SPECIFIC_ENV_VARS: list[tuple[str, str]] = [
+        ("CLAUDECODE", "claude-code"),
+        ("GEMINI_CLI", "gemini-cli"),
+        ("CURSOR_AGENT", "cursor"),
+        ("CLINE_ACTIVE", "cline"),
+        ("AUGMENT_AGENT", "augment"),
+        ("OPENCODE_CLIENT", "opencode"),
+        ("GOOSE_TERMINAL", "goose"),
+        ("TRAE_AI_SHELL_ID", "trae"),
+    ]
+    for env_var, agent_name in _TOOL_SPECIFIC_ENV_VARS:
+        if os.environ.get(env_var):
+            return agent_name
+
+    return None
+
+
 def _read_user_config():
     config_data = {}
     if not _is_remote() and os.path.exists(user_config_path):

{modal-1.4.1.dev1 → modal-1.4.1.dev3}/modal/functions.pyi

@@ -348,7 +348,7 @@ class Function(
 
     _call_generator: ___call_generator_spec
 
-    class __remote_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
+    class __remote_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> ReturnType_INNER:
             """Calls the function remotely, executing it with the given arguments and returning the execution's result."""
             ...
@@ -357,7 +357,7 @@ class Function(
             """Calls the function remotely, executing it with the given arguments and returning the execution's result."""
             ...
 
-    remote: __remote_spec[modal._functions.P, modal._functions.ReturnType]
+    remote: __remote_spec[modal._functions.ReturnType, modal._functions.P]
 
     class __remote_gen_spec(typing_extensions.Protocol):
         def __call__(self, /, *args, **kwargs) -> typing.Generator[typing.Any, None, None]:
@@ -384,7 +384,7 @@ class Function(
         """
         ...
 
-    class ___experimental_spawn_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
+    class ___experimental_spawn_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> FunctionCall[ReturnType_INNER]:
             """[Experimental] Calls the function with the given arguments, without waiting for the results.
 
@@ -407,7 +407,7 @@ class Function(
             """
             ...
 
-    _experimental_spawn: ___experimental_spawn_spec[modal._functions.P, modal._functions.ReturnType]
+    _experimental_spawn: ___experimental_spawn_spec[modal._functions.ReturnType, modal._functions.P]
 
     class ___spawn_map_inner_spec(typing_extensions.Protocol[P_INNER]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> None: ...
@@ -415,7 +415,7 @@ class Function(
 
     _spawn_map_inner: ___spawn_map_inner_spec[modal._functions.P]
 
-    class __spawn_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
+    class __spawn_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> FunctionCall[ReturnType_INNER]:
             """Calls the function with the given arguments, without waiting for the results.
 
@@ -436,7 +436,7 @@ class Function(
             """
             ...
 
-    spawn: __spawn_spec[modal._functions.P, modal._functions.ReturnType]
+    spawn: __spawn_spec[modal._functions.ReturnType, modal._functions.P]
 
     def get_raw_f(self) -> collections.abc.Callable[..., typing.Any]:
         """Return the inner Python object wrapped by this Modal Function."""

{modal-1.4.1.dev1 → modal-1.4.1.dev3}/modal/sandbox.py

@@ -42,6 +42,7 @@ from .exception import (
     InvalidError,
     SandboxTerminatedError,
     SandboxTimeoutError,
+    TimeoutError,
 )
 from .file_io import FileWatchEvent, FileWatchEventType, _FileIO, ls, mkdir, rm, watch
 from .image import _Image
@@ -118,6 +119,73 @@ class SandboxConnectCredentials:
     token: str
 
 
+@dataclass(frozen=True)
+class Probe:
+    """Probe configuration for the Sandbox Readiness Probe.
+
+    Usage:
+        ```py notest
+        # Wait until a file exists.
+        readiness_probe = modal.Probe.with_exec(
+            "sh", "-c", "test -f /tmp/ready",
+        )
+
+        # Wait until a TCP port is accepting connections.
+        readiness_probe = modal.Probe.with_tcp(8080)
+
+        app = modal.App.lookup('sandbox-readiness-probe', create_if_missing=True)
+        sandbox = modal.Sandbox.create(
+            "python3", "-m", "http.server", "8080",
+            readiness_probe=readiness_probe,
+            app=app,
+        )
+        sandbox.wait_until_ready()
+        ```
+    """
+
+    tcp_port: Optional[int] = None
+    exec_argv: Optional[tuple[str, ...]] = None
+    interval_ms: int = 100
+
+    def __post_init__(self):
+        if (self.tcp_port is None) == (self.exec_argv is None):
+            raise InvalidError("Probe must be created with Probe.with_tcp(...) or Probe.with_exec(...)")
+
+    @classmethod
+    def with_tcp(cls, port: int, *, interval_ms: int = 100) -> "Probe":
+        if not isinstance(port, int):
+            raise InvalidError("Probe.with_tcp() expects an integer `port`")
+        if port <= 0 or port > 65535:
+            raise InvalidError(f"Probe.with_tcp() expects `port` in [1, 65535], got {port}")
+        if not isinstance(interval_ms, int):
+            raise InvalidError("Probe.with_tcp() expects an integer `interval_ms`")
+        if interval_ms <= 0:
+            raise InvalidError(f"Probe.with_tcp() expects `interval_ms` > 0, got {interval_ms}")
+        return cls(tcp_port=port, interval_ms=interval_ms)
+
+    @classmethod
+    def with_exec(cls, *argv: str, interval_ms: int = 100) -> "Probe":
+        if len(argv) == 0:
+            raise InvalidError("Probe.with_exec() requires at least one argument")
+        if not all(isinstance(arg, str) for arg in argv):
+            raise InvalidError("Probe.with_exec() expects all arguments to be strings")
+        if not isinstance(interval_ms, int):
+            raise InvalidError("Probe.with_exec() expects an integer `interval_ms`")
+        if interval_ms <= 0:
+            raise InvalidError(f"Probe.with_exec() expects `interval_ms` > 0, got {interval_ms}")
+        return cls(exec_argv=tuple(argv), interval_ms=interval_ms)
+
+    def _to_proto(self) -> api_pb2.Probe:
+        if self.tcp_port is not None:
+            return api_pb2.Probe(tcp_port=self.tcp_port, interval_ms=self.interval_ms)
+        if self.exec_argv is not None:
+            return api_pb2.Probe(
+                exec_command=api_pb2.Probe.ExecCommand(argv=list(self.exec_argv)),
+                interval_ms=self.interval_ms,
+            )
+        raise InvalidError("Probe must be created with Probe.with_tcp(...) or Probe.with_exec(...)")
+
+
 class _Sandbox(_Object, type_prefix="sb"):
     """A `Sandbox` object lets you interact with a running sandbox. This API is similar to Python's
     [asyncio.subprocess.Process](https://docs.python.org/3/library/asyncio-subprocess.html#asyncio.subprocess.Process).
@@ -166,6 +234,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         h2_ports: Sequence[int] = [],
         unencrypted_ports: Sequence[int] = [],
         proxy: Optional[_Proxy] = None,
+        readiness_probe: Optional[Probe] = None,
         experimental_options: Optional[dict[str, bool]] = None,
         enable_snapshot: bool = False,
         verbose: bool = False,
@@ -279,6 +348,7 @@ class _Sandbox(_Object, type_prefix="sb"):
                 open_ports=api_pb2.PortSpecs(ports=open_ports),
                 network_access=network_access,
                 proxy_id=(proxy.object_id if proxy else None),
+                readiness_probe=(readiness_probe._to_proto() if readiness_probe else None),
                 enable_snapshot=enable_snapshot,
                 verbose=verbose,
                 name=name,
@@ -339,6 +409,8 @@ class _Sandbox(_Object, type_prefix="sb"):
         proxy: Optional[_Proxy] = None,
         # If True, the sandbox will receive a MODAL_IDENTITY_TOKEN env var for OIDC-based auth.
         include_oidc_identity_token: bool = False,
+        # Probe used to determine when the sandbox has become ready.
+        readiness_probe: Optional[Probe] = None,
         # Enable verbose logging for sandbox operations.
         verbose: bool = False,
         experimental_options: Optional[dict[str, bool]] = None,
@@ -403,6 +475,7 @@ class _Sandbox(_Object, type_prefix="sb"):
             h2_ports=h2_ports,
             unencrypted_ports=unencrypted_ports,
             proxy=proxy,
+            readiness_probe=readiness_probe,
             experimental_options=experimental_options,
             _experimental_enable_snapshot=_experimental_enable_snapshot,
             include_oidc_identity_token=include_oidc_identity_token,
@@ -439,6 +512,7 @@ class _Sandbox(_Object, type_prefix="sb"):
         unencrypted_ports: Sequence[int] = [],
         proxy: Optional[_Proxy] = None,
         include_oidc_identity_token: bool = False,
+        readiness_probe: Optional[Probe] = None,
         experimental_options: Optional[dict[str, bool]] = None,
         _experimental_enable_snapshot: bool = False,
         client: Optional[_Client] = None,
@@ -490,6 +564,7 @@ class _Sandbox(_Object, type_prefix="sb"):
             h2_ports=h2_ports,
             unencrypted_ports=unencrypted_ports,
             proxy=proxy,
+            readiness_probe=readiness_probe,
             experimental_options=experimental_options,
             enable_snapshot=_experimental_enable_snapshot,
             verbose=verbose,
@@ -958,6 +1033,39 @@ class _Sandbox(_Object, type_prefix="sb"):
                     raise SandboxTerminatedError()
                 break
 
+    async def wait_until_ready(self, *, timeout: int = 300) -> None:
+        """Wait for the Sandbox readiness probe to report that the Sandbox is ready.
+
+        The Sandbox must be configured with a `readiness_probe` in order to use this method.
+
+        Usage:
+        ```py notest
+        app = modal.App.lookup('sandbox-wait-until-ready', create_if_missing=True)
+        sandbox = modal.Sandbox.create(
+            "python3", "-m", "http.server", "8080",
+            readiness_probe=modal.Probe.with_tcp(8080),
+            app=app,
+        )
+        sandbox.wait_until_ready()
+        ```
+        """
+        if timeout <= 0:
+            raise InvalidError(f"`timeout` must be positive, got: {timeout}")
+
+        deadline = time.monotonic() + timeout
+        remaining_timeout = deadline - time.monotonic()
+        while remaining_timeout > 0:
+            req = api_pb2.SandboxWaitUntilReadyRequest(
+                sandbox_id=self.object_id,
+                timeout=min(remaining_timeout, 50.0),
+            )
+            resp = await self._client.stub.SandboxWaitUntilReady(req)
+            if resp.ready_at > 0:
+                return
+
+            remaining_timeout = deadline - time.monotonic()
+        raise TimeoutError()
+
     async def tunnels(self, timeout: int = 50) -> dict[int, Tunnel]:
         """Get Tunnel metadata for the sandbox.
 

{modal-1.4.1.dev1 → modal-1.4.1.dev3}/modal/sandbox.pyi

@@ -71,6 +71,68 @@ class SandboxConnectCredentials:
         """Return hash(self)."""
         ...
 
+class Probe:
+    """Probe configuration for the Sandbox Readiness Probe.
+
+    Usage:
+        ```py notest
+        # Wait until a file exists.
+        readiness_probe = modal.Probe.with_exec(
+            "sh", "-c", "test -f /tmp/ready",
+        )
+
+        # Wait until a TCP port is accepting connections.
+        readiness_probe = modal.Probe.with_tcp(8080)
+
+        app = modal.App.lookup('sandbox-readiness-probe', create_if_missing=True)
+        sandbox = modal.Sandbox.create(
+            "python3", "-m", "http.server", "8080",
+            readiness_probe=readiness_probe,
+            app=app,
+        )
+        sandbox.wait_until_ready()
+        ```
+    """
+
+    tcp_port: typing.Optional[int]
+    exec_argv: typing.Optional[tuple[str, ...]]
+    interval_ms: int
+
+    def __post_init__(self): ...
+    @classmethod
+    def with_tcp(cls, port: int, *, interval_ms: int = 100) -> Probe: ...
+    @classmethod
+    def with_exec(cls, *argv: str, interval_ms: int = 100) -> Probe: ...
+    def _to_proto(self) -> modal_proto.api_pb2.Probe: ...
+    def __init__(
+        self,
+        tcp_port: typing.Optional[int] = None,
+        exec_argv: typing.Optional[tuple[str, ...]] = None,
+        interval_ms: int = 100,
+    ) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    def __repr__(self):
+        """Return repr(self)."""
+        ...
+
+    def __eq__(self, other):
+        """Return self==value."""
+        ...
+
+    def __setattr__(self, name, value):
+        """Implement setattr(self, name, value)."""
+        ...
+
+    def __delattr__(self, name):
+        """Implement delattr(self, name)."""
+        ...
+
+    def __hash__(self):
+        """Return hash(self)."""
+        ...
+
 class _Sandbox(modal._object._Object):
     """A `Sandbox` object lets you interact with a running sandbox. This API is similar to Python's
     [asyncio.subprocess.Process](https://docs.python.org/3/library/asyncio-subprocess.html#asyncio.subprocess.Process).
@@ -120,6 +182,7 @@ class _Sandbox(modal._object._Object):
         h2_ports: collections.abc.Sequence[int] = [],
         unencrypted_ports: collections.abc.Sequence[int] = [],
         proxy: typing.Optional[modal.proxy._Proxy] = None,
+        readiness_probe: typing.Optional[Probe] = None,
         experimental_options: typing.Optional[dict[str, bool]] = None,
         enable_snapshot: bool = False,
         verbose: bool = False,
@@ -159,6 +222,7 @@ class _Sandbox(modal._object._Object):
         custom_domain: typing.Optional[str] = None,
         proxy: typing.Optional[modal.proxy._Proxy] = None,
         include_oidc_identity_token: bool = False,
+        readiness_probe: typing.Optional[Probe] = None,
         verbose: bool = False,
         experimental_options: typing.Optional[dict[str, bool]] = None,
         _experimental_enable_snapshot: bool = False,
@@ -211,6 +275,7 @@ class _Sandbox(modal._object._Object):
         unencrypted_ports: collections.abc.Sequence[int] = [],
         proxy: typing.Optional[modal.proxy._Proxy] = None,
         include_oidc_identity_token: bool = False,
+        readiness_probe: typing.Optional[Probe] = None,
         experimental_options: typing.Optional[dict[str, bool]] = None,
         _experimental_enable_snapshot: bool = False,
         client: typing.Optional[modal.client._Client] = None,
@@ -360,6 +425,24 @@ class _Sandbox(modal._object._Object):
         """Wait for the Sandbox to finish running."""
         ...
 
+    async def wait_until_ready(self, *, timeout: int = 300) -> None:
+        """Wait for the Sandbox readiness probe to report that the Sandbox is ready.
+
+        The Sandbox must be configured with a `readiness_probe` in order to use this method.
+
+        Usage:
+        ```py notest
+        app = modal.App.lookup('sandbox-wait-until-ready', create_if_missing=True)
+        sandbox = modal.Sandbox.create(
+            "python3", "-m", "http.server", "8080",
+            readiness_probe=modal.Probe.with_tcp(8080),
+            app=app,
+        )
+        sandbox.wait_until_ready()
+        ```
+        """
+        ...
+
     async def tunnels(self, timeout: int = 50) -> dict[int, modal._tunnel.Tunnel]:
         """Get Tunnel metadata for the sandbox.
 
@@ -843,6 +926,7 @@ class Sandbox(modal.object.Object):
         h2_ports: collections.abc.Sequence[int] = [],
         unencrypted_ports: collections.abc.Sequence[int] = [],
         proxy: typing.Optional[modal.proxy.Proxy] = None,
+        readiness_probe: typing.Optional[Probe] = None,
         experimental_options: typing.Optional[dict[str, bool]] = None,
         enable_snapshot: bool = False,
         verbose: bool = False,
@@ -886,6 +970,7 @@ class Sandbox(modal.object.Object):
             custom_domain: typing.Optional[str] = None,
             proxy: typing.Optional[modal.proxy.Proxy] = None,
             include_oidc_identity_token: bool = False,
+            readiness_probe: typing.Optional[Probe] = None,
             verbose: bool = False,
             experimental_options: typing.Optional[dict[str, bool]] = None,
             _experimental_enable_snapshot: bool = False,
@@ -941,6 +1026,7 @@ class Sandbox(modal.object.Object):
             custom_domain: typing.Optional[str] = None,
             proxy: typing.Optional[modal.proxy.Proxy] = None,
             include_oidc_identity_token: bool = False,
+            readiness_probe: typing.Optional[Probe] = None,
             verbose: bool = False,
             experimental_options: typing.Optional[dict[str, bool]] = None,
             _experimental_enable_snapshot: bool = False,
@@ -999,6 +1085,7 @@ class Sandbox(modal.object.Object):
             unencrypted_ports: collections.abc.Sequence[int] = [],
             proxy: typing.Optional[modal.proxy.Proxy] = None,
             include_oidc_identity_token: bool = False,
+            readiness_probe: typing.Optional[Probe] = None,
             experimental_options: typing.Optional[dict[str, bool]] = None,
             _experimental_enable_snapshot: bool = False,
             client: typing.Optional[modal.client.Client] = None,
@@ -1047,6 +1134,7 @@ class Sandbox(modal.object.Object):
             unencrypted_ports: collections.abc.Sequence[int] = [],
             proxy: typing.Optional[modal.proxy.Proxy] = None,
             include_oidc_identity_token: bool = False,
+            readiness_probe: typing.Optional[Probe] = None,
             experimental_options: typing.Optional[dict[str, bool]] = None,
             _experimental_enable_snapshot: bool = False,
             client: typing.Optional[modal.client.Client] = None,
@@ -1357,6 +1445,45 @@ class Sandbox(modal.object.Object):
 
     wait: __wait_spec
 
+    class __wait_until_ready_spec(typing_extensions.Protocol):
+        def __call__(self, /, *, timeout: int = 300) -> None:
+            """Wait for the Sandbox readiness probe to report that the Sandbox is ready.
+
+            The Sandbox must be configured with a `readiness_probe` in order to use this method.
+
+            Usage:
+            ```py notest
+            app = modal.App.lookup('sandbox-wait-until-ready', create_if_missing=True)
+            sandbox = modal.Sandbox.create(
+                "python3", "-m", "http.server", "8080",
+                readiness_probe=modal.Probe.with_tcp(8080),
+                app=app,
+            )
+            sandbox.wait_until_ready()
+            ```
+            """
+            ...
+
+        async def aio(self, /, *, timeout: int = 300) -> None:
+            """Wait for the Sandbox readiness probe to report that the Sandbox is ready.
+
+            The Sandbox must be configured with a `readiness_probe` in order to use this method.
+
+            Usage:
+            ```py notest
+            app = modal.App.lookup('sandbox-wait-until-ready', create_if_missing=True)
+            sandbox = modal.Sandbox.create(
+                "python3", "-m", "http.server", "8080",
+                readiness_probe=modal.Probe.with_tcp(8080),
+                app=app,
+            )
+            sandbox.wait_until_ready()
+            ```
+            """
+            ...
+
+    wait_until_ready: __wait_until_ready_spec
+
     class __tunnels_spec(typing_extensions.Protocol):
         def __call__(self, /, timeout: int = 50) -> dict[int, modal._tunnel.Tunnel]:
             """Get Tunnel metadata for the sandbox.

{modal-1.4.1.dev1 → modal-1.4.1.dev3}/modal.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modal
-Version: 1.4.1.dev1
+Version: 1.4.1.dev3
 Summary: Python client library for Modal
 Author-email: Modal Labs <support@modal.com>
 License-Expression: Apache-2.0

{modal-1.4.1.dev1 → modal-1.4.1.dev3}/modal_version/__init__.py

@@ -1,4 +1,4 @@
 # Copyright Modal Labs 2026
 """Supplies the current version of the modal client library."""
 
-__version__ = "1.4.1.dev1"
+__version__ = "1.4.1.dev3"