drukbox-python-sdk 0.0.1__tar.gz

drukbox_python_sdk-0.0.1/.github/workflows/on-main-merge.yml

@@ -0,0 +1,47 @@
+name: Validate On Main Merge
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: main-merge-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    name: Run Checks
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          version: "0.10.9"
+
+      - name: Sync dependencies
+        run: uv sync --dev
+
+      - name: Run Ruff
+        run: |
+          uv run ruff check
+          uv run ruff format --check
+
+      - name: Run Pyright
+        run: uv run pyright
+
+      - name: Run Tests
+        run: uv run pytest -v

drukbox_python_sdk-0.0.1/.github/workflows/on-pull-request.yml

@@ -0,0 +1,45 @@
+name: Validate On Pull Request
+
+on:
+  pull_request:
+
+concurrency:
+  group: pull-request-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    name: Run Checks
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          version: "0.10.9"
+
+      - name: Sync dependencies
+        run: uv sync --dev
+
+      - name: Run Ruff
+        run: |
+          uv run ruff check
+          uv run ruff format --check
+
+      - name: Run Pyright
+        run: uv run pyright
+
+      - name: Run Tests
+        run: uv run pytest -v

drukbox_python_sdk-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release
+
+on:
+  release:
+    types:
+      - published
+  workflow_dispatch:
+
+concurrency:
+  group: release-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/drukbox-python-sdk/
+    permissions:
+      contents: read
+      id-token: write  # required for PyPI Trusted Publisher OIDC exchange
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          version: "0.10.9"
+
+      - name: Build wheel + sdist
+        run: uv build --out-dir dist
+
+      - name: Validate distribution metadata
+        run: uv run --with twine twine check --strict dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

drukbox_python_sdk-0.0.1/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+uv.lock
+.venv/
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.coverage
+htmlcov/
+dist/
+build/
+
+# IDEs
+.idea/
+.vscode/

drukbox_python_sdk-0.0.1/AGENTS.md

@@ -0,0 +1,59 @@
+# AGENTS.md
+
+Guide for AI agents working in `drukbox-python-sdk`.
+
+## What This Project Is
+
+`drukbox-python-sdk` is the async Python SDK for Drukbox's HTTP host API:
+a small client library that speaks HTTP, parses typed records, and raises
+typed errors.
+
+The package name is `drukbox-python-sdk`; the import package is
+`drukbox_sdk`. Public API names use `Sandbox*` because the Drukbox domain
+object is a sandbox host.
+
+## Boundaries
+
+- Keep this repo focused on HTTP client behavior, typed records, and typed
+  exceptions.
+- Do not add SSH session management, file transfer, command execution,
+  Tailscale management, VM provider logic, or service-side lifecycle behavior.
+- Prefer explicit Drukbox wire contracts over broad defensive parsing.
+- Keep dependencies light; justify any new runtime dependency before adding it.
+
+## Layout
+
+```text
+src/drukbox_sdk/
+  api.py          # SandboxAPI, records, parsers, HTTP request handling
+  exceptions.py   # SDK exception hierarchy
+  __init__.py     # Public exports
+tests/
+  test_api.py     # respx-backed SDK contract tests
+```
+
+## Development Commands
+
+```bash
+uv sync
+uv run ruff check
+uv run ruff format --check
+uv run pyright
+uv run pytest
+```
+
+Run the full set when changing Python behavior. For documentation-only edits,
+grep for any names you changed and state in the summary that tests were not
+run.
+
+## Working Rules
+
+- Read this file, `pyproject.toml`, and the relevant source/tests before
+  editing.
+- Follow the repo's Python 3.11+ typing style and keep public APIs typed.
+- Match the existing async `httpx` style and strict typing.
+- Add focused tests for behavior changes.
+- Keep docs concise and repo-specific. Avoid references to downstream
+  consumers unless the user asks for them.
+- Preserve user changes in the worktree; do not clean or rewrite unrelated
+  files.

drukbox_python_sdk-0.0.1/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: drukbox-python-sdk
+Version: 0.0.1
+Summary: Async Python client for Drukbox.
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28
+Description-Content-Type: text/markdown
+
+# drukbox-python-sdk
+
+Async Python client for the [Drukbox] host API.
+
+The SDK provisions sandbox VMs, reads host state, deletes hosts, and
+returns the SSH connection details a caller needs. It speaks HTTP only:
+SSH sessions, file transfer, command execution, and retry orchestration
+belong in the caller.
+
+## Install
+
+```bash
+pip install drukbox-python-sdk
+uv add drukbox-python-sdk
+```
+
+## Usage
+
+```python
+from drukbox_sdk import SandboxAPI
+
+sandbox = SandboxAPI(
+    base_url="https://sandbox.internal.ts.net",
+    token="...",
+)
+
+try:
+    host = await sandbox.create_host(
+        image="ghcr.io/drukbox/sandbox:abc123",
+        env={"FOO": "bar"},
+        idempotency_key="agent-run-42",
+    )
+    # Use host.external_ssh_host (or host.internal_ssh_host when the
+    # service runs with Tailscale enabled), host.external_ssh_port,
+    # and host.known_hosts with asyncssh or another SSH client.
+finally:
+    await sandbox.delete_host(host.id)
+    await sandbox.aclose()
+```
+
+`create_host` blocks until the host is `active` — typically ~10–30s, up to a
+few minutes worst case. The SDK's default `timeout` (300s) covers this. Pass
+an `idempotency_key` for retry safety: a retry with the same key after a
+successful provision returns the original host instead of creating a duplicate.
+
+`SandboxAPI.from_env(prefix="SANDBOX_")` reads
+`SANDBOX_SERVICE_URL`, `SANDBOX_SERVICE_TOKEN`, and optional
+`SANDBOX_SERVICE_TIMEOUT`.
+
+## Contract
+
+Public exports live in `drukbox_sdk`:
+
+- `SandboxAPI`
+- `SandboxHost`
+- `SandboxAPIError` and typed subclasses for auth, not found, conflict,
+  unavailable, and unclassified response errors
+
+Supported host operations:
+
+- `create_host`
+- `get_host`
+- `attach`
+- `list_hosts`
+- `delete_host`
+- `aclose`
+
+`create_host` supports the service's optional `image`, `env`, `expires_at`,
+and `Idempotency-Key` inputs.
+
+The SDK does not mint Tailscale auth keys, manage ACLs, establish SSH,
+provision Linux users, transfer files, or run remote commands.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check
+uv run ruff format --check
+uv run pyright
+uv run pytest
+```
+
+Tests use `respx` to fake the Drukbox HTTP API. They do not need a
+real network, VM provider, or Drukbox service.
+
+[Drukbox]: https://github.com/clawhaven/drukbox

drukbox_python_sdk-0.0.1/README.md

@@ -0,0 +1,87 @@
+# drukbox-python-sdk
+
+Async Python client for the [Drukbox] host API.
+
+The SDK provisions sandbox VMs, reads host state, deletes hosts, and
+returns the SSH connection details a caller needs. It speaks HTTP only:
+SSH sessions, file transfer, command execution, and retry orchestration
+belong in the caller.
+
+## Install
+
+```bash
+pip install drukbox-python-sdk
+uv add drukbox-python-sdk
+```
+
+## Usage
+
+```python
+from drukbox_sdk import SandboxAPI
+
+sandbox = SandboxAPI(
+    base_url="https://sandbox.internal.ts.net",
+    token="...",
+)
+
+try:
+    host = await sandbox.create_host(
+        image="ghcr.io/drukbox/sandbox:abc123",
+        env={"FOO": "bar"},
+        idempotency_key="agent-run-42",
+    )
+    # Use host.external_ssh_host (or host.internal_ssh_host when the
+    # service runs with Tailscale enabled), host.external_ssh_port,
+    # and host.known_hosts with asyncssh or another SSH client.
+finally:
+    await sandbox.delete_host(host.id)
+    await sandbox.aclose()
+```
+
+`create_host` blocks until the host is `active` — typically ~10–30s, up to a
+few minutes worst case. The SDK's default `timeout` (300s) covers this. Pass
+an `idempotency_key` for retry safety: a retry with the same key after a
+successful provision returns the original host instead of creating a duplicate.
+
+`SandboxAPI.from_env(prefix="SANDBOX_")` reads
+`SANDBOX_SERVICE_URL`, `SANDBOX_SERVICE_TOKEN`, and optional
+`SANDBOX_SERVICE_TIMEOUT`.
+
+## Contract
+
+Public exports live in `drukbox_sdk`:
+
+- `SandboxAPI`
+- `SandboxHost`
+- `SandboxAPIError` and typed subclasses for auth, not found, conflict,
+  unavailable, and unclassified response errors
+
+Supported host operations:
+
+- `create_host`
+- `get_host`
+- `attach`
+- `list_hosts`
+- `delete_host`
+- `aclose`
+
+`create_host` supports the service's optional `image`, `env`, `expires_at`,
+and `Idempotency-Key` inputs.
+
+The SDK does not mint Tailscale auth keys, manage ACLs, establish SSH,
+provision Linux users, transfer files, or run remote commands.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check
+uv run ruff format --check
+uv run pyright
+uv run pytest
+```
+
+Tests use `respx` to fake the Drukbox HTTP API. They do not need a
+real network, VM provider, or Drukbox service.
+
+[Drukbox]: https://github.com/clawhaven/drukbox

drukbox_python_sdk-0.0.1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "drukbox-python-sdk"
+version = "0.0.1"
+description = "Async Python client for Drukbox."
+readme = "README.md"
+# Tracks the lowest Python any current consumer supports. Bump only
+# when a real consumer needs a 3.12+ feature.
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.28",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/drukbox_sdk"]
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.25",
+    "respx>=0.23",
+    "ruff>=0.9",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.format]
+line-ending = "lf"
+quote-style = "double"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.pyright]
+include = ["src", "tests"]
+pythonVersion = "3.11"
+typeCheckingMode = "strict"
+reportMissingTypeStubs = false

drukbox_python_sdk-0.0.1/src/drukbox_sdk/__init__.py

@@ -0,0 +1,31 @@
+"""Async Python client for Drukbox.
+
+Public surface — anything not re-exported here is an implementation
+detail and may change without notice.
+"""
+
+from .api import (
+    SandboxAPI,
+    SandboxHost,
+)
+from .exceptions import (
+    SandboxAPIError,
+    SandboxAuthError,
+    SandboxConflictError,
+    SandboxNotFoundError,
+    SandboxProvisioningError,
+    SandboxResponseError,
+    SandboxUnavailableError,
+)
+
+__all__ = [
+    "SandboxAPI",
+    "SandboxAPIError",
+    "SandboxAuthError",
+    "SandboxConflictError",
+    "SandboxHost",
+    "SandboxNotFoundError",
+    "SandboxProvisioningError",
+    "SandboxResponseError",
+    "SandboxUnavailableError",
+]

drukbox_python_sdk-0.0.1/src/drukbox_sdk/api.py

@@ -0,0 +1,313 @@
+"""Async HTTP client for Drukbox.
+
+The service is the canonical owner of host provisioning, Tailscale
+auth-key minting and device discovery, exe.dev VM lifecycle, and host
+teardown. This SDK is a thin wrapper around its HTTP API; everything
+that needs to happen *inside* a provisioned VM (SSH, file transfer,
+command execution) is the caller's responsibility — the SDK hands back
+the host record with ``external_ssh_host`` / ``external_ssh_port`` /
+``internal_ssh_host`` / ``known_hosts`` and stops there.
+
+Usage::
+
+    from drukbox_sdk import SandboxAPI
+
+    sandbox = SandboxAPI(
+        base_url="https://sandbox.internal.ts.net",
+        token="...",
+    )
+    try:
+        host = await sandbox.create_host(
+            image="ghcr.io/.../sandbox:abc123",
+            idempotency_key="agent-run-42",
+        )
+        # ... use host.external_ssh_host etc. with asyncssh ...
+    finally:
+        await sandbox.delete_host(host.id)
+        await sandbox.aclose()
+
+For env-backed config use :meth:`SandboxAPI.from_env`.
+"""
+
+import asyncio
+import os
+import uuid
+from dataclasses import dataclass, fields
+from datetime import datetime
+from typing import Any, Self
+
+import httpx
+
+from .exceptions import (
+    SandboxAuthError,
+    SandboxConflictError,
+    SandboxNotFoundError,
+    SandboxProvisioningError,
+    SandboxResponseError,
+    SandboxUnavailableError,
+)
+
+# Explicit pool budget. The httpx defaults (100 / 20) are plenty for
+# the SDK's traffic shape (a handful of provisioning calls per agent
+# run), but keeping the values visible at the import site means a
+# future bump in concurrency does not silently exhaust the pool.
+_SANDBOX_HTTP_LIMITS = httpx.Limits(
+    max_connections=20,
+    max_keepalive_connections=5,
+)
+
+
+@dataclass(frozen=True)
+class SandboxHost:
+    """Snapshot of a provisioned host as returned by the service.
+
+    The shape mirrors the Drukbox ``Host`` schema. ``external_ssh_host``
+    is always populated by the VM provider; ``internal_ssh_host`` is
+    populated only when the service runs with Tailscale enabled (MagicDNS
+    name on the tailnet). The internal path is always reached on port 22
+    by Tailscale convention, so there is no ``internal_ssh_port``.
+    Callers pick whichever path they can reach and dial it themselves —
+    this SDK doesn't speak SSH.
+    """
+
+    id: str
+    name: str
+    status: str
+    provider: str
+    image: str
+    external_ssh_host: str
+    external_ssh_port: int
+    internal_ssh_host: str | None
+    known_hosts: str
+    tailscale_device_id: str | None
+    last_error: str
+    created_at: str
+    updated_at: str
+    activated_at: str | None
+    expires_at: str | None
+
+
+_SANDBOX_HOST_FIELDS = {field.name for field in fields(SandboxHost)}
+
+
+def _parse_sandbox_host(data: dict[str, Any]) -> SandboxHost:
+    """Build a :class:`SandboxHost` picking only known fields.
+
+    Defensive against the service adding new fields — those flow
+    through harmlessly without breaking the SDK on the unsuspecting
+    caller's side.
+    """
+
+    return SandboxHost(**{key: data[key] for key in _SANDBOX_HOST_FIELDS})
+
+
+class SandboxAPI:
+    """Async client for Drukbox.
+
+    Construct one per process (or one per consuming subsystem) and
+    reuse it. The internal ``httpx.AsyncClient`` is loop-aware: if the
+    client gets used from a different event loop than the one it was
+    created on (e.g. an ASGI request handler vs. a CLI command vs. a
+    cron job all using the same SDK instance via module-level state),
+    it transparently rebinds to the running loop on next use. This is
+    a known foot-gun with long-lived ``httpx.AsyncClient`` instances;
+    we handle it here so callers don't have to.
+
+    Always call :meth:`aclose` during graceful shutdown.
+    """
+
+    def __init__(self, *, base_url: str, token: str, timeout: float = 300.0) -> None:
+        # The default covers the worst-case server-side budget for inline
+        # `POST /hosts`: Tailscale device discovery (~180s) + ssh-keyscan
+        # retries (~30s) + provider + network jitter. A tighter timeout that
+        # fires while the server is still provisioning leaves an orphan VM
+        # on the provider side until the janitor reaps it.
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self._client: httpx.AsyncClient | None = None
+        # The bound event loop is recorded the first time a client is
+        # created. httpx clients are tied to the loop they were
+        # instantiated on; reusing one across loops raises at request
+        # time. Track the loop here so cross-loop reuse rebinds
+        # instead of crashing.
+        self._client_loop: asyncio.AbstractEventLoop | None = None
+        # Concurrent first-callers can both observe ``self._client is
+        # None`` and race to create two clients, leaking one. Serialize
+        # the initialization path with a lazy-allocated lock.
+        self._client_lock: asyncio.Lock | None = None
+
+    @classmethod
+    def from_env(cls, *, prefix: str = "SANDBOX_") -> Self:
+        """Build from ``{prefix}SERVICE_URL`` / ``{prefix}SERVICE_TOKEN``
+        / ``{prefix}SERVICE_TIMEOUT`` env vars.
+
+        Convenience for callers that don't want to thread settings
+        through their own config layer. The constructor stays the
+        canonical entry point — this just reads the env once.
+        """
+
+        url = os.environ[f"{prefix}SERVICE_URL"]
+        token = os.environ[f"{prefix}SERVICE_TOKEN"]
+        timeout = float(os.environ.get(f"{prefix}SERVICE_TIMEOUT", "300"))
+        return cls(base_url=url, token=token, timeout=timeout)
+
+    # ------------------------------------------------------------------
+    # Host lifecycle
+    # ------------------------------------------------------------------
+
+    async def create_host(
+        self,
+        *,
+        env: dict[str, str] | None = None,
+        expires_at: datetime | None = None,
+        idempotency_key: str | None = None,
+        image: str | None = None,
+    ) -> SandboxHost:
+        """Provision a new host.
+
+        The service provisions inline; this call blocks until the host
+        is ``active`` (~10-30s typical, up to a few minutes in the worst
+        case). Raises :class:`SandboxProvisioningError` if the service
+        reaches its own provisioning failure (502); raises
+        :class:`SandboxResponseError` on transport failure or unexpected
+        status.
+
+        ``idempotency_key`` is sent as the service's ``Idempotency-Key``
+        header. Useful for retry safety on flaky networks — a retry with
+        the same key after a successful provision returns the original
+        host instead of creating a duplicate.
+        """
+
+        payload: dict[str, Any] = {}
+        if env is not None:
+            payload["env"] = env
+        if expires_at is not None:
+            payload["expires_at"] = expires_at.isoformat()
+        if image is not None:
+            payload["image"] = image
+
+        headers: dict[str, str] = {}
+        if idempotency_key is not None:
+            headers["Idempotency-Key"] = idempotency_key
+
+        data = await self._request("POST", "/hosts", json=payload, headers=headers)
+        assert isinstance(data, dict)
+        return _parse_sandbox_host(data)
+
+    async def get_host(self, host_id: uuid.UUID | str) -> SandboxHost:
+        data = await self._request("GET", f"/hosts/{host_id}")
+        assert isinstance(data, dict)
+        return _parse_sandbox_host(data)
+
+    async def attach(self, host_id: uuid.UUID | str) -> SandboxHost:
+        """Alias for :meth:`get_host` that reads better at call sites
+        coming back to a host they provisioned in an earlier process.
+
+        Same wire call; the rename only exists so a restart-resumption
+        path doesn't have to start with ``get_host`` (which would read
+        like "go discover a host" when the intent is "reattach to one
+        I already know about").
+        """
+
+        return await self.get_host(host_id)
+
+    async def list_hosts(self) -> list[SandboxHost]:
+        data = await self._request("GET", "/hosts")
+        assert isinstance(data, list)
+        return [_parse_sandbox_host(item) for item in data]
+
+    async def delete_host(self, host_id: uuid.UUID | str) -> None:
+        await self._request("DELETE", f"/hosts/{host_id}")
+
+    async def aclose(self) -> None:
+        if self._client is None:
+            return
+        await self._client.aclose()
+        self._client = None
+        self._client_loop = None
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        headers: dict[str, str] | None = None,
+        json: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | list[Any]:
+        client = await self._get_client()
+        request_headers = {
+            "Authorization": f"Bearer {self.token}",
+            "Accept": "application/json",
+        }
+        if headers is not None:
+            request_headers.update(headers)
+
+        try:
+            response = await client.request(
+                method,
+                f"{self.base_url}{path}",
+                json=json,
+                headers=request_headers,
+                timeout=self.timeout,
+            )
+        except httpx.RequestError as exc:
+            raise SandboxUnavailableError(f"Sandbox service transport failed: {exc}") from exc
+
+        if response.status_code == 204:
+            return {}
+
+        try:
+            json_response = response.json()
+        except ValueError as exc:
+            raise SandboxResponseError("Sandbox service returned non-JSON output") from exc
+
+        if response.status_code in {401, 403}:
+            raise SandboxAuthError(json_response.get("detail", "auth failed"))
+
+        if response.status_code == 404:
+            raise SandboxNotFoundError(json_response.get("detail", "not found"))
+
+        if response.status_code == 409:
+            raise SandboxConflictError(json_response.get("detail", "conflict"))
+
+        if response.status_code == 502:
+            raise SandboxProvisioningError(json_response.get("detail", "provisioning failed"))
+
+        if response.status_code == 503:
+            raise SandboxUnavailableError(json_response.get("detail", "service unavailable"))
+
+        if response.status_code >= 400:
+            raise SandboxResponseError(json_response.get("detail", "error"))
+        return json_response
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        running_loop = asyncio.get_running_loop()
+        # Fast-path: client exists and is bound to the current loop.
+        if self._client is not None and self._client_loop is running_loop:
+            return self._client
+        # Slow-path: either no client yet, or the client is bound to a
+        # stale loop (e.g. fixture teardown). Serialize through the
+        # lock.
+        if self._client_lock is None:
+            self._client_lock = asyncio.Lock()
+        async with self._client_lock:
+            # Re-check under the lock; another coroutine may have raced
+            # ahead.
+            if self._client is not None and self._client_loop is running_loop:
+                return self._client
+            if self._client is not None:
+                # Stale-loop client: closing on its own loop is unsafe,
+                # so drop the reference and rely on GC. httpx will emit
+                # an "unclosed client" warning, which is the correct
+                # signal that the process-level lifecycle hook
+                # (e.g. ASGI lifespan) didn't run on the previous loop.
+                self._client = None
+                self._client_loop = None
+            self._client = httpx.AsyncClient(limits=_SANDBOX_HTTP_LIMITS)
+            self._client_loop = running_loop
+            return self._client

drukbox_python_sdk-0.0.1/src/drukbox_sdk/exceptions.py

@@ -0,0 +1,54 @@
+"""Typed errors for Drukbox interactions.
+
+The hierarchy lets callers distinguish "I can't reach the service at
+all" from "the service told me no" and lets them narrow on common HTTP
+shapes (auth, not-found, conflict) without parsing status codes
+themselves.
+"""
+
+
+class SandboxUnavailableError(RuntimeError):
+    """Sandbox service is unreachable or transiently broken.
+
+    Raised for both transport-level failures (DNS, connection refused,
+    TLS, timeouts) and 503 responses from the service itself. Both
+    signal "retry with backoff" rather than "the request was rejected."
+    Distinct from :class:`SandboxAPIError`, which represents the
+    service deliberately refusing a request.
+    """
+
+
+class SandboxAPIError(RuntimeError):
+    """Base for any error the sandbox service returned via HTTP."""
+
+
+class SandboxAuthError(SandboxAPIError):
+    """401/403 from the sandbox service. Token wrong, missing, or revoked."""
+
+
+class SandboxNotFoundError(SandboxAPIError):
+    """404 — the resource ID isn't known to the sandbox service.
+
+    Common cause during host-attach paths: the host was already torn
+    down by a sibling worker / housekeeping sweep.
+    """
+
+
+class SandboxConflictError(SandboxAPIError):
+    """409 — the operation conflicts with the current state.
+
+    e.g. provisioning a Linux user on a host that already has one with
+    the same name.
+    """
+
+
+class SandboxProvisioningError(SandboxAPIError):
+    """502 — the service tried to provision the host and the provider,
+    Tailscale, or ssh-keyscan step failed. The host row stays in
+    ``error`` state on the service side; call :meth:`delete_host` to
+    release any partial provider state.
+    """
+
+
+class SandboxResponseError(SandboxAPIError):
+    """Everything else the service returned that the SDK doesn't classify."""

drukbox_python_sdk-0.0.1/tests/test_api.py

@@ -0,0 +1,419 @@
+"""SDK-only tests against a fake httpx server via respx.
+
+The SDK's contract is "speak HTTP to the sandbox service correctly,
+parse the responses into typed records, raise typed errors on
+non-success codes." No SSH, no provisioning, no real network. respx
+gives us a controllable transport layer so every test stays in-process.
+"""
+
+# Tests legitimately read the SDK's internal _client / _client_loop to
+# verify lifecycle + loop-binding behaviour. Suppressing here rather
+# than promoting them to public API or adding test-only accessors.
+# pyright: reportPrivateUsage=false
+
+import asyncio
+from collections.abc import AsyncGenerator
+from datetime import UTC, datetime
+from typing import Any
+from uuid import uuid4
+
+import httpx
+import pytest
+import respx
+
+from drukbox_sdk import (
+    SandboxAPI,
+    SandboxAuthError,
+    SandboxConflictError,
+    SandboxHost,
+    SandboxNotFoundError,
+    SandboxProvisioningError,
+    SandboxResponseError,
+    SandboxUnavailableError,
+)
+
+BASE_URL = "https://sandbox.test"
+
+
+def _host_payload(**overrides: Any) -> dict[str, Any]:
+    """One canonical host payload used across tests; overrides per case."""
+
+    payload: dict[str, Any] = {
+        "id": str(uuid4()),
+        "name": "host-abc",
+        "status": "provisioning",
+        "provider": "exe",
+        "image": "ghcr.io/drukbox/sandbox:test",
+        "external_ssh_host": "203.0.113.42",
+        "external_ssh_port": 22,
+        "internal_ssh_host": "host-abc.example.ts.net",
+        "known_hosts": "ssh-ed25519 AAAA...\n",
+        "tailscale_device_id": None,
+        "last_error": "",
+        "created_at": "2026-05-28T12:00:00+00:00",
+        "updated_at": "2026-05-28T12:00:00+00:00",
+        "activated_at": None,
+        "expires_at": None,
+    }
+    payload.update(overrides)
+    return payload
+
+
+@pytest.fixture
+async def api() -> AsyncGenerator[SandboxAPI, None]:
+    """Fresh SandboxAPI per test. Closed via finalizer."""
+
+    client = SandboxAPI(base_url=BASE_URL, token="t-test", timeout=5.0)
+    yield client
+    await client.aclose()
+
+
+# ---------------------------------------------------------------------------
+# Happy paths
+# ---------------------------------------------------------------------------
+
+
+@respx.mock
+async def test_create_host_posts_payload_and_returns_parsed_host(api: SandboxAPI):
+    expires_at = datetime(2026, 6, 1, 12, 0, tzinfo=UTC)
+    payload = _host_payload(expires_at=expires_at.isoformat())
+    route = respx.post(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(202, json=payload),
+    )
+
+    host = await api.create_host(
+        image="ghcr.io/drukbox/sandbox:test",
+        env={"FOO": "bar"},
+        expires_at=expires_at,
+        idempotency_key="agent-run-42",
+    )
+
+    assert route.called
+    sent = route.calls.last.request
+    assert sent.headers["Authorization"] == "Bearer t-test"
+    assert sent.headers["Accept"] == "application/json"
+    assert sent.headers["Idempotency-Key"] == "agent-run-42"
+    body = sent.content.decode()
+    assert '"image":"ghcr.io/drukbox/sandbox:test"' in body
+    assert '"env":{"FOO":"bar"}' in body
+    assert f'"expires_at":"{expires_at.isoformat()}"' in body
+
+    assert isinstance(host, SandboxHost)
+    assert host.id == payload["id"]
+    assert host.external_ssh_host == payload["external_ssh_host"]
+    assert host.external_ssh_port == payload["external_ssh_port"]
+    assert host.internal_ssh_host == payload["internal_ssh_host"]
+    assert host.tailscale_device_id is None
+    assert host.activated_at is None
+    assert host.expires_at == payload["expires_at"]
+
+
+@respx.mock
+async def test_create_host_omits_image_and_env_when_unset(api: SandboxAPI):
+    """The service treats absence as "use defaults"; we must not send
+    explicit nulls or empty dicts because the service distinguishes
+    those from "key not present"."""
+
+    payload = _host_payload()
+    route = respx.post(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(201, json=payload),
+    )
+
+    await api.create_host()
+
+    body = route.calls.last.request.content.decode()
+    assert "image" not in body
+    assert "env" not in body
+    assert "expires_at" not in body
+    assert "Idempotency-Key" not in route.calls.last.request.headers
+
+
+@respx.mock
+async def test_get_host_returns_parsed_host(api: SandboxAPI):
+    payload = _host_payload(status="active")
+    respx.get(f"{BASE_URL}/hosts/{payload['id']}").mock(
+        return_value=httpx.Response(200, json=payload),
+    )
+
+    host = await api.get_host(payload["id"])
+
+    assert host.status == "active"
+    assert host.provider == "exe"
+
+
+@respx.mock
+async def test_attach_is_alias_for_get_host(api: SandboxAPI):
+    payload = _host_payload()
+    route = respx.get(f"{BASE_URL}/hosts/{payload['id']}").mock(
+        return_value=httpx.Response(200, json=payload),
+    )
+
+    via_attach = await api.attach(payload["id"])
+    via_get = await api.get_host(payload["id"])
+
+    assert via_attach == via_get
+    # Two HTTP roundtrips; attach is not memoized.
+    assert route.call_count == 2
+
+
+@respx.mock
+async def test_list_hosts_parses_each_record(api: SandboxAPI):
+    payloads = [_host_payload(), _host_payload()]
+    respx.get(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(200, json=payloads),
+    )
+
+    hosts = await api.list_hosts()
+
+    assert len(hosts) == 2
+    assert {h.id for h in hosts} == {p["id"] for p in payloads}
+
+
+@respx.mock
+async def test_delete_host_swallows_204(api: SandboxAPI):
+    host_id = uuid4()
+    respx.delete(f"{BASE_URL}/hosts/{host_id}").mock(return_value=httpx.Response(204))
+
+    # Should not raise and should not need a body.
+    await api.delete_host(host_id)
+
+
+# ---------------------------------------------------------------------------
+# Forwards compatibility — service adds fields
+# ---------------------------------------------------------------------------
+
+
+@respx.mock
+async def test_unknown_fields_in_host_payload_are_ignored(api: SandboxAPI):
+    """If the service ships a new field tomorrow, today's SDK must not
+    break. The host parser picks known fields only."""
+
+    payload = _host_payload(future_field="surprise", another_one=42)
+    respx.get(f"{BASE_URL}/hosts/{payload['id']}").mock(
+        return_value=httpx.Response(200, json=payload),
+    )
+
+    host = await api.get_host(payload["id"])
+
+    assert host.id == payload["id"]  # Old fields still parsed.
+    assert not hasattr(host, "future_field")  # New field silently dropped.
+
+
+# ---------------------------------------------------------------------------
+# Error classification
+# ---------------------------------------------------------------------------
+
+
+@respx.mock
+async def test_401_raises_sandbox_auth_error(api: SandboxAPI):
+    respx.get(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(401, json={"detail": "bad token"}),
+    )
+
+    with pytest.raises(SandboxAuthError, match="bad token"):
+        await api.list_hosts()
+
+
+@respx.mock
+async def test_403_raises_sandbox_auth_error(api: SandboxAPI):
+    """403 and 401 are both classified as auth; callers shouldn't have
+    to care about the distinction — both mean "fix your credentials"."""
+
+    respx.get(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(403, json={"detail": "forbidden"}),
+    )
+
+    with pytest.raises(SandboxAuthError):
+        await api.list_hosts()
+
+
+@respx.mock
+async def test_404_raises_sandbox_not_found_error(api: SandboxAPI):
+    host_id = uuid4()
+    respx.get(f"{BASE_URL}/hosts/{host_id}").mock(
+        return_value=httpx.Response(404, json={"detail": "host gone"}),
+    )
+
+    with pytest.raises(SandboxNotFoundError, match="host gone"):
+        await api.get_host(host_id)
+
+
+@respx.mock
+async def test_409_raises_sandbox_conflict_error(api: SandboxAPI):
+    host_id = uuid4()
+    respx.delete(f"{BASE_URL}/hosts/{host_id}").mock(
+        return_value=httpx.Response(409, json={"detail": "host is still provisioning"}),
+    )
+
+    with pytest.raises(SandboxConflictError, match="host is still provisioning"):
+        await api.delete_host(host_id)
+
+
+@respx.mock
+async def test_500_raises_sandbox_response_error(api: SandboxAPI):
+    respx.get(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(500, json={"detail": "boom"}),
+    )
+
+    with pytest.raises(SandboxResponseError, match="boom"):
+        await api.list_hosts()
+
+
+@respx.mock
+async def test_502_raises_sandbox_provisioning_error(api: SandboxAPI):
+    """The service maps inline provisioning failures to 502; the SDK
+    surfaces them as a dedicated error so callers can distinguish
+    "provisioning broke" from generic server faults."""
+
+    respx.post(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(
+            502,
+            json={"detail": "ssh-keyscan never returned host keys"},
+        ),
+    )
+
+    with pytest.raises(SandboxProvisioningError, match="ssh-keyscan"):
+        await api.create_host()
+
+
+@respx.mock
+async def test_transport_error_raises_sandbox_unavailable_error(api: SandboxAPI):
+    """Network-level failure (DNS, connection refused, TLS) — wrapped as
+    SandboxUnavailableError so callers can distinguish "service can't be
+    reached, retry with backoff" from "service responded with a refusal"."""
+
+    respx.get(f"{BASE_URL}/hosts").mock(side_effect=httpx.ConnectError("nope"))
+
+    with pytest.raises(SandboxUnavailableError, match="transport failed"):
+        await api.list_hosts()
+
+
+@respx.mock
+async def test_503_raises_sandbox_unavailable_error(api: SandboxAPI):
+    """A 503 from the service (host teardown failed, dependency outage)
+    is the service's own "I'm broken, try again later" signal — same
+    semantics as a transport failure on the caller's side."""
+
+    respx.get(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(503, json={"detail": "host teardown could not be completed"}),
+    )
+
+    with pytest.raises(SandboxUnavailableError, match="host teardown"):
+        await api.list_hosts()
+
+
+@respx.mock
+async def test_non_json_body_raises_sandbox_response_error(api: SandboxAPI):
+    respx.get(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(200, text="<html>oops</html>"),
+    )
+
+    with pytest.raises(SandboxResponseError, match="non-JSON"):
+        await api.list_hosts()
+
+
+@respx.mock
+async def test_error_detail_absent_uses_fallback_message(api: SandboxAPI):
+    """The service contract returns ``{"detail": "..."}`` on errors but
+    we shouldn't crash if a different shape arrives — fall back to a
+    generic message rather than KeyError-ing on the caller."""
+
+    respx.get(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(500, json={"unexpected": "shape"}),
+    )
+
+    with pytest.raises(SandboxResponseError):
+        await api.list_hosts()
+
+
+# ---------------------------------------------------------------------------
+# Lifecycle + loop affinity
+# ---------------------------------------------------------------------------
+
+
+@respx.mock
+async def test_aclose_drops_client_and_is_idempotent(api: SandboxAPI):
+    respx.get(f"{BASE_URL}/hosts").mock(return_value=httpx.Response(200, json=[]))
+    await api.list_hosts()
+    assert api._client is not None
+
+    await api.aclose()
+    assert api._client is None
+
+    # Second close is a no-op (no AttributeError, no double-close).
+    await api.aclose()
+
+
+def test_cross_loop_reuse_rebinds_client_without_crashing():
+    """The httpx ``AsyncClient`` is loop-bound. Reusing the same SDK
+    instance across two ``asyncio.run`` invocations (the closest
+    stand-in for two distinct event-loop lifetimes against one module-
+    level SDK instance) should rebind instead of erroring.
+
+    The pre-fix behaviour was a ``RuntimeError("Event loop is closed")``
+    or ``Loop attached to a different loop`` on the second call — that
+    not raising is the whole point. As a secondary check we capture
+    the bound loop reference and assert they differ across the two
+    runs.
+    """
+
+    sandbox = SandboxAPI(base_url=BASE_URL, token="t", timeout=5.0)
+    bound_loops: list[asyncio.AbstractEventLoop] = []
+
+    async def use_it() -> None:
+        with respx.mock() as mock:
+            mock.get(f"{BASE_URL}/hosts").mock(
+                return_value=httpx.Response(200, json=[]),
+            )
+            await sandbox.list_hosts()
+            assert sandbox._client_loop is not None
+            bound_loops.append(sandbox._client_loop)
+
+    asyncio.run(use_it())
+    asyncio.run(use_it())
+
+    # Two distinct loop objects — the SDK rebound on the second
+    # invocation rather than reusing a stale (closed) loop.
+    assert bound_loops[0] is not bound_loops[1]
+
+
+# ---------------------------------------------------------------------------
+# from_env
+# ---------------------------------------------------------------------------
+
+
+def test_from_env_reads_prefixed_vars(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv("SANDBOX_SERVICE_URL", "https://from-env.test")
+    monkeypatch.setenv("SANDBOX_SERVICE_TOKEN", "env-token")
+    monkeypatch.setenv("SANDBOX_SERVICE_TIMEOUT", "60")
+
+    sandbox = SandboxAPI.from_env()
+
+    assert sandbox.base_url == "https://from-env.test"
+    assert sandbox.token == "env-token"
+    assert sandbox.timeout == 60.0
+
+
+def test_from_env_supports_custom_prefix(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv("CUSTOM_SERVICE_URL", "https://custom.test")
+    monkeypatch.setenv("CUSTOM_SERVICE_TOKEN", "x")
+
+    sandbox = SandboxAPI.from_env(prefix="CUSTOM_")
+
+    assert sandbox.base_url == "https://custom.test"
+    assert sandbox.timeout == 300.0  # default when unset
+
+
+def test_from_env_strips_trailing_slash_via_constructor(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    """``base_url`` should be normalized so concatenation with ``/hosts``
+    doesn't yield ``//hosts``. The constructor strips, not the env
+    reader — covered here because that's the most common entry point."""
+
+    monkeypatch.setenv("SANDBOX_SERVICE_URL", "https://trailing.test/")
+    monkeypatch.setenv("SANDBOX_SERVICE_TOKEN", "x")
+
+    sandbox = SandboxAPI.from_env()
+
+    assert sandbox.base_url == "https://trailing.test"