fix: update SDK for v0.2.0 API compatibility

Sync OpenAPI spec to v0.2.0, fix type annotation shadowing by using
builtins.list in annotated signatures, guard poll interval lookup
against None status, and reorder capsule ID assignment to validate
before storing.

.gitignore

@@ -176,7 +176,9 @@ cython_debug/
 
 CODE_EXECUTION.md
 
+.opencode/
 # AI
 .code-review-graph/
 .claude
 .mcp.json
+AGENTS.md

api/openapi.yaml

@@ -1,8 +1,8 @@
 openapi: "3.1.0"
 info:
   title: Wrenn API
-  description: MicroVM-based code execution platform API.
+  description: AI agent execution platform API.
-  version: "0.1.3"
+  version: "0.2.0"
 
 servers:
   - url: http://localhost:8080
@@ -866,8 +866,8 @@ paths:
             schema:
               $ref: "#/components/schemas/CreateCapsuleRequest"
       responses:
-        "201":
+        "202":
-          description: Capsule created
+          description: Capsule creation initiated (status will be "starting")
           content:
             application/json:
               schema:
@@ -988,8 +988,8 @@ paths:
       security:
         - apiKeyAuth: []
       responses:
-        "204":
+        "202":
-          description: Capsule destroyed
+          description: Capsule destruction initiated
 
   /v1/capsules/{id}/exec:
     parameters:
@@ -1260,8 +1260,8 @@ paths:
         destroys all running resources. The capsule exists only as files on
         disk and can be resumed later.
       responses:
-        "200":
+        "202":
-          description: Capsule paused (snapshot taken, resources released)
+          description: Capsule pause initiated (status will be "pausing")
           content:
             application/json:
               schema:
@@ -1292,8 +1292,8 @@ paths:
         memory loading. Boots a fresh Firecracker process, sets up a new
         network slot, and waits for envd to become ready.
       responses:
-        "200":
+        "202":
-          description: Capsule resumed (new VM booted from snapshot)
+          description: Capsule resume initiated (status will be "resuming")
           content:
             application/json:
               schema:
@@ -2035,6 +2035,51 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
 
+  /v1/hosts/sandbox-events:
+    post:
+      summary: Sandbox lifecycle event callback
+      operationId: sandboxEventCallback
+      tags: [hosts]
+      security:
+        - hostTokenAuth: []
+      description: |
+        Receives autonomous lifecycle events from host agents (e.g. auto-pause
+        from the TTL reaper). The event is published to an internal Redis stream
+        for the control plane's event consumer to process.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [event, sandbox_id, host_id]
+              properties:
+                event:
+                  type: string
+                  enum: [sandbox.auto_paused]
+                sandbox_id:
+                  type: string
+                host_id:
+                  type: string
+                timestamp:
+                  type: integer
+                  format: int64
+      responses:
+        "204":
+          description: Event accepted
+        "400":
+          description: Invalid request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "403":
+          description: Host ID mismatch
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
   /v1/hosts/auth/refresh:
     post:
       summary: Refresh host JWT
@@ -2346,6 +2391,54 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
 
+  /v1/admin/users/{id}/admin:
+    put:
+      summary: Grant or revoke platform admin
+      operationId: setUserAdmin
+      tags: [admin]
+      description: |
+        Sets the platform admin flag on a user. Cannot remove the last admin.
+        Requires platform admin access (JWT + is_admin).
+        The target user's JWT is not re-issued — their frontend will reflect the
+        change on next login or team switch.
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+            example: "usr-a1b2c3d4"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [admin]
+              properties:
+                admin:
+                  type: boolean
+                  description: true to grant admin, false to revoke.
+      responses:
+        "204":
+          description: Admin status updated
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          description: Caller is not a platform admin
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "404":
+          description: User not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
 components:
   securitySchemes:
     apiKeyAuth:
@@ -2544,7 +2637,7 @@ components:
           type: string
         status:
           type: string
-          enum: [pending, starting, running, paused, hibernated, stopped, missing, error]
+          enum: [pending, starting, running, pausing, paused, resuming, stopping, hibernated, stopped, missing, error]
         template:
           type: string
         vcpus:

docs/reference.md

@@ -1964,15 +1964,17 @@ inactivity TTL is set.
 #### wait\_ready
 
 ```python
-async def wait_ready(timeout: float = 30, interval: float = 0.5) -> None
+async def wait_ready(timeout: float = 30) -> None
 ```
 
 Await until the capsule status is ``running``.
 
+Polling interval adapts to the current transient status:
+0.5 s for starting/resuming, 2 s for pausing, 1 s for stopping.
+
 **Arguments**:
 
 - `timeout` _float_ - Maximum seconds to wait. Defaults to ``30``.
-- `interval` _float_ - Polling interval in seconds. Defaults to ``0.5``.
   
 
 **Raises**:
@@ -2534,15 +2536,17 @@ inactivity TTL is set.
 #### wait\_ready
 
 ```python
-def wait_ready(timeout: float = 30, interval: float = 0.5) -> None
+def wait_ready(timeout: float = 30) -> None
 ```
 
 Block until the capsule status is ``running``.
 
+Polling interval adapts to the current transient status:
+0.5 s for starting/resuming, 2 s for pausing, 1 s for stopping.
+
 **Arguments**:
 
 - `timeout` _float_ - Maximum seconds to wait. Defaults to ``30``.
-- `interval` _float_ - Polling interval in seconds. Defaults to ``0.5``.
   
 
 **Raises**:
@@ -2700,17 +2704,6 @@ Create a snapshot template from this capsule's current state.
 
 # wrenn.\_config
 
-<a id="wrenn._config.ConnectionConfig"></a>
-
-## ConnectionConfig Objects
-
-```python
-@dataclass(frozen=True)
-class ConnectionConfig()
-```
-
-Resolved credentials and base URL for Wrenn API calls.
-
 <a id="wrenn._git._auth"></a>
 
 # wrenn.\_git.\_auth

src/wrenn/_config.py

@@ -1,33 +1,5 @@
 from __future__ import annotations
 
-import os
-from dataclasses import dataclass
-
 DEFAULT_BASE_URL = "https://app.wrenn.dev/api"
 ENV_API_KEY = "WRENN_API_KEY"
 ENV_BASE_URL = "WRENN_BASE_URL"
-
-
-@dataclass(frozen=True)
-class ConnectionConfig:
-    """Resolved credentials and base URL for Wrenn API calls."""
-
-    api_key: str
-    base_url: str
-
-    @classmethod
-    def from_env(
-        cls,
-        api_key: str | None = None,
-        base_url: str | None = None,
-    ) -> ConnectionConfig:
-        resolved_key = api_key or os.environ.get(ENV_API_KEY)
-        if not resolved_key:
-            raise ValueError(
-                f"No API key provided. Pass api_key= or set the {ENV_API_KEY} environment variable."
-            )
-        resolved_url = base_url or os.environ.get(ENV_BASE_URL, DEFAULT_BASE_URL)
-        return cls(api_key=resolved_key, base_url=resolved_url)
-
-    def auth_headers(self) -> dict[str, str]:
-        return {"X-API-Key": self.api_key}

src/wrenn/async_capsule.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import builtins
+import logging
 import time
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
@@ -139,14 +140,19 @@ class AsyncCapsule:
         info = await client.capsules.get(capsule_id)
 
         if info.status == Status.paused:
-            info = await client.capsules.resume(capsule_id)
+            await client.capsules.resume(capsule_id)
 
-        return cls(
+        capsule = cls(
             _capsule_id=capsule_id,
             _client=client,
             _info=info,
         )
 
+        if info.status != Status.running:
+            await capsule.wait_ready()
+
+        return capsule
+
     # ── Dual instance/static lifecycle ──────────────────────────
 
     destroy = _DualMethod("_instance_destroy", "_static_destroy")
@@ -223,12 +229,21 @@ class AsyncCapsule:
         """
         await self._client.capsules.ping(self._id)
 
-    async def wait_ready(self, timeout: float = 30, interval: float = 0.5) -> None:
+    _POLL_INTERVALS: dict[Status, float] = {
+        Status.starting: 0.5,
+        Status.resuming: 0.5,
+        Status.pausing: 2.0,
+        Status.stopping: 1.0,
+    }
+
+    async def wait_ready(self, timeout: float = 30) -> None:
         """Await until the capsule status is ``running``.
 
+        Polling interval adapts to the current transient status:
+        0.5 s for starting/resuming, 2 s for pausing, 1 s for stopping.
+
         Args:
             timeout (float): Maximum seconds to wait. Defaults to ``30``.
-            interval (float): Polling interval in seconds. Defaults to ``0.5``.
 
         Raises:
             TimeoutError: If the capsule does not reach ``running`` state
@@ -242,8 +257,13 @@ class AsyncCapsule:
             if info.status == Status.running:
                 self._info = info
                 return
-            if info.status in (Status.error, Status.stopped, Status.paused):
+            if info.status in (Status.error, Status.stopped):
                 raise RuntimeError(f"Capsule entered {info.status} state while waiting")
+            if info.status == Status.paused:
+                await self._client.capsules.resume(self._id)
+            interval = (
+                self._POLL_INTERVALS.get(info.status, 0.5) if info.status else 0.5
+            )
             await asyncio.sleep(interval)
         raise TimeoutError(f"Capsule {self._id} did not become ready within {timeout}s")
 
@@ -389,8 +409,8 @@ class AsyncCapsule:
     ) -> None:
         try:
             await self._instance_destroy()
-        except Exception:
+        except Exception as exc:
-            pass
+            logging.warning("Failed to destroy capsule %s: %s", self._id, exc)
         try:
             await self._client.aclose()
         except Exception:

src/wrenn/capsule.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import builtins
+import logging
 import time
 from collections.abc import Iterator
 from contextlib import contextmanager
@@ -99,17 +100,24 @@ class Capsule:
             self._id: str = _capsule_id
             self._client = _client
             self._info = _info
+            if self._id is None:
+                self._client.close()
+                raise RuntimeError("API returned a capsule without an ID")
         else:
-            # Public construction: create a capsule immediately
             self._client = WrennClient(api_key=api_key, base_url=base_url)
+            try:
                 self._info = self._client.capsules.create(
                     template=template,
                     vcpus=vcpus,
                     memory_mb=memory_mb,
                     timeout_sec=timeout,
                 )
-            assert self._info.id is not None
+                if self._info.id is None:
+                    raise RuntimeError("API returned a capsule without an ID")
                 self._id = self._info.id
+            except Exception:
+                self._client.close()
+                raise
 
         self.commands = Commands(self._id, self._client.http)
         self.files = Files(self._id, self._client.http)
@@ -206,14 +214,19 @@ class Capsule:
         info = client.capsules.get(capsule_id)
 
         if info.status == Status.paused:
-            info = client.capsules.resume(capsule_id)
+            client.capsules.resume(capsule_id)
 
-        return cls(
+        capsule = cls(
             _capsule_id=capsule_id,
             _client=client,
             _info=info,
         )
 
+        if info.status != Status.running:
+            capsule.wait_ready()
+
+        return capsule
+
     # ── Dual instance/static lifecycle ──────────────────────────
 
     destroy = _DualMethod("_instance_destroy", "_static_destroy")
@@ -298,12 +311,21 @@ class Capsule:
         """
         self._client.capsules.ping(self._id)
 
-    def wait_ready(self, timeout: float = 30, interval: float = 0.5) -> None:
+    _POLL_INTERVALS: dict[Status, float] = {
+        Status.starting: 0.5,
+        Status.resuming: 0.5,
+        Status.pausing: 2.0,
+        Status.stopping: 1.0,
+    }
+
+    def wait_ready(self, timeout: float = 30) -> None:
         """Block until the capsule status is ``running``.
 
+        Polling interval adapts to the current transient status:
+        0.5 s for starting/resuming, 2 s for pausing, 1 s for stopping.
+
         Args:
             timeout (float): Maximum seconds to wait. Defaults to ``30``.
-            interval (float): Polling interval in seconds. Defaults to ``0.5``.
 
         Raises:
             TimeoutError: If the capsule does not reach ``running`` state
@@ -317,8 +339,13 @@ class Capsule:
             if info.status == Status.running:
                 self._info = info
                 return
-            if info.status in (Status.error, Status.stopped, Status.paused):
+            if info.status in (Status.error, Status.stopped):
                 raise RuntimeError(f"Capsule entered {info.status} state while waiting")
+            if info.status == Status.paused:
+                self._client.capsules.resume(self._id)
+            interval = (
+                self._POLL_INTERVALS.get(info.status, 0.5) if info.status else 0.5
+            )
             time.sleep(interval)
         raise TimeoutError(f"Capsule {self._id} did not become ready within {timeout}s")
 
@@ -463,8 +490,8 @@ class Capsule:
     ) -> None:
         try:
             self._instance_destroy()
-        except Exception:
+        except Exception as exc:
-            pass
+            logging.warning("Failed to destroy capsule %s: %s", self._id, exc)
         try:
             self._client.close()
         except Exception:

src/wrenn/client.py

@@ -111,7 +111,7 @@ class CapsulesResource:
         Raises:
             WrennNotFoundError: If no capsule with the given ID exists.
         """
-        resp = self._http.post(f"/v1/capsules/{id}/pause", timeout=_LONG_TIMEOUT)
+        resp = self._http.post(f"/v1/capsules/{id}/pause")
         return CapsuleModel.model_validate(handle_response(resp))
 
     def resume(self, id: str) -> CapsuleModel:
@@ -227,7 +227,7 @@ class AsyncCapsulesResource:
         Raises:
             WrennNotFoundError: If no capsule with the given ID exists.
         """
-        resp = await self._http.post(f"/v1/capsules/{id}/pause", timeout=_LONG_TIMEOUT)
+        resp = await self._http.post(f"/v1/capsules/{id}/pause")
         return CapsuleModel.model_validate(handle_response(resp))
 
     async def resume(self, id: str) -> CapsuleModel:

src/wrenn/code_interpreter/async_capsule.py

@@ -40,6 +40,28 @@ class AsyncCapsule(BaseAsyncCapsule):
         self._kernel_id = None
         self._proxy_client = None
 
+    async def close(self) -> None:
+        if self._proxy_client is not None:
+            try:
+                await self._proxy_client.aclose()
+            except Exception:
+                pass
+            self._proxy_client = None
+
+    def __del__(self) -> None:
+        if self._proxy_client is not None:
+            try:
+                import asyncio
+
+                loop = asyncio.get_event_loop()
+                if loop.is_running():
+                    loop.create_task(self._proxy_client.aclose())
+                else:
+                    loop.run_until_complete(self._proxy_client.aclose())
+            except Exception:
+                pass
+            self._proxy_client = None
+
     @classmethod
     async def create(
         cls,
@@ -126,8 +148,10 @@ class AsyncCapsule(BaseAsyncCapsule):
                     request=resp.request,
                     response=resp,
                 )
-            except httpx.HTTPStatusError:
+            except httpx.HTTPStatusError as exc:
+                if exc.response.status_code < 500:
                     raise
+                last_exc = exc
             except Exception as exc:
                 last_exc = exc
             await asyncio.sleep(0.5)
@@ -164,8 +188,6 @@ class AsyncCapsule(BaseAsyncCapsule):
             },
             "buffers": [],
             "channel": "shell",
-            "msg_id": msg_id,
-            "msg_type": "execute_request",
         }
 
     async def run_code(
@@ -201,7 +223,7 @@ class AsyncCapsule(BaseAsyncCapsule):
         ws_url = self._jupyter_ws_url(kernel_id)
 
         msg = self._jupyter_execute_request(code)
-        msg_id = msg["msg_id"]
+        msg_id = msg["header"]["msg_id"]
 
         execution = Execution()
         deadline = time.monotonic() + timeout
@@ -215,7 +237,7 @@ class AsyncCapsule(BaseAsyncCapsule):
                     break
                 try:
                     data = await asyncio.wait_for(ws.receive_json(), timeout=time_left)
-                except (asyncio.TimeoutError, Exception):
+                except Exception:
                     break
                 if not data:
                     break

src/wrenn/code_interpreter/capsule.py

@@ -70,6 +70,17 @@ class Capsule(BaseCapsule):
         self._kernel_id = None
         self._proxy_client = None
 
+    def close(self) -> None:
+        if self._proxy_client is not None:
+            try:
+                self._proxy_client.close()
+            except Exception:
+                pass
+            self._proxy_client = None
+
+    def __del__(self) -> None:
+        self.close()
+
     @classmethod
     def create(
         cls,
@@ -150,8 +161,10 @@ class Capsule(BaseCapsule):
                     request=resp.request,
                     response=resp,
                 )
-            except httpx.HTTPStatusError:
+            except httpx.HTTPStatusError as exc:
+                if exc.response.status_code < 500:
                     raise
+                last_exc = exc
             except Exception as exc:
                 last_exc = exc
             time.sleep(0.5)
@@ -188,8 +201,6 @@ class Capsule(BaseCapsule):
             },
             "buffers": [],
             "channel": "shell",
-            "msg_id": msg_id,
-            "msg_type": "execute_request",
         }
 
     def run_code(
@@ -227,7 +238,7 @@ class Capsule(BaseCapsule):
         ws_url = self._jupyter_ws_url(kernel_id)
 
         msg = self._jupyter_execute_request(code)
-        msg_id = msg["msg_id"]
+        msg_id = msg["header"]["msg_id"]
 
         execution = Execution()
         deadline = time.monotonic() + timeout
@@ -241,7 +252,7 @@ class Capsule(BaseCapsule):
                     break
                 try:
                     data = ws.receive_json(timeout=time_left)
-                except (TimeoutError, Exception):
+                except Exception:
                     break
                 if not data:
                     break

src/wrenn/commands.py

@@ -5,7 +5,7 @@ import builtins
 import json
 from collections.abc import AsyncIterator, Iterator
 from dataclasses import dataclass
-from typing import overload, Literal
+from typing import Literal, overload
 
 import httpx
 import httpx_ws
@@ -198,7 +198,15 @@ class Commands:
         if tag is not None:
             payload["tag"] = tag
 
-        resp = self._http.post(f"/v1/capsules/{self._capsule_id}/exec", json=payload)
+        http_timeout: httpx.Timeout | None = None
+        if not background and timeout is not None:
+            http_timeout = httpx.Timeout(timeout + 10, connect=5.0)
+
+        resp = self._http.post(
+            f"/v1/capsules/{self._capsule_id}/exec",
+            json=payload,
+            timeout=http_timeout,
+        )
         data = handle_response(resp)
         assert isinstance(data, dict)
 
@@ -379,8 +387,14 @@ class AsyncCommands:
         if tag is not None:
             payload["tag"] = tag
 
+        http_timeout: httpx.Timeout | None = None
+        if not background and timeout is not None:
+            http_timeout = httpx.Timeout(timeout + 10, connect=5.0)
+
         resp = await self._http.post(
-            f"/v1/capsules/{self._capsule_id}/exec", json=payload
+            f"/v1/capsules/{self._capsule_id}/exec",
+            json=payload,
+            timeout=http_timeout,
         )
         data = handle_response(resp)
         assert isinstance(data, dict)

src/wrenn/exceptions.py

@@ -110,13 +110,18 @@ _ERROR_MAP: dict[str, type[WrennError]] = {
 }
 
 
-def handle_response(resp: httpx.Response) -> dict | list:
+def _raise_for_status(resp: httpx.Response) -> None:
-    if resp.status_code >= 400:
+    if resp.status_code < 400:
+        return
+
     try:
         body = resp.json()
     except Exception:
-            resp.raise_for_status()
+        raise WrennInternalError(
-            raise
+            code="internal_error",
+            message=resp.text or f"HTTP {resp.status_code}",
+            status_code=resp.status_code,
+        )
 
     err = body.get("error", {})
     code = err.get("code", "internal_error")
@@ -129,7 +134,7 @@ def handle_response(resp: httpx.Response) -> dict | list:
             code=code,
             message=message,
             status_code=resp.status_code,
-                capsule_ids=body.get("sandbox_ids", []),
+            capsule_ids=body.get("capsule_ids") or body.get("sandbox_ids", []),
         )
 
     raise exc_cls(
@@ -138,9 +143,16 @@ def handle_response(resp: httpx.Response) -> dict | list:
         status_code=resp.status_code,
     )
 
+
+def handle_response(resp: httpx.Response) -> dict | list:
+    _raise_for_status(resp)
+
     if resp.status_code == 204:
         return {}
 
+    if not resp.content:
+        return {}
+
     return resp.json()
 
 

src/wrenn/files.py

@@ -5,7 +5,7 @@ from collections.abc import AsyncIterator, Iterator
 
 import httpx
 
-from wrenn.exceptions import WrennNotFoundError, handle_response
+from wrenn.exceptions import WrennNotFoundError, _raise_for_status, handle_response
 from wrenn.models import FileEntry, ListDirResponse, MakeDirResponse
 
 
@@ -46,7 +46,7 @@ class Files:
             f"/v1/capsules/{self._capsule_id}/files/read",
             json={"path": path},
         )
-        resp.raise_for_status()
+        _raise_for_status(resp)
         return resp.content
 
     def write(self, path: str, data: str | bytes) -> None:
@@ -65,7 +65,7 @@ class Files:
             files={"file": ("upload", data)},
             data={"path": path},
         )
-        resp.raise_for_status()
+        _raise_for_status(resp)
 
     def list(self, path: str, depth: int = 1) -> list[FileEntry]:
         """List directory contents.
@@ -179,7 +179,7 @@ class Files:
                 "Content-Type": f"multipart/form-data; boundary={boundary.decode('utf-8')}"
             },
         )
-        resp.raise_for_status()
+        _raise_for_status(resp)
 
     def download_stream(self, path: str) -> Iterator[bytes]:
         """Stream a large file out of the capsule.
@@ -243,7 +243,7 @@ class AsyncFiles:
             f"/v1/capsules/{self._capsule_id}/files/read",
             json={"path": path},
         )
-        resp.raise_for_status()
+        _raise_for_status(resp)
         return resp.content
 
     async def write(self, path: str, data: str | bytes) -> None:
@@ -262,7 +262,7 @@ class AsyncFiles:
             files={"file": ("upload", data)},
             data={"path": path},
         )
-        resp.raise_for_status()
+        _raise_for_status(resp)
 
     async def list(self, path: str, depth: int = 1) -> list[FileEntry]:
         """List directory contents.
@@ -377,7 +377,7 @@ class AsyncFiles:
                 "Content-Type": f"multipart/form-data; boundary={boundary.decode('utf-8')}"
             },
         )
-        resp.raise_for_status()
+        _raise_for_status(resp)
 
     async def download_stream(self, path: str) -> AsyncIterator[bytes]:
         """Stream a large file out of the capsule.

src/wrenn/models/_generated.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  openapi.yaml
-#   timestamp: 2026-04-22T20:21:34+00:00
+#   timestamp: 2026-05-15T07:57:28+00:00
 
 from __future__ import annotations
 from pydantic import AwareDatetime, BaseModel, EmailStr, Field
@@ -133,7 +133,10 @@ class Status(StrEnum):
     pending = "pending"
     starting = "starting"
     running = "running"
+    pausing = "pausing"
     paused = "paused"
+    resuming = "resuming"
+    stopping = "stopping"
     hibernated = "hibernated"
     stopped = "stopped"
     missing = "missing"

src/wrenn/pty.py

@@ -153,7 +153,8 @@ class PtySession:
             if event.pid is not None:
                 self._pid = event.pid
         if event.type == PtyEventType.exit:
-            raise StopIteration
+            self._done = True
+            return event
         if event.type == PtyEventType.error and event.fatal:
             self._done = True
             return event
@@ -281,7 +282,8 @@ class AsyncPtySession:
             if event.pid is not None:
                 self._pid = event.pid
         if event.type == PtyEventType.exit:
-            raise StopAsyncIteration
+            self._done = True
+            return event
         if event.type == PtyEventType.error and event.fatal:
             self._done = True
             return event

tests/test_capsule_features.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import httpx
 import respx
 
 from wrenn.capsule import Capsule, _build_proxy_url
@@ -30,9 +31,13 @@ class TestCapsuleCreate:
     @respx.mock
     def test_capsule_constructor_creates(self):
         respx.post(f"{BASE}/v1/capsules").respond(
-            201, json={"id": "cl-1", "status": "pending", "template": "minimal"}
+            202, json={"id": "cl-1", "status": "starting", "template": "minimal"}
+        )
+        cap = Capsule(
+            template="minimal",
+            api_key="wrn_test1234567890abcdef12345678",
+            base_url=BASE,
         )
-        cap = Capsule(template="minimal", api_key="wrn_test1234567890abcdef12345678")
         assert cap.capsule_id == "cl-1"
         assert hasattr(cap, "commands")
         assert hasattr(cap, "files")
@@ -40,18 +45,18 @@ class TestCapsuleCreate:
     @respx.mock
     def test_capsule_create_classmethod(self):
         respx.post(f"{BASE}/v1/capsules").respond(
-            201, json={"id": "cl-2", "status": "pending"}
+            202, json={"id": "cl-2", "status": "starting"}
         )
-        cap = Capsule.create(api_key="wrn_test1234567890abcdef12345678")
+        cap = Capsule.create(api_key="wrn_test1234567890abcdef12345678", base_url=BASE)
         assert cap.capsule_id == "cl-2"
 
     @respx.mock
     def test_capsule_context_manager_kills(self):
         respx.post(f"{BASE}/v1/capsules").respond(
-            201, json={"id": "cl-1", "status": "pending"}
+            202, json={"id": "cl-1", "status": "starting"}
         )
-        kill_route = respx.delete(f"{BASE}/v1/capsules/cl-1").respond(204)
+        kill_route = respx.delete(f"{BASE}/v1/capsules/cl-1").respond(202)
-        with Capsule(api_key="wrn_test1234567890abcdef12345678") as cap:
+        with Capsule(api_key="wrn_test1234567890abcdef12345678", base_url=BASE) as cap:
             assert cap.capsule_id == "cl-1"
         assert kill_route.called
 
@@ -59,33 +64,37 @@ class TestCapsuleCreate:
     def test_capsule_env_var(self, monkeypatch):
         monkeypatch.setenv("WRENN_API_KEY", "wrn_from_env_key")
         respx.post(f"{BASE}/v1/capsules").respond(
-            201, json={"id": "cl-3", "status": "pending"}
+            202, json={"id": "cl-3", "status": "starting"}
         )
-        cap = Capsule()
+        cap = Capsule(base_url=BASE)
         assert cap.capsule_id == "cl-3"
 
 
 class TestCapsuleStaticMethods:
     @respx.mock
     def test_static_destroy(self):
-        route = respx.delete(f"{BASE}/v1/capsules/cl-1").respond(204)
+        route = respx.delete(f"{BASE}/v1/capsules/cl-1").respond(202)
-        Capsule._static_destroy("cl-1", api_key="wrn_test1234567890abcdef12345678")
+        Capsule._static_destroy(
+            "cl-1", api_key="wrn_test1234567890abcdef12345678", base_url=BASE
+        )
         assert route.called
 
     @respx.mock
     def test_static_pause(self):
         respx.post(f"{BASE}/v1/capsules/cl-1/pause").respond(
-            200, json={"id": "cl-1", "status": "paused"}
+            202, json={"id": "cl-1", "status": "pausing"}
         )
-        info = Capsule._static_pause("cl-1", api_key="wrn_test1234567890abcdef12345678")
+        info = Capsule._static_pause(
-        assert info.status.value == "paused"
+            "cl-1", api_key="wrn_test1234567890abcdef12345678", base_url=BASE
+        )
+        assert info.status.value == "pausing"
 
     @respx.mock
     def test_static_list(self):
         respx.get(f"{BASE}/v1/capsules").respond(
             200, json=[{"id": "cl-1", "status": "running"}]
         )
-        items = Capsule.list(api_key="wrn_test1234567890abcdef12345678")
+        items = Capsule.list(api_key="wrn_test1234567890abcdef12345678", base_url=BASE)
         assert len(items) == 1
         assert items[0].id == "cl-1"
 
@@ -95,7 +104,7 @@ class TestCapsuleStaticMethods:
             200, json={"id": "cl-1", "status": "running"}
         )
         info = Capsule._static_get_info(
-            "cl-1", api_key="wrn_test1234567890abcdef12345678"
+            "cl-1", api_key="wrn_test1234567890abcdef12345678", base_url=BASE
         )
         assert info.id == "cl-1"
 
@@ -106,18 +115,24 @@ class TestCapsuleConnect:
         respx.get(f"{BASE}/v1/capsules/cl-1").respond(
             200, json={"id": "cl-1", "status": "running"}
         )
-        cap = Capsule.connect("cl-1", api_key="wrn_test1234567890abcdef12345678")
+        cap = Capsule.connect(
+            "cl-1", api_key="wrn_test1234567890abcdef12345678", base_url=BASE
+        )
         assert cap.capsule_id == "cl-1"
 
     @respx.mock
     def test_connect_paused_resumes(self):
-        respx.get(f"{BASE}/v1/capsules/cl-1").respond(
+        get_route = respx.get(f"{BASE}/v1/capsules/cl-1")
-            200, json={"id": "cl-1", "status": "paused"}
+        get_route.side_effect = [
-        )
+            httpx.Response(200, json={"id": "cl-1", "status": "paused"}),
+            httpx.Response(200, json={"id": "cl-1", "status": "running"}),
+        ]
         respx.post(f"{BASE}/v1/capsules/cl-1/resume").respond(
-            200, json={"id": "cl-1", "status": "running"}
+            202, json={"id": "cl-1", "status": "resuming"}
+        )
+        cap = Capsule.connect(
+            "cl-1", api_key="wrn_test1234567890abcdef12345678", base_url=BASE
         )
-        cap = Capsule.connect("cl-1", api_key="wrn_test1234567890abcdef12345678")
         assert cap.capsule_id == "cl-1"
 
 

tests/test_client.py

@@ -23,23 +23,23 @@ BASE = "https://app.wrenn.dev/api"
 
 @pytest.fixture
 def client():
-    with WrennClient(api_key="wrn_test1234567890abcdef12345678") as c:
+    with WrennClient(api_key="wrn_test1234567890abcdef12345678", base_url=BASE) as c:
         yield c
 
 
 @pytest.fixture
 def async_client():
-    return AsyncWrennClient(api_key="wrn_test1234567890abcdef12345678")
+    return AsyncWrennClient(api_key="wrn_test1234567890abcdef12345678", base_url=BASE)
 
 
 class TestCapsules:
     @respx.mock
     def test_create(self, client):
         respx.post(f"{BASE}/v1/capsules").respond(
-            201,
+            202,
             json={
                 "id": "sb-1",
-                "status": "pending",
+                "status": "starting",
                 "template": "base-python",
                 "vcpus": 2,
                 "memory_mb": 1024,
@@ -48,12 +48,12 @@ class TestCapsules:
         resp = client.capsules.create(template="base-python", vcpus=2, memory_mb=1024)
         assert isinstance(resp, Capsule)
         assert resp.id == "sb-1"
-        assert resp.status == Status.pending
+        assert resp.status == Status.starting
 
     @respx.mock
     def test_create_defaults(self, client):
         respx.post(f"{BASE}/v1/capsules").respond(
-            201, json={"id": "sb-2", "status": "pending"}
+            202, json={"id": "sb-2", "status": "starting"}
         )
         resp = client.capsules.create()
         assert resp.id == "sb-2"
@@ -77,25 +77,25 @@ class TestCapsules:
 
     @respx.mock
     def test_destroy(self, client):
-        route = respx.delete(f"{BASE}/v1/capsules/sb-1").respond(204)
+        route = respx.delete(f"{BASE}/v1/capsules/sb-1").respond(202)
         client.capsules.destroy("sb-1")
         assert route.called
 
     @respx.mock
     def test_pause(self, client):
         respx.post(f"{BASE}/v1/capsules/sb-1/pause").respond(
-            200, json={"id": "sb-1", "status": "paused"}
+            202, json={"id": "sb-1", "status": "pausing"}
         )
         resp = client.capsules.pause("sb-1")
-        assert resp.status == Status.paused
+        assert resp.status == Status.pausing
 
     @respx.mock
     def test_resume(self, client):
         respx.post(f"{BASE}/v1/capsules/sb-1/resume").respond(
-            200, json={"id": "sb-1", "status": "running"}
+            202, json={"id": "sb-1", "status": "resuming"}
         )
         resp = client.capsules.resume("sb-1")
-        assert resp.status == Status.running
+        assert resp.status == Status.resuming
 
     @respx.mock
     def test_ping(self, client):
@@ -221,7 +221,8 @@ class TestAuthModes:
         with WrennClient(api_key="wrn_test1234567890abcdef12345678") as c:
             assert c._http.headers["X-API-Key"] == "wrn_test1234567890abcdef12345678"
 
-    def test_no_auth_raises(self):
+    def test_no_auth_raises(self, monkeypatch):
+        monkeypatch.delenv("WRENN_API_KEY", raising=False)
         with pytest.raises(ValueError, match="No API key"):
             WrennClient()
 
@@ -237,7 +238,7 @@ class TestAsyncClient:
     async def test_async_capsules_create(self, async_client):
         async with async_client:
             respx.post(f"{BASE}/v1/capsules").respond(
-                201, json={"id": "sb-1", "status": "pending"}
+                202, json={"id": "sb-1", "status": "starting"}
             )
             resp = await async_client.capsules.create(template="base-python")
             assert resp.id == "sb-1"

tests/test_filesystem_pty.py

@@ -23,7 +23,7 @@ def _make_capsule(cap_id: str = "cl-abc") -> Capsule:
     respx.post(f"{BASE}/v1/capsules").respond(
         201, json={"id": cap_id, "status": "running"}
     )
-    return Capsule(api_key="wrn_test1234567890abcdef12345678")
+    return Capsule(api_key="wrn_test1234567890abcdef12345678", base_url=BASE)
 
 
 class TestFilesRead:
@@ -311,12 +311,14 @@ class TestPtySessionIteration:
         ws.receive_text.side_effect = messages
         session = PtySession(ws, "cl-abc")
         events = list(session)
-        assert len(events) == 2
+        assert len(events) == 3
         assert events[0].type == PtyEventType.started
         assert session.tag == "pty-abc12345"
         assert session.pid == 1
         assert events[1].type == PtyEventType.output
         assert events[1].data == b"hello"
+        assert events[2].type == PtyEventType.exit
+        assert events[2].exit_code == 0
 
     def test_iter_stops_on_fatal_error(self):
         ws = MagicMock()
@@ -461,10 +463,11 @@ class TestAsyncPtySession:
         events = []
         async for event in session:
             events.append(event)
-        assert len(events) == 2
+        assert len(events) == 3
         assert events[0].type == PtyEventType.started
         assert session.tag == "pty-xyz"
         assert session.pid == 5
+        assert events[2].type == PtyEventType.exit
 
 
 class TestExports:

tests/test_git.py

@@ -73,7 +73,7 @@ def _make_git(respx_mock=None) -> Git:
     """Create a Git instance bound to a test capsule."""
     from wrenn.client import WrennClient
 
-    client = WrennClient(api_key="wrn_test1234567890abcdef12345678")
+    client = WrennClient(api_key="wrn_test1234567890abcdef12345678", base_url=BASE)
     return Git(CAPSULE_ID, client.http)
 
 
@@ -81,7 +81,7 @@ def _make_async_git() -> AsyncGit:
     """Create an AsyncGit instance bound to a test capsule."""
     from wrenn.client import AsyncWrennClient
 
-    client = AsyncWrennClient(api_key="wrn_test1234567890abcdef12345678")
+    client = AsyncWrennClient(api_key="wrn_test1234567890abcdef12345678", base_url=BASE)
     return AsyncGit(CAPSULE_ID, client.http)
 
 
@@ -926,7 +926,7 @@ class TestCapsuleWiring:
         respx.post(f"{BASE}/v1/capsules").respond(
             201, json={"id": "cl-1", "status": "pending"}
         )
-        cap = Capsule(api_key="wrn_test1234567890abcdef12345678")
+        cap = Capsule(api_key="wrn_test1234567890abcdef12345678", base_url=BASE)
         assert hasattr(cap, "git")
         assert isinstance(cap.git, Git)
 
@@ -1017,7 +1017,7 @@ class TestCommandPayloadWrapping:
         from wrenn.client import WrennClient
         from wrenn.commands import Commands
 
-        client = WrennClient(api_key="wrn_test1234567890abcdef12345678")
+        client = WrennClient(api_key="wrn_test1234567890abcdef12345678", base_url=BASE)
         commands = Commands(CAPSULE_ID, client.http)
 
         route = respx.post(EXEC_URL).respond(200, json=_exec_response(stdout="3\n"))
@@ -1031,7 +1031,7 @@ class TestCommandPayloadWrapping:
         from wrenn.client import WrennClient
         from wrenn.commands import Commands
 
-        client = WrennClient(api_key="wrn_test1234567890abcdef12345678")
+        client = WrennClient(api_key="wrn_test1234567890abcdef12345678", base_url=BASE)
         commands = Commands(CAPSULE_ID, client.http)
 
         route = respx.post(EXEC_URL).respond(200, json=_exec_response())
@@ -1045,7 +1045,7 @@ class TestCommandPayloadWrapping:
         from wrenn.client import WrennClient
         from wrenn.commands import Commands
 
-        client = WrennClient(api_key="wrn_test1234567890abcdef12345678")
+        client = WrennClient(api_key="wrn_test1234567890abcdef12345678", base_url=BASE)
         commands = Commands(CAPSULE_ID, client.http)
 
         route = respx.post(EXEC_URL).respond(200, json=_exec_response())
@@ -1059,7 +1059,7 @@ class TestCommandPayloadWrapping:
         from wrenn.client import WrennClient
         from wrenn.commands import Commands
 
-        client = WrennClient(api_key="wrn_test1234567890abcdef12345678")
+        client = WrennClient(api_key="wrn_test1234567890abcdef12345678", base_url=BASE)
         commands = Commands(CAPSULE_ID, client.http)
 
         route = respx.post(EXEC_URL).respond(200, json=_exec_response())
@@ -1073,7 +1073,7 @@ class TestCommandPayloadWrapping:
         from wrenn.client import WrennClient
         from wrenn.commands import Commands
 
-        client = WrennClient(api_key="wrn_test1234567890abcdef12345678")
+        client = WrennClient(api_key="wrn_test1234567890abcdef12345678", base_url=BASE)
         commands = Commands(CAPSULE_ID, client.http)
 
         route = respx.post(EXEC_URL).respond(200, json=_exec_response())
@@ -1089,7 +1089,7 @@ class TestCommandPayloadWrapping:
         from wrenn.client import WrennClient
         from wrenn.commands import Commands
 
-        client = WrennClient(api_key="wrn_test1234567890abcdef12345678")
+        client = WrennClient(api_key="wrn_test1234567890abcdef12345678", base_url=BASE)
         commands = Commands(CAPSULE_ID, client.http)
 
         route = respx.post(EXEC_URL).respond(200, json=_exec_response())
@@ -1119,7 +1119,7 @@ class TestCommandPayloadWrapping:
         from wrenn.client import WrennClient
         from wrenn.commands import Commands
 
-        client = WrennClient(api_key="wrn_test1234567890abcdef12345678")
+        client = WrennClient(api_key="wrn_test1234567890abcdef12345678", base_url=BASE)
         commands = Commands(CAPSULE_ID, client.http)
 
         route = respx.post(EXEC_URL).respond(200, json={"pid": 42, "tag": "bg-1"})