sdxloop 0.1.0__py3-none-any.whl

sdxloop/sbx/cli.py

@@ -0,0 +1,210 @@
+"""Typed subprocess wrapper around the sbx binary.
+
+Every invocation injects ``--app-name`` (unless disabled) so sdxloop'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 sdxloop.errors import SbxError, SbxNotFoundError
+from sdxloop.sbx.models import ExecResult, SandboxInfo, SandboxSpec
+from sdxloop.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 = "sdxloop",
+        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,
+        )

sdxloop/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

sdxloop/sbx/pair.py

@@ -0,0 +1,125 @@
+"""SandboxPair — the core sdxloop 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 sdxloop.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()

sdxloop/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; ``sdxloop doctor`` warns
+on version mismatch.
+"""
+
+from __future__ import annotations
+
+import re
+
+from sdxloop.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

sdxloop/sbx/provision.py

@@ -0,0 +1,209 @@
+"""Provision the per-run sandbox pair: create, network policy, secrets, dirs.
+
+The credential split is enforced here:
+
+- **agent sandbox** gets only ``COPILOT_GITHUB_TOKEN`` (read from the host
+  environment), injected via ``sbx secret set-custom`` bound to the Copilot
+  API hosts — the value never enters the VM under the default ``proxy``
+  strategy.
+- **github sandbox** gets only ``GH_TOKEN`` via sbx's built-in ``github``
+  secret service (scoped to github.com hosts).
+
+The ``plain-env`` fallback strategy writes tokens to ``~/.sdxloop/env.sh``
+inside the sandbox (weaker: the value is visible in the VM) for environments
+where the experimental ``set-custom`` proxy rewriting is unavailable.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shlex
+from collections.abc import Callable, Mapping
+from pathlib import Path
+
+from sdxloop.config import Config
+from sdxloop.errors import ProvisionError, SbxError
+from sdxloop.events import EventBus
+from sdxloop.sbx.cli import SbxCLI
+from sdxloop.sbx.models import SandboxRole, SandboxSpec, SecretSpec
+from sdxloop.sbx.pair import SandboxPair
+from sdxloop.sbx.sandbox import ENV_FILE, EVENTS_DIR, JOBS_DIR, RESULTS_DIR, Sandbox
+
+logger = logging.getLogger(__name__)
+
+COPILOT_TOKEN_ENV = "COPILOT_GITHUB_TOKEN"
+GH_TOKEN_ENVS = ("GH_TOKEN", "GITHUB_TOKEN")
+
+# Hosts the Copilot token must reach: token exchange happens against
+# api.github.com, model/agent traffic against the copilot API hosts.
+AGENT_TOKEN_HOSTS = ("api.githubcopilot.com", "api.github.com")
+
+AGENT_ALLOW_DOMAINS = (
+    "api.githubcopilot.com",
+    "*.githubcopilot.com",
+    "api.github.com",
+    "github.com",
+    "objects.githubusercontent.com",  # copilot CLI runtime downloads
+    "raw.githubusercontent.com",
+)
+GITHUB_ALLOW_DOMAINS = (
+    "api.github.com",
+    "github.com",
+    "uploads.github.com",
+    "objects.githubusercontent.com",
+)
+
+PostCreate = Callable[[Sandbox, SandboxRole], None]
+
+
+def sandbox_name(run_id: str, role: SandboxRole) -> str:
+    return f"sdxloop-{run_id}-{role}"
+
+
+class Provisioner:
+    def __init__(
+        self,
+        cli: SbxCLI,
+        config: Config,
+        bus: EventBus | None = None,
+        *,
+        env: Mapping[str, str] | None = None,
+        post_create: PostCreate | None = None,
+    ) -> None:
+        self.cli = cli
+        self.config = config
+        self.bus = bus or EventBus()
+        self.env = os.environ if env is None else env
+        self.post_create = post_create
+
+    # -- spec construction -------------------------------------------------
+
+    def build_specs(self, run_id: str, workspace: Path) -> tuple[SandboxSpec, SandboxSpec]:
+        extra = tuple(self.config.sandbox.extra_allow_domains)
+        template = self.config.sandbox.template
+        agent = SandboxSpec(
+            name=sandbox_name(run_id, "agent"),
+            role="agent",
+            workspace=workspace,
+            template=template,
+            policy_allows=[*AGENT_ALLOW_DOMAINS, *extra],
+            secrets=[
+                SecretSpec(kind="custom", host=host, env=COPILOT_TOKEN_ENV)
+                for host in AGENT_TOKEN_HOSTS
+            ],
+        )
+        github = SandboxSpec(
+            name=sandbox_name(run_id, "github"),
+            role="github",
+            workspace=workspace,
+            template=template,
+            policy_allows=[*GITHUB_ALLOW_DOMAINS, *extra],
+            secrets=[SecretSpec(kind="service", service="github")],
+        )
+        return agent, github
+
+    # -- tokens ------------------------------------------------------------
+
+    def copilot_token(self) -> str:
+        token = self.env.get(COPILOT_TOKEN_ENV, "")
+        if not token:
+            raise ProvisionError(
+                f"{COPILOT_TOKEN_ENV} is not set on the host. Create a fine-grained PAT "
+                'with the "Copilot Requests" permission and export it.'
+            )
+        return token
+
+    def gh_token(self) -> str:
+        for name in GH_TOKEN_ENVS:
+            token = self.env.get(name, "")
+            if token:
+                return token
+        raise ProvisionError(
+            f"none of {', '.join(GH_TOKEN_ENVS)} are set on the host. Create a fine-grained "
+            "PAT with the repository permissions sdxloop should act with (e.g. issues:write, "
+            "contents:read) and export GH_TOKEN."
+        )
+
+    # -- provisioning ------------------------------------------------------
+
+    def ensure_pair(self, run_id: str, workspace: Path | None = None) -> SandboxPair:
+        workspace = workspace or self.config.sandbox.workspace
+        if workspace is None:
+            workspace = self.config.state_dir / "runs" / run_id / "workspace"
+        workspace = workspace.resolve()
+        workspace.mkdir(parents=True, exist_ok=True)
+
+        # Fail fast on missing tokens before creating any microVM.
+        tokens: dict[SandboxRole, str] = {
+            "agent": self.copilot_token(),
+            "github": self.gh_token(),
+        }
+
+        agent_spec, github_spec = self.build_specs(run_id, workspace)
+        created: list[Sandbox] = []
+        try:
+            sandboxes: dict[SandboxRole, Sandbox] = {}
+            for spec in (agent_spec, github_spec):
+                self.bus.emit("sandbox.provision_start", run_id, name=spec.name, role=spec.role)
+                self.cli.create(spec)
+                sandbox = Sandbox(self.cli, spec.name)
+                created.append(sandbox)
+                self._apply_policy(spec)
+                self._apply_secrets(spec, sandbox, tokens[spec.role])
+                sandbox.mkdirs(JOBS_DIR, RESULTS_DIR, EVENTS_DIR)
+                if self.post_create is not None:
+                    self.post_create(sandbox, spec.role)
+                sandboxes[spec.role] = sandbox
+                self.bus.emit("sandbox.ready", run_id, name=spec.name, role=spec.role)
+            return SandboxPair(
+                run_id,
+                agent=sandboxes["agent"],
+                github=sandboxes["github"],
+                keep=self.config.keep_sandboxes,
+            )
+        except Exception as exc:
+            for sandbox in created:
+                try:
+                    sandbox.rm()
+                except SbxError:
+                    logger.warning("rollback: failed to remove %s", sandbox.name, exc_info=True)
+            if isinstance(exc, ProvisionError):
+                raise
+            raise ProvisionError(f"provisioning run {run_id} failed: {exc}") from exc
+
+    def _apply_policy(self, spec: SandboxSpec) -> None:
+        for domain in spec.policy_allows:
+            self.cli.policy_allow(domain, sandbox=spec.name)
+
+    def _apply_secrets(self, spec: SandboxSpec, sandbox: Sandbox, token: str) -> None:
+        if self.config.secret_strategy == "plain-env":
+            self._apply_plain_env(spec, sandbox, token)
+            return
+        for secret in spec.secrets:
+            if secret.kind == "service":
+                assert secret.service is not None
+                self.cli.secret_set(secret.service, sandbox=spec.name, token=token)
+            else:
+                assert secret.host is not None and secret.env is not None
+                self.cli.secret_set_custom(
+                    host=secret.host,
+                    env=secret.env,
+                    value=token,
+                    sandbox=spec.name,
+                )
+
+    def _apply_plain_env(self, spec: SandboxSpec, sandbox: Sandbox, token: str) -> None:
+        """Weaker fallback: write tokens/env into ~/.sdxloop/env.sh in the VM."""
+        exports: dict[str, str] = dict(spec.persistent_env)
+        if spec.role == "agent":
+            exports[COPILOT_TOKEN_ENV] = token
+        else:
+            exports["GH_TOKEN"] = token
+            exports["GITHUB_TOKEN"] = token
+        lines = "".join(
+            f"export {key}={shlex.quote(value)}\n" for key, value in sorted(exports.items())
+        )
+        sandbox.exec(["mkdir", "-p", ENV_FILE.rsplit("/", 1)[0]])
+        sandbox.write_text(ENV_FILE, lines)
+        sandbox.exec(["chmod", "600", ENV_FILE])