sbxloop 0.2.0__py3-none-any.whl

sbxloop/sbx/cli.py

@@ -0,0 +1,236 @@
+"""Typed subprocess wrapper around the sbx binary.
+
+Every invocation injects ``--app-name`` (unless disabled) so sbxloop's
+sandboxes, policies, and secrets live in an isolated sbx application state,
+invisible to the user's interactive sbx usage.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+from collections.abc import Sequence
+
+from sbxloop.errors import SbxError, SbxNotFoundError
+from sbxloop.sbx.models import ExecResult, SandboxInfo, SandboxSpec
+from sbxloop.sbx.parse import parse_ls, parse_version
+
+_NOT_FOUND_MARKERS = ("not found", "no such sandbox", "does not exist", "unknown sandbox")
+
+
+class SbxCLI:
+    """Blocking, typed access to the sbx CLI."""
+
+    def __init__(
+        self,
+        binary: str = "sbx",
+        app_name: str | None = None,
+        default_timeout: float = 120.0,
+    ) -> None:
+        self.binary = binary
+        self.app_name = app_name
+        self.default_timeout = default_timeout
+
+    def argv(self, *args: str) -> list[str]:
+        prefix = [self.binary]
+        if self.app_name:
+            prefix += ["--app-name", self.app_name]
+        return prefix + list(args)
+
+    def run(
+        self,
+        *args: str,
+        timeout: float | None = None,
+        check: bool = True,
+        stdin: str | None = None,
+    ) -> ExecResult:
+        argv = self.argv(*args)
+        started = time.monotonic()
+        try:
+            proc = subprocess.run(
+                argv,
+                capture_output=True,
+                text=True,
+                timeout=timeout or self.default_timeout,
+                input=stdin,
+                check=False,
+            )
+        except FileNotFoundError as exc:
+            raise SbxNotFoundError(
+                f"sbx binary {self.binary!r} not found on PATH — install Docker Sandboxes "
+                "(https://docs.docker.com/ai/sandboxes/) and run `sbx login`",
+                argv=argv,
+            ) from exc
+        except subprocess.TimeoutExpired as exc:
+            raise SbxError(
+                f"sbx invocation timed out after {timeout or self.default_timeout:.0f}s",
+                argv=argv,
+                stderr=(exc.stderr or b"").decode() if isinstance(exc.stderr, bytes) else "",
+            ) from exc
+
+        result = ExecResult(
+            argv=argv,
+            returncode=proc.returncode,
+            stdout=proc.stdout,
+            stderr=proc.stderr,
+            duration_s=time.monotonic() - started,
+        )
+        if check and not result.ok:
+            raise self._error_for(result)
+        return result
+
+    def popen(self, *args: str) -> subprocess.Popen[str]:
+        """Start a streaming sbx invocation (stdout piped, line-buffered)."""
+        argv = self.argv(*args)
+        try:
+            return subprocess.Popen(
+                argv,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                bufsize=1,
+            )
+        except FileNotFoundError as exc:
+            raise SbxNotFoundError(
+                f"sbx binary {self.binary!r} not found on PATH",
+                argv=argv,
+            ) from exc
+
+    def _error_for(self, result: ExecResult) -> SbxError:
+        message = f"sbx command failed: {' '.join(result.argv[1:3])}"
+        lowered = result.stderr.lower()
+        cls = SbxNotFoundError if any(m in lowered for m in _NOT_FOUND_MARKERS) else SbxError
+        return cls(
+            message,
+            argv=result.argv,
+            returncode=result.returncode,
+            stderr=result.stderr,
+        )
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def create(self, spec: SandboxSpec) -> None:
+        args = ["create", f"--name={spec.name}"]
+        if spec.template:
+            args += ["--template", spec.template]
+        args += [spec.agent, str(spec.workspace)]
+        # Creating a microVM can take a while on first template pull.
+        self.run(*args, timeout=600.0)
+
+    def exec(
+        self,
+        name: str,
+        cmd: Sequence[str],
+        *,
+        timeout: float | None = None,
+    ) -> ExecResult:
+        """Run a command inside a sandbox; the inner exit code is returned,
+        but sbx-level failures (missing sandbox, daemon down) raise."""
+        result = self.run("exec", name, *cmd, timeout=timeout, check=False)
+        if not result.ok:
+            lowered = result.stderr.lower()
+            if any(m in lowered for m in _NOT_FOUND_MARKERS):
+                raise self._error_for(result)
+        return result
+
+    def cp(self, src: str, dst: str, *, timeout: float | None = None) -> None:
+        self.run("cp", src, dst, timeout=timeout)
+
+    def ls(self) -> list[SandboxInfo]:
+        return parse_ls(self.run("ls").stdout)
+
+    def stop(self, name: str) -> None:
+        self.run("stop", name)
+
+    def rm(self, name: str, *, force: bool = True) -> None:
+        args = ["rm"]
+        if force:
+            args.append("--force")
+        self.run(*args, name)
+
+    def version(self) -> str | None:
+        return parse_version(self.run("version", check=False).stdout)
+
+    # -- network policy ----------------------------------------------------
+
+    def policy_allow(self, domain: str, *, sandbox: str | None = None) -> None:
+        args = ["policy", "allow", "network", domain]
+        if sandbox:
+            args += ["--sandbox", sandbox]
+        self.run(*args)
+
+    def policy_check(self, host: str, *, sandbox: str | None = None) -> bool:
+        args = ["policy", "check", "network", host]
+        if sandbox:
+            args += ["--sandbox", sandbox]
+        result = self.run(*args, check=False)
+        if not result.ok:
+            return False
+        lowered = result.stdout.lower()
+        return not any(marker in lowered for marker in ("deny", "denied", "block"))
+
+    def policy_ls(self) -> str:
+        return self.run("policy", "ls").stdout
+
+    def policy_init(self, preset: str) -> None:
+        self.run("policy", "init", preset)
+
+    # -- secrets -----------------------------------------------------------
+
+    def secret_set(
+        self,
+        service: str,
+        *,
+        sandbox: str | None = None,
+        token: str | None = None,
+    ) -> None:
+        """Attach a built-in secret service (global with ``-g``, else scoped)."""
+        scope = [sandbox] if sandbox else ["-g"]
+        self.run("secret", "set", *scope, service, stdin=token)
+
+    def secret_set_custom(
+        self,
+        *,
+        host: str,
+        env: str,
+        value: str,
+        sandbox: str | None = None,
+    ) -> None:
+        scope = [sandbox] if sandbox else ["-g"]
+        self.run(
+            "secret",
+            "set-custom",
+            *scope,
+            "--host",
+            host,
+            "--env",
+            env,
+            "--value",
+            value,
+        )
+
+    def secret_rm(
+        self,
+        *,
+        service: str | None = None,
+        host: str | None = None,
+        env: str | None = None,
+        sandbox: str | None = None,
+    ) -> bool:
+        """Best-effort secret removal; returns whether sbx accepted it.
+
+        Used by the replace-on-exists flow: sbx refuses to overwrite an
+        existing secret, so provisioning removes and re-sets. Removal syntax
+        for custom secrets is not a stable documented API, hence best-effort
+        (callers keep the existing value when removal is rejected).
+        """
+        scope = [sandbox] if sandbox else ["-g"]
+        args = ["secret", "rm", *scope]
+        if service:
+            args.append(service)
+        else:
+            assert env is not None
+            if host:
+                args += ["--host", host]
+            args += ["--env", env]
+        return self.run(*args, check=False).ok

sbxloop/sbx/models.py

@@ -0,0 +1,83 @@
+"""Models for the sbx CLI layer."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+SandboxRole = Literal["agent", "github"]
+
+
+class SecretSpec(BaseModel):
+    """A secret to inject into a sandbox.
+
+    Either a built-in sbx secret *service* (e.g. ``github``, which injects
+    ``GH_TOKEN``/``GITHUB_TOKEN`` scoped to github.com hosts), or a *custom*
+    secret bound to one host + env var via ``sbx secret set-custom``.
+    Values are never stored on this model; they are passed at provision time.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    kind: Literal["service", "custom"]
+    service: str | None = None
+    host: str | None = None
+    env: str | None = None
+
+    @model_validator(mode="after")
+    def _check_kind(self) -> SecretSpec:
+        if self.kind == "service":
+            if not self.service:
+                raise ValueError("service secret requires a service name")
+            if self.host or self.env:
+                raise ValueError("service secret must not set host/env")
+        else:
+            if not self.host or not self.env:
+                raise ValueError("custom secret requires host and env")
+            if self.service:
+                raise ValueError("custom secret must not set service")
+        return self
+
+
+class SandboxSpec(BaseModel):
+    """Everything needed to create and configure one sandbox."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    role: SandboxRole
+    workspace: Path
+    agent: str = "shell"
+    template: str | None = None
+    policy_allows: list[str] = Field(default_factory=list)
+    secrets: list[SecretSpec] = Field(default_factory=list)
+    persistent_env: dict[str, str] = Field(default_factory=dict)
+
+
+class SandboxInfo(BaseModel):
+    """One row of ``sbx ls`` (parsed tolerantly; unknown columns dropped)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    agent: str | None = None
+    status: str | None = None
+    workspace: str | None = None
+
+
+class ExecResult(BaseModel):
+    """Outcome of one sbx invocation (or an exec'd command inside a sandbox)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    argv: list[str]
+    returncode: int
+    stdout: str
+    stderr: str
+    duration_s: float
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0

sbxloop/sbx/pair.py

@@ -0,0 +1,125 @@
+"""SandboxPair — the core sbxloop primitive — and its cleanup guarantees.
+
+A run's pair consists of the agent sandbox (COPILOT_GITHUB_TOKEN only) and
+the github-ops sandbox (GH_TOKEN only). The pair is a context manager whose
+exit stops and removes both sandboxes unless ``keep`` is set; a process-wide
+registry additionally cleans up on interpreter exit and on SIGINT/SIGTERM,
+so aborted runs do not leak microVMs.
+"""
+
+from __future__ import annotations
+
+import atexit
+import contextlib
+import logging
+import signal
+import threading
+import types
+from typing import Any
+
+from sbxloop.sbx.sandbox import Sandbox
+
+logger = logging.getLogger(__name__)
+
+
+class SandboxPair:
+    def __init__(
+        self,
+        run_id: str,
+        agent: Sandbox,
+        github: Sandbox,
+        *,
+        keep: bool = False,
+    ) -> None:
+        self.run_id = run_id
+        self.agent = agent
+        self.github = github
+        self.keep = keep
+        self._cleaned = False
+
+    def __enter__(self) -> SandboxPair:
+        cleanup_registry.register(self)
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: types.TracebackType | None,
+    ) -> None:
+        if self.keep:
+            cleanup_registry.unregister(self)
+        else:
+            self.cleanup()
+
+    def cleanup(self) -> None:
+        """Stop and remove both sandboxes. Idempotent, best-effort per sandbox."""
+        if self._cleaned:
+            return
+        self._cleaned = True
+        cleanup_registry.unregister(self)
+        for sandbox in (self.agent, self.github):
+            try:
+                sandbox.stop()
+            except Exception:
+                logger.warning("failed to stop sandbox %s", sandbox.name, exc_info=True)
+            try:
+                sandbox.rm()
+            except Exception:
+                logger.warning("failed to remove sandbox %s", sandbox.name, exc_info=True)
+
+
+class CleanupRegistry:
+    """Process-wide safety net: cleans registered pairs on exit and signals."""
+
+    def __init__(self) -> None:
+        self._pairs: list[SandboxPair] = []
+        self._lock = threading.Lock()
+        self._installed = False
+        self._previous: dict[int, Any] = {}
+
+    def register(self, pair: SandboxPair) -> None:
+        with self._lock:
+            if pair not in self._pairs:
+                self._pairs.append(pair)
+            self._install_handlers()
+
+    def unregister(self, pair: SandboxPair) -> None:
+        with self._lock:
+            if pair in self._pairs:
+                self._pairs.remove(pair)
+
+    def cleanup_all(self) -> None:
+        with self._lock:
+            pairs = list(self._pairs)
+        for pair in pairs:
+            try:
+                pair.cleanup()
+            except Exception:
+                logger.warning("cleanup failed for run %s", pair.run_id, exc_info=True)
+
+    def _install_handlers(self) -> None:
+        if self._installed:
+            return
+        self._installed = True
+        atexit.register(self.cleanup_all)
+        if threading.current_thread() is not threading.main_thread():
+            return  # signal handlers can only be installed from the main thread
+        for signum in (signal.SIGINT, signal.SIGTERM):
+            # ValueError/OSError: not installable in this context (e.g. no tty)
+            with contextlib.suppress(ValueError, OSError):
+                self._previous[signum] = signal.signal(signum, self._handle_signal)
+
+    def _handle_signal(self, signum: int, frame: types.FrameType | None) -> None:
+        logger.info("signal %s received; cleaning up sandboxes", signum)
+        self.cleanup_all()
+        previous = self._previous.get(signum)
+        if callable(previous):
+            previous(signum, frame)
+        elif signum == signal.SIGINT:
+            raise KeyboardInterrupt
+        else:
+            raise SystemExit(128 + signum)
+
+
+cleanup_registry = CleanupRegistry()

sbxloop/sbx/parse.py

@@ -0,0 +1,67 @@
+"""Tolerant parsers for sbx CLI text output.
+
+The sbx binary is proprietary and its output format is not a stable API, so
+parsing is column-header-driven and deliberately forgiving: unknown columns
+are ignored and malformed lines are skipped rather than raising. Formats are
+pinned by fixture tests captured from sbx v0.35.x; ``sbxloop doctor`` warns
+on version mismatch.
+"""
+
+from __future__ import annotations
+
+import re
+
+from sbxloop.sbx.models import SandboxInfo
+
+_VERSION_RE = re.compile(r"(\d+\.\d+\.\d+)")
+
+
+_CELL_SPLIT = re.compile(r"\s{2,}")
+
+
+def parse_columns(text: str) -> list[dict[str, str]]:
+    """Parse a left-aligned column table using the header row for names.
+
+    Cells are split on runs of two or more spaces, which survives cells that
+    overflow their column width (unlike offset slicing). Rows with fewer
+    cells than headers get empty strings; extra cells are dropped.
+    """
+    lines = [line.rstrip() for line in text.splitlines() if line.strip()]
+    if not lines:
+        return []
+    headers = [h.lower() for h in _CELL_SPLIT.split(lines[0].strip())]
+    if not headers:
+        return []
+
+    rows: list[dict[str, str]] = []
+    for line in lines[1:]:
+        cells = _CELL_SPLIT.split(line.strip())
+        row = {
+            header: cells[i].strip() if i < len(cells) else "" for i, header in enumerate(headers)
+        }
+        rows.append(row)
+    return rows
+
+
+def parse_ls(text: str) -> list[SandboxInfo]:
+    """Parse ``sbx ls`` output into SandboxInfo rows (nameless rows skipped)."""
+    infos: list[SandboxInfo] = []
+    for row in parse_columns(text):
+        name = row.get("name", "")
+        if not name:
+            continue
+        infos.append(
+            SandboxInfo(
+                name=name,
+                agent=row.get("agent") or None,
+                status=row.get("status") or None,
+                workspace=row.get("workspace") or None,
+            )
+        )
+    return infos
+
+
+def parse_version(text: str) -> str | None:
+    """Extract a semver from ``sbx version`` output, if present."""
+    match = _VERSION_RE.search(text)
+    return match.group(1) if match else None