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

snowflake/sandbox/_ansi.py

@@ -0,0 +1,206 @@
+"""Terminal escape-sequence filtering.
+
+Generic byte-stream filtering for ANSI/OSC control sequences. Nothing here knows
+what a sandbox is: it takes pty bytes in and gives pty bytes out.
+
+It lives apart from `shell.py` because it outlives it. `shell.py` says in its own
+docstring that it is a stopgap to be deleted once a duplex stream reaches the
+sandbox -- but the reason to strip OSC 52 before writing remote bytes to a local
+terminal has nothing to do with which transport carried them, so a duplex
+replacement needs this filter unchanged. Leaving it inside the module marked for
+deletion invited it to be deleted along with it.
+"""
+
+from __future__ import annotations
+
+__all__ = ["_ClipboardStripper"]
+
+
+class _ClipboardStripper:
+    """Removes OSC 52 (clipboard-write) sequences from a byte stream.
+
+    Why this one sequence and not a general "sanitizer": a sandbox runs untrusted
+    and often agent-generated code, and `attach()` hands its raw output to the
+    operator's *local* terminal emulator. That is the same trust boundary `ssh`
+    and `docker attach` carry, but our remote end is less trusted than a host you
+    chose to log into, so the sequences that act on the operator's machine rather
+    than on the screen deserve removing.
+
+    OSC 52 qualifies unambiguously: it writes the local clipboard, has no display
+    purpose, and a sandbox silently replacing what the operator is about to paste
+    -- then having them paste it into a trusted shell -- is a real consequence.
+
+    Deliberately NOT filtered, because filtering them would break more than it
+    protects:
+
+    * **Display sequences** (CSI colours, cursor movement, alt-screen). Removing
+      these is removing the terminal, and `vim`/`htop` stop working.
+    * **Capability and cursor-position queries** (DA, DSR). A malicious sandbox
+      can use these to make the local terminal *reply*, and the reply arrives as
+      typed input on the next prompt -- a genuine residual risk. But legitimate
+      TUIs query these routinely, and an app whose query is swallowed hangs
+      waiting for an answer that never comes. Silently breaking working programs
+      to narrow an already-narrow window is the wrong trade; the honest answer is
+      to document it (see `attach`).
+    * **Window-title writes** (OSC 0/2). Annoying, not dangerous.
+
+    **This decides from the first bytes of the sequence, not from finding its
+    end**, and that shape is load-bearing rather than incidental. The first
+    version searched for the terminator and only then classified the body, which
+    forced it to buffer an unterminated sequence -- and to have a bound on that
+    buffer, past which it emitted the held bytes *verbatim*. A sandbox could
+    therefore defeat the filter completely by sending `ESC ] 52 ; c ;` followed by
+    more than the bound in base64 and the terminator in a later chunk: the
+    introducer and payload were passed through and the terminal reassembled them.
+    Classifying up front means an OSC 52 is discarded as it streams, so its length
+    is irrelevant and nothing needs holding.
+
+    It also treats a bare `ESC` inside a sequence as ENDING it, which is what
+    xterm-family terminals do. Otherwise `ESC ] 0 ; x  ESC ] 52 ; c ; <payload>
+    BEL` reads as one sequence whose parameter is `0` -- passed through intact --
+    while the terminal aborts the outer one at the inner `ESC` and honours the
+    clipboard write inside it.
+
+    The 8-bit C1 forms (`0x9d` introducer, `0x9c` terminator) are handled too, for
+    terminals that decode them.
+    """
+
+    # An OSC parameter is a short number followed by ';'. Anything longer than
+    # this without resolving is not a parameter, so stop waiting and pass it on.
+    _MAX_PARAM = 16
+
+    def __init__(self) -> None:
+        # "pass" outside a sequence; "esc" saw ESC awaiting ']'; "param" inside a
+        # sequence still reading its parameter; "keep"/"drop" inside a classified
+        # sequence.
+        self._state = "pass"
+        self._param = bytearray()
+        # What we were doing when an ESC arrived. ESC is ambiguous: it may start a
+        # new sequence, or be the first half of the 2-byte ST terminator, and the
+        # right handling of ST depends on whether we were keeping or dropping.
+        self._pre_esc = "pass"
+
+    def feed(self, data: bytes) -> bytes:
+        """Filter one chunk of the stream, returning the bytes safe to write.
+
+        Stateful across calls: a sequence split over two chunks is classified
+        from its first bytes, so an OSC 52 is dropped however it is fragmented.
+        Call `flush` at end of stream to release anything still withheld.
+        """
+        out = bytearray()
+        for byte in data:
+            self._step(byte, out)
+        return bytes(out)
+
+    def _enter_param(self) -> None:
+        """Begin a sequence, with its parameter not yet read."""
+        self._state = "param"
+        self._param.clear()
+
+    def _step(self, byte: int, out: bytearray) -> None:
+        # One handler per state (see __init__ for what each means); the states
+        # are few and fixed, so a dispatch reads more honestly than one long body.
+        state = self._state
+        if state == "pass":
+            self._step_pass(byte, out)
+        elif state == "esc":
+            self._step_esc(byte, out)
+        elif state == "param":
+            self._step_param(byte, out)
+        elif state == "keep":
+            self._step_keep(byte, out)
+        else:  # "drop"
+            self._step_drop(byte, out)
+
+    def _step_pass(self, byte: int, out: bytearray) -> None:
+        if byte == 0x1B:  # ESC -- may begin an OSC
+            self._pre_esc = "pass"
+            self._state = "esc"
+        elif byte == 0x9D:  # 8-bit OSC introducer
+            self._enter_param()
+        else:
+            out.append(byte)
+
+    def _step_esc(self, byte: int, out: bytearray) -> None:
+        if byte == 0x5C:  # '\\' -> this ESC was the 2-byte ST terminator
+            if self._pre_esc in ("keep", "pass"):
+                out += bytes((0x1B, 0x5C))
+            self._state = "pass"
+            self._param.clear()
+        elif byte == 0x5D:  # ']' -> a new OSC begins
+            self._enter_param()
+        elif byte == 0x1B:  # ESC ESC -- emit one, stay pending
+            if self._pre_esc in ("keep", "pass"):
+                out.append(0x1B)
+        else:
+            # Not a sequence we care about: replay the withheld ESC unless we
+            # were mid-drop, where everything is discarded anyway.
+            if self._pre_esc in ("keep", "pass"):
+                out += bytes((0x1B, byte))
+            self._state = "pass"
+
+    def _step_param(self, byte: int, out: bytearray) -> None:
+        if self._is_end(byte, out, keep=True):
+            return
+        if byte == 0x1B:
+            # A sequence aborted by a new ESC. Emit what we withheld (it was
+            # not OSC 52) and reprocess the ESC.
+            out += bytes((0x1B, 0x5D)) + bytes(self._param)
+            self._param.clear()
+            # Committed to passing this one through, so an ST that follows is
+            # echoed too.
+            self._pre_esc = "keep"
+            self._state = "esc"
+            return
+        self._param.append(byte)
+        if byte == 0x3B or len(self._param) > self._MAX_PARAM:  # ';'
+            param = bytes(self._param).rstrip(b";")
+            if param == b"52":
+                self._state = "drop"
+            else:
+                out += bytes((0x1B, 0x5D)) + bytes(self._param)
+                self._state = "keep"
+            self._param.clear()
+
+    def _step_keep(self, byte: int, out: bytearray) -> None:
+        if self._is_end(byte, out, keep=True):
+            return
+        if byte == 0x1B:
+            self._pre_esc = "keep"
+            self._state = "esc"
+            return
+        out.append(byte)
+
+    def _step_drop(self, byte: int, out: bytearray) -> None:
+        # Discard everything until the sequence ends. Length is irrelevant here,
+        # which is the whole point.
+        if self._is_end(byte, out, keep=False):
+            return
+        if byte == 0x1B:
+            self._pre_esc = "drop"
+            self._state = "esc"
+
+    def _is_end(self, byte: int, out: bytearray, *, keep: bool) -> bool:
+        """Handle BEL / 8-bit ST. Returns True if the byte ended the sequence."""
+        if byte in (0x07, 0x9C):
+            if keep:
+                out.append(byte)
+            self._state = "pass"
+            self._param.clear()
+            return True
+        return False
+
+    def flush(self) -> bytes:
+        """Emit anything withheld, at end of stream.
+
+        A partially-read parameter is emitted (it was never classified as OSC 52),
+        a pending ESC is emitted, and an in-progress OSC 52 stays dropped.
+        """
+        out = bytearray()
+        if self._state == "esc":
+            out.append(0x1B)
+        elif self._state == "param":
+            out += bytes((0x1B, 0x5D)) + bytes(self._param)
+        self._param.clear()
+        self._state = "pass"
+        return bytes(out)

snowflake/sandbox/_args.py

@@ -0,0 +1,208 @@
+"""Validating and coercing what the caller passed.
+
+Author-time checks on `Sandbox.create` arguments, and the translation of a
+caller's command into what the wire actually accepts. Failing here rather than at
+the server turns a confusing remote response into a message that names the
+parameter and the fix.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+from snowflake.sandbox.exceptions import SandboxError
+
+__all__ = [
+    "_tags_post_create_message",
+    "_validate_tags",
+    "_dur_seconds",
+    "_require_nonempty_cmd",
+    "_require_str_cmd",
+    "_cmd_to_code",
+    "_wrap_detached",
+]
+
+
+def _tags_post_create_message(create_call: str) -> str:
+    """Why ``set_tags()`` cannot relabel a running sandbox, and what to do instead.
+
+    The rule is the platform's and is identical for both clients, but the remedy
+    has to be spelled in the caller's own idiom — ``await AsyncSandbox.create(...)``
+    on the async client, ``Sandbox.create(...)`` on the sync one. Sharing the text
+    with the async spelling baked in told sync callers to await a class they are
+    not using, so the differing half is a parameter rather than a copy.
+    """
+    return (
+        "set_tags() cannot relabel a running sandbox: the backend stores tags (as "
+        "`labels`) only at create and exposes no update endpoint, so there is nowhere "
+        "to write them. Pass tags at create instead: "
+        f'{create_call}(..., tags={{"team": "sandbox"}}). Call set_tags() only '
+        "before the sandbox is created (it is then buffered into the create request)."
+    )
+
+
+def _validate_tags(tags: Mapping[str, str] | None, *, context: str) -> dict[str, str]:
+    """Coerce/validate a caller tag map into a plain ``dict[str, str]``.
+
+    Tags map to the server's ``labels`` field, which is a bare ``map[string]string``
+    with no server-side validation, so the only rules enforced are: keys and values
+    must be strings, and keys must be non-empty. An empty *value* is allowed (a
+    presence-style tag). An obvious mistake (a non-string value, an empty key) fails
+    at the call site rather than as a confusing server response or a
+    silently-stringified label. ``None`` -> ``{}``.
+    """
+    if tags is None:
+        return {}
+    if not isinstance(tags, Mapping):
+        raise SandboxError(
+            f"{context}: tags must be a mapping of str->str, got {type(tags).__name__}"
+        )
+    out: dict[str, str] = {}
+    for k, v in tags.items():
+        if not isinstance(k, str) or not isinstance(v, str):
+            raise SandboxError(
+                f"{context}: every tag key and value must be a str, got "
+                f"{type(k).__name__}->{type(v).__name__}"
+            )
+        if not k:
+            raise SandboxError(f"{context}: tag keys must be non-empty")
+        out[k] = v
+    return out
+
+
+def _dur_seconds(value: str | float) -> float:
+    """Parse a duration (``"30s"`` / ``"10m"`` / ``"1h"`` or a number) to seconds."""
+    if isinstance(value, (int, float)):
+        return float(value)
+    s = str(value).strip().lower()
+    try:
+        if s.endswith("ms"):
+            return float(s[:-2]) / 1000.0
+        if s.endswith("s"):
+            return float(s[:-1])
+        if s.endswith("m"):
+            return float(s[:-1]) * 60.0
+        if s.endswith("h"):
+            return float(s[:-1]) * 3600.0
+        return float(s)
+    except ValueError as exc:
+        raise SandboxError(f"invalid duration: {value!r}") from exc
+
+
+def _require_nonempty_cmd(cmd: Sequence[str], *, caller: str) -> None:
+    """Reject an empty argv before it becomes a silent no-op.
+
+    An empty ``cmd`` used to run and "succeed": `_cmd_to_code([])` produces
+    ``subprocess.run('', shell=True, ...)``, and a shell handed an empty string
+    exits 0 with no output. The caller got an `ExecResult` with ``exit_code == 0``
+    and empty streams -- indistinguishable from a command that ran and printed
+    nothing, so a bug that dropped the argv on the floor looked like a pass.
+
+    *caller* names the public method in the message so the steer is actionable
+    from either ``exec`` or ``exec_stream``.
+    """
+    if not cmd:
+        raise SandboxError(
+            f"{caller}() requires at least one command element; got an empty "
+            f"sequence. An empty argv would have run an empty shell command and "
+            f"returned exit_code 0 with no output, which is indistinguishable "
+            f"from success. Pass the program and its arguments, e.g. "
+            f'{caller}(["python", "-c", "print(42)"]).'
+        )
+
+
+def _require_str_cmd(cmd: Sequence[str], *, caller: str) -> None:
+    """Reject a non-string argv element before shlex silently reinterprets it.
+
+    `_cmd_to_code` quotes with ``shlex.quote``, which starts ``if not s: return "''"``
+    -- so ``None`` is FALSY and comes back as an empty shell argument rather than
+    raising: ``["ok", None]`` ran as ``ok \'\'``, a different command than the caller
+    passed, with nothing said. An ``int`` is the milder half: shlex raises, but a bare
+    ``TypeError`` that ``except SandboxError`` does not catch, unlike every other
+    input-validation failure here.
+    """
+    if isinstance(cmd, str):
+        # A bare string is iterated character by character below, so every element
+        # is trivially a str and the loop never fires -- then `_cmd_to_code` quotes
+        # each character and runs a mangled command. Reject it here: argv is a
+        # sequence of program-plus-arguments, not a shell line.
+        raise SandboxError(
+            f"{caller}() takes an argv sequence, not a string: {cmd!r} would be "
+            f"iterated character by character. Pass a list, e.g. "
+            f'{caller}(["ls", "-la"]) or {caller}(["sh", "-c", {cmd!r}]).'
+        )
+    for i, arg in enumerate(cmd):
+        if not isinstance(arg, str):
+            raise SandboxError(
+                f"{caller}() cmd[{i}] must be str, got {type(arg).__name__}. Every "
+                f"element of the argv must be a string; pass str(x) if you meant to "
+                f"interpolate a value."
+            )
+
+
+def _cmd_to_code(cmd: Sequence[str]) -> str:
+    """Turn an argv into the single Python ``code`` string /execute accepts.
+
+    A ``python -c CODE`` invocation passes CODE through; any other argv is
+    wrapped in a subprocess call so arbitrary commands run.
+
+    Trailing arguments after ``-c CODE`` are delivered as ``sys.argv``. They used
+    to be dropped silently: ``exec(["python3", "-c", src, "AAA"])`` sent only
+    ``src``, and the script saw ``sys.argv == ['-']`` (the /execute path feeds the
+    source to the interpreter on stdin), so callers had no way to parameterize a
+    run per exec and no error telling them so.
+    """
+    if len(cmd) >= 3 and cmd[0] in ("python", "python3") and cmd[1] == "-c":
+        code, extra = cmd[2], list(cmd[3:])
+        if not extra:
+            return code
+        # Compile the caller's source as its own unit rather than prepending the
+        # assignment to it: prepending breaks `from __future__ import ...`, which
+        # must be the first statement. Passing __name__ == "__main__" keeps
+        # `if __name__ == "__main__":` entry points working.
+        return (
+            "import sys\n"
+            f"sys.argv = {['-c', *extra]!r}\n"
+            f"exec(compile({code!r}, '<sandbox-exec>', 'exec'), "
+            "{'__name__': '__main__', '__builtins__': __builtins__})\n"
+        )
+    import shlex
+
+    joined = " ".join(shlex.quote(a) for a in cmd)
+    # Inherited, not captured: capture_output=True is communicate(), which waits for
+    # pipe EOF rather than for the command to exit -- so a descendant left holding the
+    # pipe burned the whole server deadline (exit 124, or 137 on guest-init) and the
+    # buffered output was discarded with it. sandbox-server's drain loop already breaks
+    # on the child's exit regardless of pipe EOF, and reads the two streams separately,
+    # so inheriting hands the deadline back to it and keeps stdout/stderr apart. #266
+    return (
+        "import subprocess, sys; "
+        f"r = subprocess.run({joined!r}, shell=True); "
+        "sys.exit(r.returncode)"
+    )
+
+
+def _wrap_detached(cmd: Sequence[str]) -> tuple[list[str], str]:
+    """Wrap *cmd* so a detached run prints a result sentinel on exit.
+
+    Returns ``(argv, nonce)``. Sets ``$SANDBOX_RESULT`` (creating its dir), runs
+    *cmd* as a subprocess, then emits
+    ``__SANDBOX_RESULT__<base64(json)>`` — what `Sandbox.wait()` scans for —
+    carrying ``{status, exit_code, result, nonce}``. ``result`` is the parsed
+    ``$SANDBOX_RESULT`` artifact the inner command wrote (matching the
+    ``deploy_async`` job-runner), or ``{"exit_code": N}`` if it wrote none.
+
+    The ``nonce`` is minted here, per run, and kept in the wrapper only: it is
+    never exported to the inner command's environment. `wait()` requires it, so
+    an arbitrary ``__SANDBOX_RESULT__`` line printed by the workload itself is no
+    longer read as the run's authoritative outcome.
+    """
+    import json as _json
+    import uuid as _uuid
+
+    from snowflake.sandbox._runtime._shims import _detached_wrapper_source
+
+    nonce = _uuid.uuid4().hex
+    payload = _json.dumps(list(cmd))
+    script = _detached_wrapper_source(payload, nonce)
+    return ["python3", "-c", script], nonce

snowflake/sandbox/_assemble.py

@@ -0,0 +1,256 @@
+"""Assemble the local bundle that gets shipped to a sandbox.
+
+``Bundle`` is the declaration — which local tree, which include/exclude globs —
+and the helpers below are what realize it: shallow-clone a git ref, copy a tree
+while filtering excludes / symlinks / credential-shaped files, expand ``${VAR}``
+references, and layer include-glob matches on top. Everything here is local and
+filesystem-only: no Snowflake calls, no network beyond ``git clone``.
+
+``deploy_spec`` (``deploy``), ``deploy_async`` (``jobs``), ``Function.remote``
+(``function``) and ``agent_session`` (``warm_session``) all package their code
+through this module, which is why it is a module and not four copies.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import shutil
+import subprocess
+import tempfile
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from snowflake.sandbox.exceptions import SandboxError
+
+
+@dataclass(frozen=True)
+class Bundle:
+    """Source-tree slice bundled and uploaded to the sandbox.
+
+    Example:
+        bundle = Bundle.from_dir(
+            ".",
+            include=["src/**", "config.toml"],
+            exclude=["*.pyc", ".DS_Store"],
+        )
+    """
+
+    root: str = "."
+    include: tuple[str, ...] = field(default_factory=tuple)
+    exclude: tuple[str, ...] = field(default_factory=tuple)
+
+    @staticmethod
+    def from_dir(
+        root: str,
+        *,
+        include: Sequence[str] = (),
+        exclude: Sequence[str] = (),
+    ) -> Bundle:
+        """Construct a Bundle from a root directory with optional glob patterns."""
+        return Bundle(root=root, include=tuple(include), exclude=tuple(exclude))
+
+
+def _bundle_files(source_dir: Path, limit: int = 200) -> list[str]:
+    out = []
+    for p in sorted(source_dir.rglob("*")):
+        if p.is_file() and "__pycache__" not in p.parts and ".git" not in p.parts:
+            out.append(str(p.relative_to(source_dir)))
+            if len(out) >= limit:
+                out.append("... (truncated)")
+                break
+    return out
+
+
+_DEFAULT_EXCLUDES = ("*.pyc", ".DS_Store")
+_SKIP_DIR_NAMES = {"__pycache__", ".git", ".venv", "node_modules"}
+
+
+def _clone_git_ref(repo: str, ref: str | None, subdir: str | None) -> tuple[Path, Path, str]:
+    """Shallow-clone ``repo`` at ``ref`` into a temp dir.
+
+    Returns ``(clone_root, effective_source_dir, resolved_sha)``.  The caller
+    is responsible for ``shutil.rmtree``-ing ``clone_root``.
+
+    Strategy: ``git clone --depth 1 <repo> <tmp>`` then
+    ``git -C <tmp> fetch --depth 1 origin <ref> && git -C <tmp> checkout FETCH_HEAD``.
+    This handles both branch/tag names and full/abbreviated SHAs with a single
+    code path (fetch by refspec always works for branches; for SHAs it works on
+    GitHub and most servers that enable ``uploadpack.allowReachableSHA1InWant``).
+    ``ref=None`` skips the second fetch and uses the default branch HEAD.
+    """
+    tmp_parent = Path(tempfile.mkdtemp(prefix="sbx-git-"))
+    tmp = tmp_parent / "repo"
+    try:
+        # Initial shallow clone (gets default branch HEAD; also establishes the remote).
+        subprocess.run(
+            ["git", "clone", "--depth", "1", repo, str(tmp)],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+
+        if ref is not None:
+            # Fetch the requested ref and check it out.
+            subprocess.run(
+                ["git", "-C", str(tmp), "fetch", "--depth", "1", "origin", ref],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            subprocess.run(
+                ["git", "-C", str(tmp), "checkout", "FETCH_HEAD"],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+
+        # Resolve the HEAD SHA.
+        proc = subprocess.run(
+            ["git", "-C", str(tmp), "rev-parse", "HEAD"],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        sha = proc.stdout.strip()
+
+        effective = tmp / subdir if subdir else tmp
+        if not effective.is_dir():
+            raise SandboxError(f"git subdir not found in clone: {subdir}")
+
+        print(f"[deploy] resolved {repo}@{ref or 'HEAD'} -> {sha}")
+        return tmp_parent, effective, sha
+    except subprocess.CalledProcessError as exc:
+        shutil.rmtree(tmp_parent, ignore_errors=True)
+        stderr_msg = (exc.stderr or "").strip()
+        raise SandboxError(f"git clone/fetch failed: {stderr_msg or exc}") from exc
+    except Exception:
+        shutil.rmtree(tmp_parent, ignore_errors=True)
+        raise
+
+
+def _excluded(rel: str, patterns: Sequence[str]) -> bool:
+    if _SKIP_DIR_NAMES & set(Path(rel).parts):
+        return True
+    return any(
+        fnmatch.fnmatch(rel, pat) or fnmatch.fnmatch(Path(rel).name, pat) for pat in patterns
+    )
+
+
+def _copy_tree_into(src_root: Path, dest: Path, excludes: Sequence[str]) -> None:
+    from snowflake.sandbox._bundle import _is_credential_path
+
+    for src in sorted(src_root.rglob("*")):
+        # A symlink is followed by is_file()/copy2, so one pointing outside the
+        # project would put its target in the bundle (and then on a stage). The
+        # bundle is the project tree, nothing else.
+        if src.is_symlink():
+            continue
+        if not src.is_file():
+            continue
+        rel = src.relative_to(src_root)
+        if _excluded(str(rel), excludes):
+            continue
+        # `.env` / `id_rsa` / `*.pem` beside the entry point is the normal layout;
+        # the default excludes were only *.pyc + .DS_Store, so they shipped.
+        if _is_credential_path(rel):
+            continue
+        (dest / rel).parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src, dest / rel, follow_symlinks=False)
+
+
+def _subst_map(
+    var_overrides: Mapping[str, str] | None,
+    env_overrides: Mapping[str, str] | None,
+) -> dict[str, str]:
+    """Build the manifest ``${VAR}`` substitution map for ``[bundle]``/``[build]``.
+
+    Precedence (highest wins): ``var_overrides`` (build-time ``--var``) >
+    ``env_overrides`` (runtime ``--env``, also usable for substitution since some
+    values like ``TRIAGE_TEAM`` are both) > ``os.environ`` (resolved lazily by
+    ``_expand_vars`` for names not in the explicit map)."""
+    merged: dict[str, str] = {}
+    if env_overrides:
+        merged.update(env_overrides)
+    if var_overrides:
+        merged.update(var_overrides)
+    return merged
+
+
+def _expand_vars(text: str, subst: Mapping[str, str] | None) -> str:
+    """Expand ``$VAR`` / ``${VAR}`` in *text* against *subst*.
+
+    *subst* is the build-time substitution map (see ``_subst_map``). Names absent
+    from it fall back to ``os.environ`` (so plain ``os.path.expandvars`` behaviour
+    is preserved for back-compat). Passing ``subst=None`` is exactly the old
+    ``os.path.expandvars``."""
+    if subst is None:
+        return os.path.expandvars(text)
+    # Layer subst over os.environ for the duration of the expansion: explicit
+    # overrides win, anything else still resolves from the process environment.
+    saved = {k: os.environ.get(k) for k in subst}
+    try:
+        os.environ.update(subst)
+        return os.path.expandvars(text)
+    finally:
+        for k, old in saved.items():
+            if old is None:
+                os.environ.pop(k, None)
+            else:
+                os.environ[k] = old
+
+
+def _assemble_bundle(
+    manifest_dir: Path, spec: dict[str, Any], subst: Mapping[str, str] | None = None
+) -> Path:
+    """Assemble a bundle from the project dir + ``[bundle].include`` globs.
+
+    The manifest's own directory is the base (entry, setup.sh, requirements.txt
+    ship as in a plain deploy). ``[bundle].include`` globs are resolved against
+    ``[bundle].root`` (default: the manifest dir; ``$VARS`` and ``~`` expanded)
+    and layered under ``[bundle].mount`` (default: bundle root), preserving each
+    match's path relative to root. This lets a workload whose files are scattered
+    across a monorepo declare its slice instead of shipping a bespoke packer.
+
+    ``$VAR`` expansion in ``root`` / ``include`` resolves from *subst* (the merged
+    build-time map: ``var_overrides`` > ``env_overrides`` > ``os.environ``) so a
+    relative ``root = ".."`` plus ``--var TRIAGE_TEAM=platform`` needs no shell export.
+
+    Note: glob ``**`` does not descend into symlinked directories — include such
+    targets explicitly (e.g. the real dir behind a symlink)."""
+    excludes = list(_DEFAULT_EXCLUDES) + list(spec.get("exclude") or [])
+    dest = Path(tempfile.mkdtemp(prefix="sbx-bundle-"))
+    _copy_tree_into(manifest_dir, dest, excludes)
+
+    root = Path(os.path.expanduser(_expand_vars(spec.get("root") or str(manifest_dir), subst)))
+    if not root.is_absolute():
+        root = (manifest_dir / root).resolve()
+    if not root.is_dir():
+        raise SandboxError(f"[bundle].root not found: {root}")
+    from snowflake.sandbox._bundle import _is_credential_path
+
+    mount = dest / (spec.get("mount") or ".")
+    copied: set[str] = set()
+    for pattern in spec.get("include") or []:
+        pattern = _expand_vars(pattern, subst)  # e.g. teams/${TRIAGE_TEAM}/**
+        for match in sorted(root.glob(pattern)):
+            # A glob match is either a file (copy it) or a directory (copy the
+            # files beneath it) — `**` matches dirs, not the files under them.
+            files = [match] if match.is_file() else [p for p in match.rglob("*") if p.is_file()]
+            for src_file in files:
+                # The same credential + symlink filters the base copy runs. Without
+                # them here, `include=["**"]` / `root=".."` would upload `.env` /
+                # `id_rsa` / `~/.aws` to the stage: skip symlinks (a symlink out of
+                # the tree would drag its target in) and credential-shaped paths.
+                if src_file.is_symlink():
+                    continue
+                rel = src_file.relative_to(root)
+                key = str(rel)
+                if key in copied or _excluded(key, excludes) or _is_credential_path(rel):
+                    continue
+                (mount / rel).parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(src_file, mount / rel, follow_symlinks=False)
+                copied.add(key)
+    return dest