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

snowflake/sandbox/_mcp_status.py

@@ -0,0 +1,183 @@
+"""In-sandbox MCP connection status: "can I use this connector right now?"
+
+The client-facing surface here — `McpConnectionStatus`, `mcp_server_status`, and
+the ``MCP_STATUS_*`` vocabulary — is re-exported from `snowflake.sandbox.mcp` (and
+the package root), which is where it is documented and imported from. It lives in
+its own module because it shares nothing with the discovery/SQL half of `mcp`:
+this side reads a JSON file the hostagent writes inside the container and never
+opens a Snowflake connection.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Literal, cast, get_args, overload
+
+# Where the hostagent writes the per-server fetch outcome INSIDE the container.
+# This is the authoritative "can I use this connector right now?" signal, and it
+# is deliberately not the account-status view `list_mcp_servers` reads:
+# SYSTEM$GET_USER_INTEGRATION_AUTHORIZATIONS keeps reporting CONNECTED after the
+# OAuth provider revokes a grant, because the revocation happens IdP-side and
+# Snowflake only learns of it when it next tries to use the token. The hostagent
+# does try -- on every refresh cycle -- so its own fetch result is the only
+# source that stays truthful mid-life.
+#
+# The file is a single JSON document keyed by the client-facing server name (the
+# same <NAME> as SANDBOX_MCP_TOKEN_<NAME>), each value carrying
+# {status, fqn, gs_error_code, detail, last_checked_at}. The path, the key, and
+# the status vocabulary below are the contract shared with the hostagent half;
+# change them only in lockstep with it.
+MCP_STATUS_PATH = "/snowflake/mcp/status.json"
+
+# The connector is usable: the last per-user token fetch succeeded.
+MCP_STATUS_LIVE: Literal["live"] = "live"
+# The connector needs the user to re-consent in Snowsight. The hostagent maps a
+# Snowflake policy verdict of ACCESS_DENIED or SECRET_NOT_FOUND to this -- the OAuth
+# grant was revoked, or the secret can no longer be resolved for this user, and
+# no retry inside the sandbox will fix it.
+MCP_STATUS_RECONNECT_REQUIRED: Literal["reconnect_required"] = "reconnect_required"
+# The status could not be determined: no status file (an older runtime, or the
+# feature not enabled) or no entry for this name. Fail-soft -- absence is never
+# reported as an outage.
+MCP_STATUS_UNKNOWN: Literal["unknown"] = "unknown"
+
+McpLiveStatus = Literal["live", "reconnect_required", "unknown"]
+"""In-sandbox connection status of an EXTERNAL MCP SERVER (`McpConnectionStatus.status`)."""
+
+
+def _coerce_live_status(raw: str | None) -> McpLiveStatus:
+    """Clamp a status-file value to the known set; anything else -> ``unknown``."""
+    return cast("McpLiveStatus", raw) if raw in get_args(McpLiveStatus) else MCP_STATUS_UNKNOWN
+
+
+@dataclass(frozen=True)
+class McpConnectionStatus:
+    """The live, in-sandbox connection status of one EXTERNAL MCP SERVER.
+
+    This is what code running *inside* a sandbox should consult before it relies
+    on a connector. It reflects the platform's most recent attempt to fetch
+    *your* OAuth token for the server, so it is the one signal that stays truthful
+    after a provider-side revocation. `McpServerInfo.status` (from
+    `list_mcp_servers`) is the account/authorization view and can still read
+    ``CONNECTED`` when the grant has actually lapsed; when the two disagree, this
+    one is right about whether a tool call will succeed.
+
+    ``status`` is one of ``live``, ``reconnect_required``, or ``unknown``. When it
+    is ``reconnect_required`` the fix is a one-time re-consent in Snowsight (not a
+    retry): ``gs_error_code`` carries the verdict that classified it
+    (``ACCESS_DENIED`` / ``SECRET_NOT_FOUND``) and ``detail`` a human-readable
+    line. ``unknown`` means no signal was available and must not be treated as an
+    outage.
+    """
+
+    name: str
+    status: McpLiveStatus
+    fqn: str | None = None
+    gs_error_code: str | None = None
+    detail: str | None = None
+    last_checked_at: str | None = None
+
+    @property
+    def needs_reconnect(self) -> bool:
+        """True only when the server is known to need a re-consent."""
+        return self.status == MCP_STATUS_RECONNECT_REQUIRED
+
+    @property
+    def live(self) -> bool:
+        """True only when the last token fetch for this server succeeded."""
+        return self.status == MCP_STATUS_LIVE
+
+
+def _status_entry(name: str, raw: object) -> McpConnectionStatus:
+    """Build one `McpConnectionStatus` from a status-file value, fail-soft.
+
+    Any missing or non-string field degrades to ``None`` / ``unknown`` rather
+    than raising, so a shape the platform tightens later cannot break a caller.
+    """
+    if not isinstance(raw, Mapping):
+        return McpConnectionStatus(name=name, status=MCP_STATUS_UNKNOWN)
+
+    def _s(key: str) -> str | None:
+        value = raw.get(key)
+        return value if isinstance(value, str) and value else None
+
+    return McpConnectionStatus(
+        name=name,
+        status=_coerce_live_status(_s("status")),
+        fqn=_s("fqn"),
+        gs_error_code=_s("gs_error_code"),
+        detail=_s("detail"),
+        last_checked_at=_s("last_checked_at"),
+    )
+
+
+def _load_status_doc(path: str | os.PathLike[str]) -> dict[str, Any] | None:
+    """Read and parse the status file, or None if absent / unreadable / malformed."""
+    try:
+        with open(path, encoding="utf-8") as fh:
+            doc = json.load(fh)
+    except (OSError, ValueError):
+        # Missing file (older runtime / feature off), unreadable, or invalid JSON.
+        return None
+    return doc if isinstance(doc, dict) else None
+
+
+@overload
+def mcp_server_status(name: str, *, path: str | os.PathLike[str] = ...) -> McpConnectionStatus: ...
+
+
+@overload
+def mcp_server_status(
+    name: None = ..., *, path: str | os.PathLike[str] = ...
+) -> list[McpConnectionStatus]: ...
+
+
+def mcp_server_status(
+    name: str | None = None,
+    *,
+    path: str | os.PathLike[str] = MCP_STATUS_PATH,
+) -> McpConnectionStatus | list[McpConnectionStatus]:
+    """Read the live connection status the platform publishes inside the sandbox.
+
+    Call this from code running *in* a sandbox to learn whether an MCP connector
+    is usable right now, or whether the user must re-consent to it. Unlike
+    `list_mcp_servers` -- which queries the account and can report a revoked grant
+    as still ``CONNECTED`` -- this reads the platform's own most-recent
+    token-fetch result, rewritten each refresh cycle, so it catches a
+    provider-side revocation the account view misses.
+
+    With a ``name`` it returns that one server's `McpConnectionStatus` (the client
+    name used in ``mcp_servers=``, i.e. the ``<NAME>`` in
+    ``SANDBOX_MCP_TOKEN_<NAME>``); with no name it returns one for every server
+    the sandbox currently has a signal for. A missing file or a missing entry
+    yields status ``unknown`` rather than raising -- absence is never an outage.
+
+    Example:
+        from snowflake.sandbox import mcp_server_status
+
+        gh = mcp_server_status("github")
+        if gh.needs_reconnect:
+            raise SystemExit(
+                f"Reconnect {gh.fqn} in Snowsight before running: {gh.detail}"
+            )
+
+    Parameters
+    ----------
+    name:
+        The client-facing server name to look up. Omit to get the full list.
+    path:
+        Status-file path; defaults to the runtime location and is a parameter
+        only so tests need not write to an absolute system path.
+    """
+    doc = _load_status_doc(path)
+    if name is not None:
+        raw = doc.get(name) if doc is not None else None
+        if raw is None:
+            return McpConnectionStatus(name=name, status=MCP_STATUS_UNKNOWN)
+        return _status_entry(name, raw)
+    if not doc:
+        return []
+    return [_status_entry(str(key), value) for key, value in doc.items()]

snowflake/sandbox/_retry.py

@@ -0,0 +1,94 @@
+"""Backoff + jitter helper for the SDK retry loop.
+
+Retry policy:
+
+- Cold-start retries on ``503`` or ``409 not_ready``: exponential backoff
+  ``1, 4, 16, 64s`` capped at 4 attempts.
+- ``429`` honors the ``Retry-After`` header.
+- ``500`` retries once, then surfaces ``SandboxTransportError``.
+- Retries computed here jitter ±25%. The one exception is a ``429`` that carries
+  a ``Retry-After``: ``_transport._rate_limit_delay`` jitters that hint *upward
+  only*, because retrying before the moment the server named would re-hammer a
+  gateway that just asked us to back off.
+
+Every one of those is gated on **idempotency**: for a non-idempotent method
+(POST) a retry is issued only when the failure proves the server never ran the
+request. See ``_transport._IDEMPOTENT_METHODS`` for the rule and why.
+
+The helper here only computes delays; the wiring into specific HTTP status
+codes lives in ``_transport.py``.
+"""
+
+from __future__ import annotations
+
+import random
+
+__all__ = [
+    "compute_backoff",
+    "DEFAULT_COLD_START_DELAYS_S",
+    "DEFAULT_500_DELAYS_S",
+    "DEFAULT_LOGS_500_DELAYS_S",
+    "DEFAULT_NOT_FOUND_DELAYS_S",
+    "DEFAULT_START_FAILURE_DELAYS_S",
+    "is_retryable_start_failure",
+]
+
+DEFAULT_COLD_START_DELAYS_S: tuple[float, ...] = (1.0, 4.0, 16.0, 64.0)
+"""Delays before attempt 1, 2, 3, 4 of cold-start retries (4 attempts total)."""
+
+DEFAULT_500_DELAYS_S: tuple[float, ...] = (1.0,)
+"""Single retry budget for 500s, then surface as SandboxTransportError."""
+
+DEFAULT_NOT_FOUND_DELAYS_S: tuple[float, ...] = (0.5, 1.0, 2.0, 4.0)
+"""Retries for a 404 right after create: a freshly-created container is not
+yet routable for a moment. Bounded (~7.5s) so a genuinely-missing container
+still surfaces SandboxNotFoundError quickly."""
+
+DEFAULT_LOGS_500_DELAYS_S: tuple[float, ...] = (1.0, 2.0, 4.0, 8.0)
+"""Longer 500 budget (~15s) for the read-only logs route. Fetching logs while a
+container is mid-run can hit a transient upstream 500 that outlasts the single
+default 500 retry; a GET is idempotent so extending the budget is safe. Bounded
+so a persistent 500 still surfaces SandboxTransportError."""
+
+DEFAULT_START_FAILURE_DELAYS_S: tuple[float, ...] = (2.0, 8.0)
+"""Backoff before re-creating a container after a *retryable* StartApp failure
+(2 re-creates → 3 create attempts total). The CNG controller has already
+exhausted its own in-place StartApp attempts and tagged the failure retryable, so
+a fresh container may land on a healthy hostagent. Kept small so create() never
+hangs on a persistent condition."""
+
+
+def is_retryable_start_failure(status: str, error_message: str | None) -> bool:
+    """True when a create settled on a terminal ``failed`` the server tagged retryable.
+
+    There is no structured ``retryable`` flag on the wire today, so this matches the
+    ``(retryable)`` marker CNG's controller emits after it exhausts its own StartApp
+    attempts. Scoped to ``create()``'s own readiness wait: the message is hydrated
+    from *this* attempt's failed-container poll immediately before the raise, so the
+    staleness that makes ``_error_message`` unusable elsewhere does not apply here.
+    """
+    return status == "failed" and "(retryable)" in (error_message or "")
+
+
+def compute_backoff(
+    attempt: int,
+    *,
+    delays: tuple[float, ...] = DEFAULT_COLD_START_DELAYS_S,
+    jitter: float = 0.25,
+    rng: random.Random | None = None,
+) -> float | None:
+    """Return the delay in seconds before the given retry attempt.
+
+    ``attempt`` is 1-indexed (the first retry is ``attempt=1``). Returns
+    ``None`` if the attempt is past the budget — the caller surfaces the
+    terminal exception.
+
+    Jitter is full-symmetric: the returned delay is uniformly sampled from
+    ``[base * (1 - jitter), base * (1 + jitter)]``.
+    """
+    if attempt < 1 or attempt > len(delays):
+        return None
+    base = delays[attempt - 1]
+    r = rng if rng is not None else random.Random()
+    spread = base * jitter
+    return max(0.0, base + r.uniform(-spread, spread))

snowflake/sandbox/_runtime/__init__.py

@@ -0,0 +1,42 @@
+"""Code that runs on the **far side** of the sandbox boundary.
+
+Everything in this subpackage executes *inside* a sandbox container, not in the
+calling process. That is the whole reason it has a home of its own: the boundary
+is otherwise invisible. These are not helpers the SDK calls — they are programs
+the SDK *writes out and ships*, to be run later, by a different interpreter, on
+another machine, with only the base image's stdlib available.
+
+What follows from that, and is easy to forget when the same text sits inline in a
+client-side module:
+
+* **No SDK imports.** The container's base image ships (at most) the *published*
+  SDK, which may be older than the one deploying. In-container programs stand on
+  the stdlib alone — every value they need is baked into their source as a
+  literal, never imported at run time.
+* **The programs are not type-checked or linted.** These modules hold their
+  source as *strings*; mypy and ruff see the quotes, not the program. A typo
+  inside one surfaces as a container that dies on start, hundreds of milliseconds
+  of network away from the traceback that would have named it.
+* **Every string is a wire protocol.** The stdout sentinels, the mailbox path and
+  the marker-attribute names are read by the *other* side. Changing one is a
+  compatibility break against sandboxes already running, not a rename — which is
+  why they are defined once, in `_protocol`, and imported by both halves.
+
+Layout:
+
+* `_protocol` — the constants both sides must agree on (sentinels, mailbox path,
+  nonce env var, marker attributes, inotify mask bits).
+* `_job_runner` — the bash runner ``deploy_async`` injects to wrap a detached run.
+* `_shims` — the generated python entrypoints: the ``@app.session`` daemon, the
+  ``@app.function`` runner, and the detached-command wrapper.
+* `_fs_helper` — the ``python3 -c`` programs behind the directory ops and the
+  ``inotify(7)`` file watcher.
+
+The one piece of in-container code deliberately *not* here is
+`snowflake.sandbox.warm_session.session_loop`. It runs in the container too, but it is
+public API the *user* imports and calls from their own entrypoint — ordinary
+typed, linted, documented library code — so it keeps a public home. What lives
+here is the code the SDK generates and the caller never sees.
+"""
+
+from __future__ import annotations

snowflake/sandbox/_runtime/_fs_helper.py

@@ -0,0 +1,93 @@
+"""The ``python3 -c`` programs behind the filesystem surface.
+
+Two of the three filesystem mechanisms have no server route, so they run as
+source text in the container over ``exec`` / ``exec_stream`` instead:
+
+* the **directory ops** (``list_files`` / ``stat`` / ``make_directory`` /
+  ``remove``) — the ``/files`` route transfers bytes only, so these are ordinary
+  in-container filesystem calls that print structured JSON back;
+* the **file watcher** — a ``ctypes``-driven ``inotify(7)`` monitor, reaching a
+  kernel facility through ``libc`` so it needs no container package (the image
+  ships neither an ``inotifywait`` binary nor a python inotify library).
+
+Both embed their arguments as ``repr``'d Python literals or pass them as separate
+argv entries — never shell-interpolated — so a path containing spaces, quotes or
+shell metacharacters cannot break out of the program.
+"""
+
+from __future__ import annotations
+
+from snowflake.sandbox._runtime._protocol import (
+    _FS_SENTINEL,
+    _IN_CLOSE_WRITE,
+    _IN_CREATE,
+    _IN_DELETE,
+    _IN_MODIFY,
+    _IN_MOVED_FROM,
+    _IN_MOVED_TO,
+    _WATCH_READY,
+    _WATCH_SENTINEL,
+)
+
+__all__ = ["_FS_HELPER_PREAMBLE", "_watch_program"]
+
+
+_FS_HELPER_PREAMBLE = f"""\
+import json, os, shutil, sys
+def _emit(obj):
+    sys.stdout.write({_FS_SENTINEL!r} + json.dumps(obj) + "\\n")
+"""
+
+
+def _watch_program() -> str:
+    """The in-container inotify monitor, as a python3 ``-c`` source string.
+
+    Prints ``_WATCH_READY`` once armed, then one ``_WATCH_SENTINEL{json}`` line
+    per event (``{"mask": int, "path": abs}``). argv: ``[root, recursive01,
+    timeout_or_empty]``. inotify is not natively recursive, so with recursion it
+    walks the tree at start and adds a watch for each directory created
+    afterward, keeping the watch set complete.
+    """
+    mask = _IN_CREATE | _IN_MOVED_TO | _IN_DELETE | _IN_MOVED_FROM | _IN_MODIFY | _IN_CLOSE_WRITE
+    # IN_ISDIR rides the high bit of an event mask when the subject is a dir.
+    return f"""\
+import ctypes, ctypes.util, os, struct, select, sys, time, json
+root = sys.argv[1]
+recursive = sys.argv[2] == "1"
+timeout = float(sys.argv[3]) if sys.argv[3] else None
+IN_ISDIR = 0x40000000
+MASK = {mask}
+libc = ctypes.CDLL(ctypes.util.find_library("c") or "libc.so.6", use_errno=True)
+fd = libc.inotify_init1(os.O_NONBLOCK)
+if fd < 0:
+    sys.stderr.write("inotify_init1 failed errno=%d\\n" % ctypes.get_errno()); sys.exit(2)
+wds = {{}}
+def add(path):
+    wd = libc.inotify_add_watch(fd, path.encode(), MASK)
+    if wd >= 0:
+        wds[wd] = path
+    return wd
+if add(root) < 0:
+    sys.stderr.write("inotify_add_watch failed for %r errno=%d\\n" % (root, ctypes.get_errno())); sys.exit(3)
+if recursive:
+    for dp, dns, _fns in os.walk(root):
+        for d in dns:
+            add(os.path.join(dp, d))
+sys.stdout.write({_WATCH_READY!r} + "\\n"); sys.stdout.flush()
+deadline = None if timeout is None else time.time() + timeout
+while deadline is None or time.time() < deadline:
+    wait = 1.0 if deadline is None else max(0.0, deadline - time.time())
+    if not select.select([fd], [], [], wait)[0]:
+        continue
+    buf = os.read(fd, 8192)
+    i = 0
+    while i + 16 <= len(buf):
+        wd, m, _cookie, ln = struct.unpack_from("iIII", buf, i); i += 16
+        name = buf[i:i+ln].split(b"\\x00", 1)[0].decode("utf-8", "replace"); i += ln
+        base = wds.get(wd, root)
+        full = os.path.join(base, name) if name else base
+        if recursive and (m & {_IN_CREATE}) and (m & IN_ISDIR):
+            add(full)
+        sys.stdout.write({_WATCH_SENTINEL!r} + json.dumps({{"mask": m, "path": full}}) + "\\n")
+        sys.stdout.flush()
+"""

snowflake/sandbox/_runtime/_job_runner.py

@@ -0,0 +1,111 @@
+"""The bash runner ``deploy_async`` injects to wrap a detached run.
+
+Written into the bundle as ``_sandbox_job_runner.sh`` and made the container's
+entry, so it — not the user's command — is PID 1's job. It runs the manifest's
+original ``[build].entry`` as a *subprocess* (not ``exec``) precisely so it
+regains control afterwards and can report the outcome: print the result sentinel
+to stdout, and best-effort POST the webhook.
+
+Bash, not python, because this is the layer that must work before anything is
+known about the workload. It assumes only what the base image guarantees: bash,
+python3 (for json/base64, so no dependency on a ``base64`` CLI flavour) and curl.
+"""
+
+from __future__ import annotations
+
+from snowflake.sandbox._runtime._protocol import _RESULT_SENTINEL
+
+__all__ = ["_SANDBOX_JOB_RUNNER"]
+
+
+# The ``__RESULT_SENTINEL__`` token below is substituted with _RESULT_SENTINEL at
+# import time so the sentinel prefix stays defined in exactly one place.
+_SANDBOX_JOB_RUNNER = r"""#!/bin/bash
+# Injected by deploy_async. Runs the inner entry, captures its exit code and
+# $SANDBOX_RESULT artifact, prints the result sentinel to stdout, and best-effort
+# POSTs the webhook. Preserves the inner exit code. No stage write and no
+# Snowflake calls: the webhook needs only egress.
+set -u
+
+SANDBOX_RESULT="${SANDBOX_RESULT:-/sandbox/result.json}"
+export SANDBOX_RESULT
+_SANDBOX_WEBHOOK_PAYLOAD="/tmp/_sandbox_webhook_payload.json"
+
+# Take the per-run nonce out of the environment before running the inner entry,
+# so the untrusted workload cannot read it and forge its own result sentinel.
+_SANDBOX_JOB_NONCE="${SANDBOX_JOB_NONCE:-}"
+unset SANDBOX_JOB_NONCE
+
+# The inner entry writes its structured result to $SANDBOX_RESULT; make sure its
+# parent dir exists (the default /sandbox is not present in the base image), and
+# is writable, so the inner write doesn't FileNotFoundError. Best-effort: if the
+# default location can't be created, fall back to a tmp path.
+if ! mkdir -p "$(dirname "$SANDBOX_RESULT")" 2>/dev/null; then
+    SANDBOX_RESULT="/tmp/_sandbox_result.json"
+    export SANDBOX_RESULT
+    mkdir -p "$(dirname "$SANDBOX_RESULT")" 2>/dev/null || true
+fi
+
+# Decode the JSON-encoded inner entry argv into the _inner array.
+mapfile -t _inner < <(printf '%s' "${SANDBOX_JOB_INNER_ENTRY:-[]}" | python3 -c '
+import json, sys
+for a in json.load(sys.stdin):
+    print(a)
+')
+
+if [ "${#_inner[@]}" -eq 0 ]; then
+    echo "sandbox-job-runner: empty SANDBOX_JOB_INNER_ENTRY" >&2
+    exit 2
+fi
+
+# Run the inner entry as a subprocess (not exec) so we regain control to emit
+# the sentinel + webhook after it completes.
+"${_inner[@]}"
+inner_exit=$?
+
+if [ "$inner_exit" -eq 0 ]; then
+    _status="succeeded"
+else
+    _status="failed"
+fi
+
+# Build the result JSON (parse $SANDBOX_RESULT if present, else {exit_code:N}),
+# print the sentinel line to stdout (the log channel the SDK scans), and write
+# the webhook payload to a file for the curl below.
+SANDBOX_JOB_STATUS="$_status" \
+SANDBOX_JOB_EXIT="$inner_exit" \
+SANDBOX_RESULT="$SANDBOX_RESULT" \
+SANDBOX_JOB_SENTINEL="__RESULT_SENTINEL__" \
+SANDBOX_JOB_NONCE="${_SANDBOX_JOB_NONCE:-}" \
+SANDBOX_JOB_WEBHOOK_PAYLOAD="$_SANDBOX_WEBHOOK_PAYLOAD" \
+python3 -c '
+import base64, json, os
+status = os.environ["SANDBOX_JOB_STATUS"]
+exit_code = int(os.environ["SANDBOX_JOB_EXIT"])
+result = None
+try:
+    with open(os.environ["SANDBOX_RESULT"]) as fh:
+        result = json.load(fh)
+except Exception:
+    result = None
+if not isinstance(result, dict):
+    result = {"exit_code": exit_code}
+core = {"status": status, "exit_code": exit_code, "result": result,
+        "nonce": os.environ.get("SANDBOX_JOB_NONCE", "")}
+print(os.environ["SANDBOX_JOB_SENTINEL"] + base64.b64encode(json.dumps(core).encode()).decode())
+webhook = dict(core)
+webhook["job_id"] = os.environ.get("SANDBOX_JOB_ID", "")
+with open(os.environ["SANDBOX_JOB_WEBHOOK_PAYLOAD"], "w") as fh:
+    json.dump(webhook, fh)
+'
+
+# Best-effort webhook POST (failures swallowed). Needs only egress.
+if [ -n "${SANDBOX_JOB_WEBHOOK:-}" ] && [ -f "$_SANDBOX_WEBHOOK_PAYLOAD" ]; then
+    curl -m 10 -s -X POST \
+        -H 'Content-Type: application/json' \
+        -d @"$_SANDBOX_WEBHOOK_PAYLOAD" \
+        "$SANDBOX_JOB_WEBHOOK" >/dev/null 2>&1 || true
+fi
+
+exit "$inner_exit"
+""".replace("__RESULT_SENTINEL__", _RESULT_SENTINEL)

snowflake/sandbox/_runtime/_protocol.py

@@ -0,0 +1,53 @@
+"""The values both sides of the sandbox boundary must agree on.
+
+Each of these is read by a *different process* from the one that writes it: the
+in-container programs in this package bake them into their source as literals,
+and the client-side modules use the same names to parse what comes back. Defining
+them once, here, is what keeps the two halves in step — the alternative is a
+literal repeated in a source string, where no test and no type checker can notice
+it drifting.
+
+They are therefore a **compatibility surface**, not internal names. A sandbox that
+was deployed by an older SDK is still running the older text; changing a value
+here stops the current client from recognising that container's output.
+"""
+
+from __future__ import annotations
+
+# The stdout sentinel the in-sandbox runner prints on completion. The payload
+# after the prefix is base64(json) where json = {status, exit_code, result}.
+_RESULT_SENTINEL = "__SANDBOX_RESULT__"
+
+# The mailbox file the daemon tails inside the container.
+_MAILBOX_PATH = "/tmp/sandbox_mailbox.jsonl"
+
+# The stdout sentinel the in-container daemon prints per reply. The payload is
+# ``<msg_id>__<nonce>__<base64(json(reply))>`` so a reply is matched to its message
+# id AND authenticated by the per-session nonce, which keeps the untrusted
+# workload from forging a reply for someone else's message.
+_REPLY_SENTINEL = "__SANDBOX_REPLY__"
+
+# Attribute the marker stamps onto a method so the generated session shim can
+# discover the cold-start hook by introspection (mirrors function-mode's
+# discovery of fn.__name__). Kept as a plain attribute flag — no wrapper class —
+# so the method is still a normal bound method on the user's instance.
+_ENTER_FLAG = "__sandbox_session_enter__"
+
+# The stdout sentinel the in-container filesystem helper prefixes its JSON with.
+_FS_SENTINEL = "__SBX_FS__"
+
+# The stdout sentinels the in-container inotify monitor prints: one READY line
+# once the watch is armed, then one prefixed JSON line per event.
+_WATCH_SENTINEL = "__SBX_WATCH__"
+_WATCH_READY = _WATCH_SENTINEL + "READY"
+
+# Raw inotify(7) mask bits (uapi/linux/inotify.h) -- hard-coded so the in-container
+# program needs no imports beyond the stdlib.
+_IN_MODIFY = 0x00000002
+_IN_CLOSE_WRITE = 0x00000008
+_IN_MOVED_FROM = 0x00000040
+_IN_MOVED_TO = 0x00000080
+_IN_CREATE = 0x00000100
+_IN_DELETE = 0x00000200
+_IN_ACCESS = 0x00000001
+_IN_OPEN = 0x00000020