snowflake-sandbox-python 0.2.1a1__py3-none-any.whl

snowflake/sandbox/jobs.py

@@ -0,0 +1,649 @@
+"""Detached run engine — the machinery behind ``AsyncSandbox.create(command=…)`` +
+``wait`` and ``Function.spawn``.
+
+Spawn a detached sandbox, get a handle back immediately, and check in over time
+(``status`` / ``get``) or be told the result by webhook. It mirrors Modal's
+``FunctionCall`` surface (``spawn`` → id → ``from_id`` / ``get`` / ``cancel``).
+
+Stage-free: no durable store, no stage, no in-sandbox Snowflake write.
+``job_id == container_id``; status comes from the live container registry
+(``get_sandbox``) and the result from the **stdout sentinel**
+``__SANDBOX_RESULT__<base64(json)>`` read via ``logs``. An injected
+``_sandbox_job_runner.sh`` runs the manifest's original ``[build].entry`` as a
+subprocess, captures its exit code + ``$SANDBOX_RESULT`` artifact, prints the
+sentinel, and (if a webhook is set) POSTs the same payload — best-effort, no
+Snowflake creds.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import binascii
+import json
+import shutil
+import tempfile
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Self, cast
+
+if TYPE_CHECKING:
+    from snowflake.sandbox.config import ConnectionLike
+    from snowflake.sandbox.image import Image
+    from snowflake.sandbox.types import JobStatus, MemoryTier, RunStatus
+
+from snowflake.sandbox._assemble import (
+    _DEFAULT_EXCLUDES,
+    _assemble_bundle,
+    _bundle_files,
+    _clone_git_ref,
+    _copy_tree_into,
+)
+from snowflake.sandbox._deploy_spec import DeploySpec
+from snowflake.sandbox._diagnostics import preflight_checks
+from snowflake.sandbox._runtime._job_runner import _SANDBOX_JOB_RUNNER
+from snowflake.sandbox._runtime._protocol import _RESULT_SENTINEL
+from snowflake.sandbox.client import AsyncSandbox, get_sandbox
+from snowflake.sandbox.deploy import DeployPlan
+from snowflake.sandbox.exceptions import SandboxError
+from snowflake.sandbox.sync_client import Sandbox
+from snowflake.sandbox.sync_client import get_sandbox as get_sandbox_sync
+from snowflake.sandbox.types import TERMINAL_STATUSES
+
+__all__ = ["Job", "RunResult", "SyncJob", "deploy_async", "deploy_async_sync"]
+
+# Name of the injected runner inside the bundle, and the effective container
+# entry that runs it. Unlike the ``exec`` path (which the backend runs with
+# cwd=<code dir>), a detached command-container's main process starts in /tmp,
+# NOT the code-extraction dir — so a bare relative ``_sandbox_job_runner.sh``
+# is not found. The entry therefore cds into the extracted bundle first. The
+# server prepends the code dir to PYTHONPATH, so the runner is located by
+# taking PYTHONPATH's first entry (falling back to the known /tmp/_sandbox_code
+# extraction dir) before exec'ing the runner.
+_RUNNER_FILENAME = "_sandbox_job_runner.sh"
+_RUNNER_ENTRY = [
+    "/bin/bash",
+    "-c",
+    'cd "${PYTHONPATH%%:*}" 2>/dev/null || cd /tmp/_sandbox_code 2>/dev/null; '
+    "exec /bin/bash " + _RUNNER_FILENAME,
+]
+
+
+@dataclass
+class RunResult:
+    """The outcome of a detached run (``spawn`` + ``wait``).
+
+    ``status`` is one of ``succeeded`` | ``failed`` | ``timed_out`` (the
+    terminal lifecycle states a ``get`` can resolve to). ``exit_code`` is the
+    inner entry's exit code (``None`` if the container exited without a
+    sentinel and no code is known, or if it timed out before completing).
+    ``result`` is the parsed ``$SANDBOX_RESULT`` artifact (or ``{"exit_code":
+    N}`` when absent), or ``None`` if no sentinel was seen. ``logs_ref`` is the
+    container id — where the logs are read from."""
+
+    status: RunStatus
+    exit_code: int | None
+    result: dict[str, Any] | None
+    logs_ref: str | None
+
+
+def _parse_result_sentinel(log_text: str, *, nonce: str | None = None) -> RunResult | None:
+    """Scan *log_text* for the LAST ``__SANDBOX_RESULT__<b64>`` line and decode
+    it into a `RunResult`. Pure + unit-testable.
+
+    Returns ``None`` if no well-formed sentinel line is present (a malformed
+    base64/json payload is skipped, not raised, so a partial log line never
+    masks an earlier good one).
+
+    When *nonce* is given, only a sentinel whose payload carries that exact
+    ``nonce`` is accepted — this is the authentication filter. The nonce is minted
+    per run by the wrapper and never handed to the inner command, so a line the
+    (untrusted) workload prints on its own stdout cannot carry it.
+
+    ``nonce=None`` decodes any well-formed sentinel WITHOUT authenticating it; it
+    is for pure decoding only. Callers that need the result to be trustworthy —
+    `AsyncSandbox.wait`, `Job.get`, `Job.status` — pass the run nonce, and when they
+    hold no nonce (a `connect()` / `from_id()` reconnect) they do NOT call this
+    with ``nonce=None`` and trust the outcome; they fall back to the
+    server-reported exit code. So a workload can no longer report
+    ``succeeded`` for a run that failed just by printing ``__SANDBOX_RESULT__``.
+    """
+    found: RunResult | None = None
+    for line in log_text.splitlines():
+        idx = line.find(_RESULT_SENTINEL)
+        if idx == -1:
+            continue
+        b64 = line[idx + len(_RESULT_SENTINEL) :].strip()
+        if not b64:
+            continue
+        try:
+            decoded = base64.b64decode(b64, validate=True)
+            core = json.loads(decoded)
+        except (binascii.Error, ValueError, UnicodeDecodeError):
+            continue
+        if not isinstance(core, dict):
+            continue
+        if nonce is not None and core.get("nonce") != nonce:
+            continue
+        raw_status = core.get("status")
+        exit_code = core.get("exit_code")
+        result = core.get("result")
+        # Clamp an unknown/malformed wire status to `failed` rather than letting an
+        # arbitrary string through the typed RunStatus field.
+        status: RunStatus = (
+            raw_status if raw_status in ("succeeded", "failed", "timed_out") else "failed"
+        )
+        found = RunResult(
+            status=status,
+            exit_code=exit_code if isinstance(exit_code, int) else None,
+            result=result if isinstance(result, dict) else None,
+            logs_ref=None,
+        )
+    return found
+
+
+class _JobHandle:
+    """Shared, I/O-free handle state for `Job` and `SyncJob`.
+
+    ``job_id == container_id``. Holds the id and the per-run ``nonce`` (the token
+    `deploy_async` / `deploy_async_sync` gave the injected runner) and the
+    ``from_id`` rehydrator, so the async and sync handles cannot drift on how a
+    handle is constructed or authenticated. When ``nonce`` is set, only a result
+    sentinel carrying it is accepted, so a line the workload prints on its own
+    stdout cannot pass as the run's outcome; a handle rehydrated with `from_id()`
+    has no nonce (it lives only in the spawning process) and keeps the
+    unauthenticated read.
+    """
+
+    def __init__(
+        self,
+        id: str,
+        *,
+        nonce: str | None = None,
+        name: str | None = None,
+        connection: ConnectionLike | None = None,
+    ) -> None:
+        self.id = id
+        self.nonce = nonce
+        # The sandbox's vanity name — the user-facing identity. Set when the handle
+        # is minted by deploy_async[_sync]; a from_id() rehydrate has no name.
+        self.name = name
+        # The Snowflake connection this handle reads its container over. Carried on the
+        # handle because every method re-fetches the container by id (``get_sandbox``),
+        # and a handle rehydrated in a new process has no ambient connection to inherit:
+        # without this, ``Job.from_id(id, connection="prod")`` had no way to say which
+        # account the job lives in.
+        self._connection = connection
+
+    @classmethod
+    def from_id(cls, job_id: str, *, connection: ConnectionLike | None = None) -> Self:
+        """Rehydrate a handle from a job id (= container id).
+
+        ``connection`` names the Snowflake connection the job lives in — a name from
+        ``~/.snowflake/connections.toml``, a live connector connection, or a `Config`.
+        Omit it to use the enclosing ``using()`` block, else the default connection.
+        """
+        return cls(job_id, connection=connection)
+
+
+class Job(_JobHandle):
+    """A handle to a detached run (async API).
+
+    Construct via `deploy_async()` (which spawns the detached sandbox) or
+    `from_id()` to rehydrate later (the "check in over time" path). For a
+    blocking caller with no event loop, `SyncJob` is the exact synchronous
+    counterpart — same methods, same authentication rule, no ``await``.
+    """
+
+    async def status(self) -> JobStatus:
+        """Derive the lifecycle status from the container + logs sentinel.
+
+        ``succeeded``/``failed`` when a **trusted** sentinel is present (per its
+        parsed status); ``failed`` if the container is terminal (``dead`` or ``failed``) with no
+        trusted sentinel; otherwise ``running``. ``cancelled`` is observed only via
+        `cancel()` (which destroys the container); ``timed_out`` is a
+        `get()` outcome, not a container state.
+
+        A handle rehydrated with `from_id()` has no nonce, so the stdout
+        sentinel is not authenticated — status is derived from the container's own
+        terminal state and server-reported exit code, never a forgeable line."""
+        sb = await get_sandbox(self.id, connection=self._connection)
+        if self.nonce is not None:
+            parsed = _parse_result_sentinel(await sb.logs(), nonce=self.nonce)
+            if parsed is not None:
+                # A trusted sentinel reports succeeded/failed; status() is a live
+                # lifecycle verdict where timed_out is not a member, so fold it in.
+                return "failed" if parsed.status == "timed_out" else parsed.status
+        if sb.status in TERMINAL_STATUSES:
+            # No trusted sentinel: read the server-reported exit code where the
+            # backend exposes it, else fall back to the conservative "failed".
+            await sb._probe_managed_exit_code()
+            return "succeeded" if sb._exit_code == 0 else "failed"
+        return "running"
+
+    async def get(self, timeout: float | None = None, poll_s: float = 3.0) -> RunResult:
+        """Poll for the Job's result.
+
+        Fetches ``get_sandbox(id).logs()`` and scans for the LAST sentinel;
+        returns the decoded `RunResult` as soon as one appears. If the
+        container reaches a terminal state (``dead`` or ``failed``) with no sentinel, returns
+        ``RunResult(status="failed", ...)``. On *timeout* (when set) before
+        either condition, returns ``RunResult(status="timed_out", ...)`` rather
+        than raising — ``get`` is the poll-with-deadline contract and
+        ``timed_out`` is a defined lifecycle status."""
+        deadline = (time.monotonic() + timeout) if timeout is not None else None
+        while True:
+            sb = await get_sandbox(self.id, connection=self._connection)
+            # Only trust the stdout sentinel when we hold the run's nonce;
+            # a from_id() handle has none, so fall through to the server state.
+            if self.nonce is not None:
+                parsed = _parse_result_sentinel(await sb.logs(), nonce=self.nonce)
+                if parsed is not None:
+                    parsed.logs_ref = self.id
+                    return parsed
+            if sb.status in TERMINAL_STATUSES:
+                # No trusted sentinel: report the server-reported exit code where
+                # available rather than an unauthenticated stdout line.
+                await sb._probe_managed_exit_code()
+                ec = sb._exit_code
+                status: RunStatus = "succeeded" if ec == 0 else "failed"
+                return RunResult(status=status, exit_code=ec, result=None, logs_ref=self.id)
+            if deadline is not None and time.monotonic() + poll_s >= deadline:
+                return RunResult(status="timed_out", exit_code=None, result=None, logs_ref=self.id)
+            await asyncio.sleep(poll_s)
+
+    async def logs(self, tail: int = 0) -> str:
+        """Return the container's captured logs (Layer-0 byte view)."""
+        sb = await get_sandbox(self.id, connection=self._connection)
+        return await sb.logs(tail=tail)
+
+    async def cancel(self) -> None:
+        """Cancel the Job by destroying its container (lands ``cancelled``)."""
+        sb = await get_sandbox(self.id, connection=self._connection)
+        await sb.destroy()
+
+
+class SyncJob(_JobHandle):
+    """A handle to a detached run (sync API) — the blocking counterpart of `Job`.
+
+    Same four operations as `Job` with identical names and semantics; it reads
+    the container through the synchronous `get_sandbox` and blocks on
+    `time.sleep` instead of awaiting. It shares the authoritative result decode
+    (`_parse_result_sentinel`) and the nonce authentication rule with `Job`
+    rather than re-deriving them, so a sync caller and an async caller resolve the
+    same job to the same status/result. It runs with no event loop, so a notebook
+    cell or a plain script can poll a job without spinning one up. Construct via
+    `deploy_async_sync()` or `SyncJob.from_id()`.
+    """
+
+    def status(self) -> JobStatus:
+        """Derive the lifecycle status from the container + logs sentinel.
+
+        Same verdict as `Job.status`: a trusted sentinel wins (per its parsed
+        status), else a terminal (``dead``/``failed``) container maps its server-reported
+        exit code, else ``running``. A `from_id()` handle holds no nonce, so the
+        stdout sentinel is not authenticated and the status comes from the
+        container's own terminal state."""
+        sb = get_sandbox_sync(self.id, connection=self._connection)
+        if self.nonce is not None:
+            parsed = _parse_result_sentinel(sb.logs(), nonce=self.nonce)
+            if parsed is not None:
+                # See Job.status: fold the non-live timed_out into failed.
+                return "failed" if parsed.status == "timed_out" else parsed.status
+        if sb.status in TERMINAL_STATUSES:
+            sb._probe_managed_exit_code()
+            return "succeeded" if sb._exit_code == 0 else "failed"
+        return "running"
+
+    def get(self, timeout: float | None = None, poll_s: float = 3.0) -> RunResult:
+        """Poll for the Job's result (blocking).
+
+        Same contract as `Job.get`: the last trusted sentinel wins; a terminal
+        container with no trusted sentinel reports its server-reported exit code;
+        a deadline hit first returns ``RunResult(status="timed_out", ...)`` rather
+        than raising. Blocks on `time.sleep` between polls instead of awaiting."""
+        deadline = (time.monotonic() + timeout) if timeout is not None else None
+        while True:
+            sb = get_sandbox_sync(self.id, connection=self._connection)
+            if self.nonce is not None:
+                parsed = _parse_result_sentinel(sb.logs(), nonce=self.nonce)
+                if parsed is not None:
+                    parsed.logs_ref = self.id
+                    return parsed
+            if sb.status in TERMINAL_STATUSES:
+                sb._probe_managed_exit_code()
+                ec = sb._exit_code
+                status: RunStatus = "succeeded" if ec == 0 else "failed"
+                return RunResult(status=status, exit_code=ec, result=None, logs_ref=self.id)
+            if deadline is not None and time.monotonic() + poll_s >= deadline:
+                return RunResult(status="timed_out", exit_code=None, result=None, logs_ref=self.id)
+            time.sleep(poll_s)
+
+    def logs(self, tail: int = 0) -> str:
+        """Return the container's captured logs (Layer-0 byte view).
+
+        A snapshot string, not a stream — `Job.logs` returns the whole captured
+        log text, so its sync twin does too. (Line-by-line following is
+        `Sandbox.stdout` / `SyncLogStream`, not this.)"""
+        sb = get_sandbox_sync(self.id, connection=self._connection)
+        return sb.logs(tail=tail)
+
+    def cancel(self) -> None:
+        """Cancel the Job by destroying its container (lands ``cancelled``)."""
+        sb = get_sandbox_sync(self.id, connection=self._connection)
+        sb.destroy()
+
+
+@dataclass
+class _JobPrep:
+    """The output of `_prepare_job` — the assembled, runner-injected bundle and
+    the create arguments a detached spawn needs, resolved before any container
+    I/O, plus the temp dirs the caller cleans up.
+
+    ``deploy_image`` is the layered `Image` (built by ``from_local``) when the
+    spec carries one, else the plan's base-name string. ``nonce`` is the per-run
+    token the runner echoes in its result sentinel; the returned `Job` carries it
+    so the result read is authenticated. Single-sourced so a detached spawn
+    launches the same container whether the caller went through `deploy_async`
+    or `deploy_async_sync`.
+    """
+
+    bundle_dir: Path
+    deploy_image: str | Image
+    job_env: dict[str, str]
+    platform_env: dict[str, str]
+    plan: DeployPlan
+    nonce: str
+    clone_root: Path | None
+
+
+def _prepare_job(
+    spec: DeploySpec,
+    *,
+    source_dir: str | Path | None,
+    run_preflight: bool,
+    git_repo: str | None,
+    git_ref: str | None,
+    git_subdir: str | None,
+    webhook: str | None,
+    extra_platform_env: dict[str, str] | None = None,
+) -> _JobPrep:
+    """Assemble a detached-run bundle from a `DeploySpec` (no container I/O).
+
+    Shared by `deploy_async` and `deploy_async_sync`: source resolution,
+    preflight, bundle assembly, runner injection, the per-run nonce, the
+    ``SANDBOX_JOB_*`` platform-env, and the `DeployPlan` all live here so the two
+    calling styles spawn identical jobs. Only the container create/ensure differs
+    between them.
+
+    On any failure after a clone/assembly the temp trees are removed before the
+    error propagates, since the caller never receives the prep to clean up.
+    """
+    clone_root: Path | None = None
+    bundle_dir: Path | None = None
+
+    inner_entry = list(spec.entry)
+    if not inner_entry:
+        raise SandboxError("spec.entry is required for deploy_async")
+
+    if git_repo is not None:
+        clone_root, effective_src, _resolved_ref = _clone_git_ref(git_repo, git_ref, git_subdir)
+        base = Path(effective_src)
+    elif source_dir is not None:
+        base = Path(source_dir).expanduser().resolve()
+    elif spec.bundle is not None:
+        base = Path(spec.bundle.root).expanduser().resolve()
+    else:
+        raise SandboxError("deploy_async needs a bundle, a source_dir, or a git_repo")
+
+    try:
+        if not base.is_dir():
+            raise SandboxError(f"bundle root not found: {base}")
+
+        env = {k: str(v) for k, v in spec.env.items() if str(v) != ""}
+        egress_body = spec.egress_body()
+
+        if run_preflight:
+            problems = preflight_checks(spec, base)
+            errs = [p for p in problems if p.severity == "error"]
+            if errs:
+                raise SandboxError(
+                    "deploy_async preflight failed: "
+                    + "; ".join(f"{p.message} ({p.fix})" if p.fix else p.message for p in errs)
+                )
+
+        # Assemble the bundle. Include globs mean a monorepo slice; a bare exclude
+        # also forces assembly so excludes are honored; otherwise copy the project
+        # dir into a temp dir (so we never mutate the user's tree when injecting
+        # the runner).
+        if spec.bundle is not None and (spec.bundle.include or spec.bundle.exclude):
+            include_root = Path(spec.bundle.root).expanduser()
+            if not include_root.is_absolute():
+                include_root = (base / include_root).resolve()
+            bundle_dir = _assemble_bundle(
+                base,
+                {
+                    "root": str(include_root),
+                    "include": list(spec.bundle.include),
+                    "exclude": list(spec.bundle.exclude),
+                },
+            )
+        else:
+            bundle_dir = Path(tempfile.mkdtemp(prefix="sbx-job-bundle-"))
+            _copy_tree_into(base, bundle_dir, list(_DEFAULT_EXCLUDES))
+
+        # Inject the runner + the job env, and override the effective entry.
+        (bundle_dir / _RUNNER_FILENAME).write_text(_SANDBOX_JOB_RUNNER)
+        job_env = dict(env)  # user env only — stays on the `env` map
+        # Per-run token the runner echoes in its result sentinel and unsets
+        # before running the inner entry, so the workload cannot forge its own
+        # "succeeded". See _parse_result_sentinel for what this does and does not
+        # guarantee.
+        nonce = uuid.uuid4().hex
+        # The runner's control vars are server-reserved SANDBOX_ keys, so they ride
+        # the `sandbox_env` PLATFORM channel (from_local -> AsyncSandbox._add_platform_env),
+        # NOT the user `env` map: the create path rejects (400) a SANDBOX_ key on the
+        # env map, which used to break `Function.spawn` silently — the same failure
+        # the warm-session nonce hit before it moved to the platform channel.
+        # The runner reads them from its environment (the server merges sandbox_env
+        # into the app env) and unsets SANDBOX_JOB_NONCE before the inner entry runs.
+        platform_env: dict[str, str] = {
+            "SANDBOX_JOB_INNER_ENTRY": json.dumps(inner_entry),
+            "SANDBOX_JOB_NONCE": nonce,
+        }
+        if webhook:
+            platform_env["SANDBOX_JOB_WEBHOOK"] = webhook
+        # Caller-supplied reserved platform keys (function-mode's SANDBOX_CALL_JSON)
+        # ride the sandbox_env channel alongside the SANDBOX_JOB_* runner vars, never
+        # the user env map — the create path rejects a SANDBOX_ key on `env`.
+        for _k, _v in (extra_platform_env or {}).items():
+            platform_env[_k] = str(_v)
+
+        plan = DeployPlan(
+            image=spec.image,
+            memory=spec.memory,
+            cpu=spec.cpu,
+            entry=_RUNNER_ENTRY,
+            code_stage=spec.code_stage,
+            egress=egress_body,
+            env_keys=sorted([*job_env, *platform_env]),
+            bundle_files=_bundle_files(bundle_dir),
+        )
+
+        # `timeout` no longer maps to a wire lifetime: the server has no such field
+        # (idle_timeout_s now 400s), so the detached job lives per the container's
+        # own idle policy.
+        deploy_image = plan.image
+        return _JobPrep(
+            bundle_dir=bundle_dir,
+            deploy_image=deploy_image,
+            job_env=job_env,
+            platform_env=platform_env,
+            plan=plan,
+            nonce=nonce,
+            clone_root=clone_root,
+        )
+    except BaseException:
+        # The caller never gets the prep, so it cannot run _cleanup_job_prep —
+        # clean the temp trees here before the failure propagates.
+        if bundle_dir is not None:
+            shutil.rmtree(bundle_dir, ignore_errors=True)
+        if clone_root is not None:
+            shutil.rmtree(clone_root, ignore_errors=True)
+        raise
+
+
+def _cleanup_job_prep(prep: _JobPrep) -> None:
+    """Remove the temp trees `_prepare_job` created (bundle dir, clone)."""
+    shutil.rmtree(prep.bundle_dir, ignore_errors=True)
+    if prep.clone_root is not None:
+        shutil.rmtree(prep.clone_root, ignore_errors=True)
+
+
+async def deploy_async(
+    spec: DeploySpec,
+    *,
+    source_dir: str | Path | None = None,
+    on_line: object = None,
+    run_preflight: bool = True,
+    force_fresh: bool = True,
+    git_repo: str | None = None,
+    git_ref: str | None = None,
+    git_subdir: str | None = None,
+    webhook: str | None = None,
+    extra_platform_env: dict[str, str] | None = None,
+    connection: ConnectionLike | None = None,
+) -> Job:
+    """Spawn a detached Job from a `DeploySpec` and return a handle.
+
+    v0: ``job_id == container_id``; no stage / no Snowflake write in the runner.
+    ``on_line`` is accepted for signature parity with ``deploy_spec`` but unused
+    in a detached spawn (there is no streamed output to relay).
+
+    Here "async" names the *detached* deployment mode (spawn-and-return, mirroring
+    Modal's ``FunctionCall``), not the Python calling convention — this function
+    is itself awaitable. The blocking-Python entry point to the same detached
+    spawn is `deploy_async_sync`.
+
+    There is no ``timeout`` here: a detached job runs as the container's main
+    process and there is no wired hard-lifetime (the old ``idle_timeout_s`` proxy
+    was silently dropped server-side). Poll the result with a deadline via
+    ``Job.get(timeout=...)`` / ``AsyncSandbox.wait(timeout=...)``; use ``@app.session``
+    on the app for a long-lived daemon.
+
+    ``connection`` picks the Snowflake connection for this call; the handle carries it
+    onward. See `config.using` for the resolution rules (names, live connections,
+    memoisation, and how an enclosing ``using()`` block interacts).
+    """
+    del on_line  # parity with deploy_spec; nothing to stream in a detached spawn
+    del force_fresh  # accepted for signature parity; a spawn is always fresh
+
+    prep = _prepare_job(
+        spec,
+        source_dir=source_dir,
+        run_preflight=run_preflight,
+        git_repo=git_repo,
+        git_ref=git_ref,
+        git_subdir=git_subdir,
+        webhook=webhook,
+        extra_platform_env=extra_platform_env,
+    )
+    try:
+        sb = await AsyncSandbox.from_local(
+            prep.bundle_dir,
+            connection=connection,
+            command=list(_RUNNER_ENTRY),
+            image=prep.deploy_image,
+            memory=cast("MemoryTier", prep.plan.memory),
+            cpu=prep.plan.cpu,
+            code_stage=prep.plan.code_stage,
+            env=prep.job_env,
+            platform_env=prep.platform_env,
+            egress=prep.plan.egress,
+            stage_mounts=spec.stage_mounts,
+        )
+        await sb._ensure_created()
+        return Job(
+            id=sb.id,
+            nonce=prep.nonce,
+            name=getattr(sb, "name", None),
+            connection=connection,
+        )
+    finally:
+        _cleanup_job_prep(prep)
+
+
+def deploy_async_sync(
+    spec: DeploySpec,
+    *,
+    source_dir: str | Path | None = None,
+    on_line: object = None,
+    run_preflight: bool = True,
+    force_fresh: bool = True,
+    git_repo: str | None = None,
+    git_ref: str | None = None,
+    git_subdir: str | None = None,
+    webhook: str | None = None,
+    extra_platform_env: dict[str, str] | None = None,
+    connection: ConnectionLike | None = None,
+) -> SyncJob:
+    """Spawn a detached job synchronously — the blocking counterpart of `deploy_async`.
+
+    Two senses of "async" meet here and do not collide: the base name's *async*
+    is the detached deployment mode (spawn-and-return), and the ``_sync`` suffix
+    is this SDK's marker for the blocking-Python twin of an ``async def``. So
+    ``deploy_async_sync`` reads as "the blocking entry point to a detached
+    (async-mode) spawn". It shares the whole bundle-assembly core with
+    `deploy_async` via `_prepare_job` and only swaps the awaited container create
+    for the blocking one, so it spawns from a plain script with no event loop.
+
+    Returns a `SyncJob`; poll it with `SyncJob.get(timeout=...)` (or
+    `Sandbox.wait(timeout=...)`).
+
+    ``connection`` picks the Snowflake connection for this call; the handle carries it
+    onward. See `config.using` for the resolution rules (names, live connections,
+    memoisation, and how an enclosing ``using()`` block interacts).
+
+    Example:
+        job = deploy_async_sync(spec, source_dir="./agent")
+        result = job.get(timeout=600)
+        print(result.status)
+    """
+    del on_line  # parity with deploy_spec; nothing to stream in a detached spawn
+    del force_fresh  # accepted for signature parity; a spawn is always fresh
+
+    prep = _prepare_job(
+        spec,
+        source_dir=source_dir,
+        run_preflight=run_preflight,
+        git_repo=git_repo,
+        git_ref=git_ref,
+        git_subdir=git_subdir,
+        webhook=webhook,
+        extra_platform_env=extra_platform_env,
+    )
+    try:
+        sb = Sandbox.from_local(
+            prep.bundle_dir,
+            connection=connection,
+            command=list(_RUNNER_ENTRY),
+            image=prep.deploy_image,
+            memory=cast("MemoryTier", prep.plan.memory),
+            cpu=prep.plan.cpu,
+            code_stage=prep.plan.code_stage,
+            env=prep.job_env,
+            platform_env=prep.platform_env,
+            egress=prep.plan.egress,
+            stage_mounts=spec.stage_mounts,
+        )
+        sb._ensure_created()
+        return SyncJob(
+            id=sb.id,
+            nonce=prep.nonce,
+            name=getattr(sb, "name", None),
+            connection=connection,
+        )
+    finally:
+        _cleanup_job_prep(prep)