v0.1.0

tests/conftest.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+ENV_FILE = Path(__file__).resolve().parent.parent / ".env"
+
+
+def _read_env_file() -> dict[str, str]:
+    result: dict[str, str] = {}
+    if not ENV_FILE.exists():
+        return result
+    for line in ENV_FILE.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip().strip("\"'")
+        if key:
+            result[key] = value
+    return result
+
+
+def pytest_collection_modifyitems(
+    config: pytest.Config, items: list[pytest.Item]
+) -> None:
+    env_vars = _read_env_file()
+    has_key = bool(os.environ.get("WRENN_API_KEY") or env_vars.get("WRENN_API_KEY"))
+    if has_key:
+        return
+    skip = pytest.mark.skip(reason="WRENN_API_KEY not set")
+    for item in items:
+        if "integration" in item.keywords:
+            item.add_marker(skip)

tests/test_capsule_features.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import respx
+
+from wrenn.capsule import Capsule, _build_proxy_url
+from wrenn.code_interpreter.models import Execution, ExecutionError, Logs, Result
+
+BASE = "https://app.wrenn.dev/api"
+
+
+class TestBuildProxyUrl:
+    def test_https_production(self):
+        url = _build_proxy_url("https://app.wrenn.dev/api", "cl-abc123", 8888)
+        assert url == "wss://8888-cl-abc123.app.wrenn.dev"
+
+    def test_http_localhost(self):
+        url = _build_proxy_url("http://localhost:8080", "cl-abc123", 3000)
+        assert url == "ws://3000-cl-abc123.localhost:8080"
+
+    def test_https_custom_port(self):
+        url = _build_proxy_url("https://api.example.com:9443", "sb-1", 8080)
+        assert url == "wss://8080-sb-1.api.example.com:9443"
+
+    def test_http_no_port(self):
+        url = _build_proxy_url("http://192.168.1.1", "sb-2", 5000)
+        assert url == "ws://5000-sb-2.192.168.1.1"
+
+
+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"}
+        )
+        cap = Capsule(template="minimal", api_key="wrn_test1234567890abcdef12345678")
+        assert cap.capsule_id == "cl-1"
+        assert hasattr(cap, "commands")
+        assert hasattr(cap, "files")
+
+    @respx.mock
+    def test_capsule_create_classmethod(self):
+        respx.post(f"{BASE}/v1/capsules").respond(
+            201, json={"id": "cl-2", "status": "pending"}
+        )
+        cap = Capsule.create(api_key="wrn_test1234567890abcdef12345678")
+        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"}
+        )
+        kill_route = respx.delete(f"{BASE}/v1/capsules/cl-1").respond(204)
+        with Capsule(api_key="wrn_test1234567890abcdef12345678") as cap:
+            assert cap.capsule_id == "cl-1"
+        assert kill_route.called
+
+    @respx.mock
+    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"}
+        )
+        cap = Capsule()
+        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)
+        Capsule._static_destroy("cl-1", api_key="wrn_test1234567890abcdef12345678")
+        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"}
+        )
+        info = Capsule._static_pause("cl-1", api_key="wrn_test1234567890abcdef12345678")
+        assert info.status.value == "paused"
+
+    @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")
+        assert len(items) == 1
+        assert items[0].id == "cl-1"
+
+    @respx.mock
+    def test_static_get_info(self):
+        respx.get(f"{BASE}/v1/capsules/cl-1").respond(
+            200, json={"id": "cl-1", "status": "running"}
+        )
+        info = Capsule._static_get_info(
+            "cl-1", api_key="wrn_test1234567890abcdef12345678"
+        )
+        assert info.id == "cl-1"
+
+
+class TestCapsuleConnect:
+    @respx.mock
+    def test_connect_running(self):
+        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")
+        assert cap.capsule_id == "cl-1"
+
+    @respx.mock
+    def test_connect_paused_resumes(self):
+        respx.get(f"{BASE}/v1/capsules/cl-1").respond(
+            200, json={"id": "cl-1", "status": "paused"}
+        )
+        respx.post(f"{BASE}/v1/capsules/cl-1/resume").respond(
+            200, json={"id": "cl-1", "status": "running"}
+        )
+        cap = Capsule.connect("cl-1", api_key="wrn_test1234567890abcdef12345678")
+        assert cap.capsule_id == "cl-1"
+
+
+class TestExecutionModels:
+    def test_execution_defaults(self):
+        e = Execution()
+        assert e.results == []
+        assert e.logs.stdout == []
+        assert e.logs.stderr == []
+        assert e.error is None
+        assert e.text is None
+
+    def test_result_from_bundle(self):
+        bundle = {"text/plain": "84", "image/png": "base64data"}
+        r = Result.from_bundle(bundle, is_main_result=True)
+        assert r.text == "84"
+        assert r.png == "base64data"
+        assert r.is_main_result is True
+
+    def test_result_from_bundle_strips_quotes(self):
+        bundle = {"text/plain": "'hello'"}
+        r = Result.from_bundle(bundle)
+        assert r.text == "hello"
+
+    def test_result_from_bundle_extra_mimes(self):
+        bundle = {"text/plain": "x", "application/vnd.custom": "data"}
+        r = Result.from_bundle(bundle)
+        assert r.extra == {"application/vnd.custom": "data"}
+
+    def test_result_formats(self):
+        r = Result(text="hi", png="data")
+        assert "text" in r.formats()
+        assert "png" in r.formats()
+        assert "html" not in r.formats()
+
+    def test_execution_text_property(self):
+        e = Execution(
+            results=[
+                Result(text="chart", is_main_result=False),
+                Result(text="42", is_main_result=True),
+            ]
+        )
+        assert e.text == "42"
+
+    def test_execution_error(self):
+        err = ExecutionError(
+            name="ZeroDivisionError",
+            value="division by zero",
+            traceback="Traceback ...\nZeroDivisionError: division by zero",
+        )
+        e = Execution(error=err)
+        assert e.error is not None
+        assert "ZeroDivisionError" in e.error.name
+
+    def test_logs(self):
+        logs = Logs(stdout=["hello\n", "world\n"], stderr=["warn\n"])
+        assert "".join(logs.stdout) == "hello\nworld\n"
+        assert "".join(logs.stderr) == "warn\n"
+
+
+class TestDeprecationWarnings:
+    def test_import_sandbox_from_wrenn_warns(self):
+        import sys
+        import warnings
+
+        # Clear cached attribute
+        if "Sandbox" in dir(sys.modules.get("wrenn", object())):
+            delattr(sys.modules["wrenn"], "Sandbox")
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            from wrenn import Sandbox
+
+            assert Sandbox is Capsule
+            fw = [x for x in w if issubclass(x.category, FutureWarning)]
+            assert len(fw) >= 1
+            assert "Sandbox" in str(fw[0].message)

tests/test_client.py

@@ -0,0 +1,262 @@
+from __future__ import annotations
+
+import pytest
+import respx
+
+from wrenn.client import AsyncWrennClient, WrennClient
+from wrenn.exceptions import (
+    WrennAgentError,
+    WrennAuthenticationError,
+    WrennConflictError,
+    WrennInternalError,
+    WrennNotFoundError,
+    WrennValidationError,
+)
+from wrenn.models import (
+    Capsule,
+    Status,
+    Template,
+)
+
+BASE = "https://app.wrenn.dev/api"
+
+
+@pytest.fixture
+def client():
+    with WrennClient(api_key="wrn_test1234567890abcdef12345678") as c:
+        yield c
+
+
+@pytest.fixture
+def async_client():
+    return AsyncWrennClient(api_key="wrn_test1234567890abcdef12345678")
+
+
+class TestCapsules:
+    @respx.mock
+    def test_create(self, client):
+        respx.post(f"{BASE}/v1/capsules").respond(
+            201,
+            json={
+                "id": "sb-1",
+                "status": "pending",
+                "template": "base-python",
+                "vcpus": 2,
+                "memory_mb": 1024,
+            },
+        )
+        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
+
+    @respx.mock
+    def test_create_defaults(self, client):
+        respx.post(f"{BASE}/v1/capsules").respond(
+            201, json={"id": "sb-2", "status": "pending"}
+        )
+        resp = client.capsules.create()
+        assert resp.id == "sb-2"
+
+    @respx.mock
+    def test_list(self, client):
+        respx.get(f"{BASE}/v1/capsules").respond(
+            200, json=[{"id": "sb-1", "status": "running"}]
+        )
+        boxes = client.capsules.list()
+        assert len(boxes) == 1
+        assert boxes[0].status == Status.running
+
+    @respx.mock
+    def test_get(self, client):
+        respx.get(f"{BASE}/v1/capsules/sb-1").respond(
+            200, json={"id": "sb-1", "status": "running"}
+        )
+        resp = client.capsules.get("sb-1")
+        assert resp.id == "sb-1"
+
+    @respx.mock
+    def test_destroy(self, client):
+        route = respx.delete(f"{BASE}/v1/capsules/sb-1").respond(204)
+        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"}
+        )
+        resp = client.capsules.pause("sb-1")
+        assert resp.status == Status.paused
+
+    @respx.mock
+    def test_resume(self, client):
+        respx.post(f"{BASE}/v1/capsules/sb-1/resume").respond(
+            200, json={"id": "sb-1", "status": "running"}
+        )
+        resp = client.capsules.resume("sb-1")
+        assert resp.status == Status.running
+
+    @respx.mock
+    def test_ping(self, client):
+        route = respx.post(f"{BASE}/v1/capsules/sb-1/ping").respond(204)
+        client.capsules.ping("sb-1")
+        assert route.called
+
+
+class TestSnapshots:
+    @respx.mock
+    def test_create(self, client):
+        respx.post(f"{BASE}/v1/snapshots").respond(
+            201,
+            json={"name": "snap-1", "type": "snapshot", "vcpus": 1},
+        )
+        resp = client.snapshots.create(capsule_id="sb-1", name="snap-1")
+        assert isinstance(resp, Template)
+        assert resp.name == "snap-1"
+
+    @respx.mock
+    def test_create_with_overwrite(self, client):
+        route = respx.post(f"{BASE}/v1/snapshots").respond(
+            201, json={"name": "snap-1", "type": "snapshot"}
+        )
+        client.snapshots.create(capsule_id="sb-1", overwrite=True)
+        req = route.calls[0].request
+        assert "overwrite=true" in str(req.url)
+
+    @respx.mock
+    def test_list(self, client):
+        respx.get(f"{BASE}/v1/snapshots").respond(
+            200, json=[{"name": "base-python", "type": "base"}]
+        )
+        snaps = client.snapshots.list()
+        assert len(snaps) == 1
+
+    @respx.mock
+    def test_list_with_filter(self, client):
+        route = respx.get(f"{BASE}/v1/snapshots").respond(200, json=[])
+        client.snapshots.list(type="snapshot")
+        req = route.calls[0].request
+        assert "type=snapshot" in str(req.url)
+
+    @respx.mock
+    def test_delete(self, client):
+        route = respx.delete(f"{BASE}/v1/snapshots/snap-1").respond(204)
+        client.snapshots.delete("snap-1")
+        assert route.called
+
+
+class TestErrorHandling:
+    @respx.mock
+    def test_validation_error(self, client):
+        respx.post(f"{BASE}/v1/capsules").respond(
+            400,
+            json={"error": {"code": "invalid_request", "message": "bad input"}},
+        )
+        with pytest.raises(WrennValidationError) as exc_info:
+            client.capsules.create()
+        assert exc_info.value.code == "invalid_request"
+        assert exc_info.value.status_code == 400
+
+    @respx.mock
+    def test_auth_error(self, client):
+        respx.get(f"{BASE}/v1/capsules").respond(
+            401,
+            json={"error": {"code": "unauthorized", "message": "bad key"}},
+        )
+        with pytest.raises(WrennAuthenticationError):
+            client.capsules.list()
+
+    @respx.mock
+    def test_not_found_error(self, client):
+        respx.get(f"{BASE}/v1/capsules/nope").respond(
+            404,
+            json={"error": {"code": "not_found", "message": "capsule not found"}},
+        )
+        with pytest.raises(WrennNotFoundError):
+            client.capsules.get("nope")
+
+    @respx.mock
+    def test_conflict_error(self, client):
+        respx.get(f"{BASE}/v1/capsules/sb-1").respond(
+            409,
+            json={"error": {"code": "invalid_state", "message": "not running"}},
+        )
+        with pytest.raises(WrennConflictError):
+            client.capsules.get("sb-1")
+
+    @respx.mock
+    def test_agent_error(self, client):
+        respx.post(f"{BASE}/v1/capsules").respond(
+            502,
+            json={"error": {"code": "agent_error", "message": "host agent failed"}},
+        )
+        with pytest.raises(WrennAgentError):
+            client.capsules.create()
+
+    @respx.mock
+    def test_internal_error(self, client):
+        respx.get(f"{BASE}/v1/capsules/sb-1").respond(
+            500,
+            json={"error": {"code": "internal_error", "message": "oops"}},
+        )
+        with pytest.raises(WrennInternalError):
+            client.capsules.get("sb-1")
+
+    @respx.mock
+    def test_unknown_error_code_falls_back(self, client):
+        respx.get(f"{BASE}/v1/capsules/sb-1").respond(
+            418,
+            json={"error": {"code": "teapot", "message": "I'm a teapot"}},
+        )
+        from wrenn.exceptions import WrennError
+
+        with pytest.raises(WrennError) as exc_info:
+            client.capsules.get("sb-1")
+        assert exc_info.value.code == "teapot"
+
+
+class TestAuthModes:
+    def test_api_key_header(self):
+        with WrennClient(api_key="wrn_test1234567890abcdef12345678") as c:
+            assert c._http.headers["X-API-Key"] == "wrn_test1234567890abcdef12345678"
+
+    def test_no_auth_raises(self):
+        with pytest.raises(ValueError, match="No API key"):
+            WrennClient()
+
+    def test_env_var_fallback(self, monkeypatch):
+        monkeypatch.setenv("WRENN_API_KEY", "wrn_from_env")
+        with WrennClient() as c:
+            assert c._http.headers["X-API-Key"] == "wrn_from_env"
+
+
+class TestAsyncClient:
+    @pytest.mark.asyncio
+    @respx.mock
+    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"}
+            )
+            resp = await async_client.capsules.create(template="base-python")
+            assert resp.id == "sb-1"
+
+    @pytest.mark.asyncio
+    @respx.mock
+    async def test_async_capsules_list(self, async_client):
+        async with async_client:
+            respx.get(f"{BASE}/v1/capsules").respond(200, json=[{"id": "sb-1"}])
+            boxes = await async_client.capsules.list()
+            assert len(boxes) == 1
+
+    @pytest.mark.asyncio
+    @respx.mock
+    async def test_async_error_handling(self, async_client):
+        async with async_client:
+            respx.get(f"{BASE}/v1/capsules/nope").respond(
+                404,
+                json={"error": {"code": "not_found", "message": "not found"}},
+            )
+            with pytest.raises(WrennNotFoundError):
+                await async_client.capsules.get("nope")

tests/test_filesystem_pty.py

@@ -0,0 +1,491 @@
+from __future__ import annotations
+
+import base64
+import json
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+import respx
+
+from wrenn.capsule import Capsule
+from wrenn.models import FileEntry
+from wrenn.pty import (
+    AsyncPtySession,
+    PtyEventType,
+    PtySession,
+    _parse_pty_event,
+)
+
+BASE = "https://app.wrenn.dev/api"
+
+
+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")
+
+
+class TestFilesRead:
+    @respx.mock
+    def test_read_returns_string(self):
+        cap = _make_capsule()
+        content = b"file contents here"
+        respx.post(f"{BASE}/v1/capsules/cl-abc/files/read").respond(
+            200, content=content
+        )
+        data = cap.files.read("/app/main.py")
+        assert data == "file contents here"
+
+    @respx.mock
+    def test_read_bytes(self):
+        cap = _make_capsule()
+        content = b"\x00\x01\x02"
+        respx.post(f"{BASE}/v1/capsules/cl-abc/files/read").respond(
+            200, content=content
+        )
+        data = cap.files.read_bytes("/bin/binary")
+        assert data == b"\x00\x01\x02"
+
+
+class TestFilesWrite:
+    @respx.mock
+    def test_write_string(self):
+        cap = _make_capsule()
+        route = respx.post(f"{BASE}/v1/capsules/cl-abc/files/write").respond(204)
+        cap.files.write("/app/main.py", "print('hello')")
+        assert route.called
+
+    @respx.mock
+    def test_write_bytes(self):
+        cap = _make_capsule()
+        route = respx.post(f"{BASE}/v1/capsules/cl-abc/files/write").respond(204)
+        cap.files.write("/app/data.bin", b"\x00\x01\x02")
+        assert route.called
+
+
+class TestFilesList:
+    @respx.mock
+    def test_list_returns_entries(self):
+        cap = _make_capsule()
+        respx.post(f"{BASE}/v1/capsules/cl-abc/files/list").respond(
+            200,
+            json={
+                "entries": [
+                    {
+                        "name": "main.py",
+                        "path": "/home/user/main.py",
+                        "type": "file",
+                        "size": 1024,
+                        "mode": 33188,
+                        "permissions": "-rw-r--r--",
+                        "owner": "root",
+                        "group": "root",
+                        "modified_at": 1712899200,
+                        "symlink_target": None,
+                    },
+                    {
+                        "name": "config",
+                        "path": "/home/user/config",
+                        "type": "directory",
+                        "size": 4096,
+                        "mode": 16877,
+                        "permissions": "drwxr-xr-x",
+                        "owner": "root",
+                        "group": "root",
+                        "modified_at": 1712899100,
+                        "symlink_target": None,
+                    },
+                ]
+            },
+        )
+        entries = cap.files.list("/home/user")
+        assert len(entries) == 2
+        assert isinstance(entries[0], FileEntry)
+        assert entries[0].name == "main.py"
+        assert entries[0].type == "file"
+        assert entries[1].name == "config"
+        assert entries[1].type == "directory"
+
+    @respx.mock
+    def test_list_with_depth(self):
+        cap = _make_capsule()
+        route = respx.post(f"{BASE}/v1/capsules/cl-abc/files/list").respond(
+            200, json={"entries": []}
+        )
+        cap.files.list("/home/user", depth=3)
+        body = json.loads(route.calls[0].request.content)
+        assert body["depth"] == 3
+
+    @respx.mock
+    def test_list_empty(self):
+        cap = _make_capsule()
+        respx.post(f"{BASE}/v1/capsules/cl-abc/files/list").respond(
+            200, json={"entries": []}
+        )
+        entries = cap.files.list("/empty")
+        assert entries == []
+
+
+class TestFilesMakeDir:
+    @respx.mock
+    def test_make_dir_returns_entry(self):
+        cap = _make_capsule()
+        respx.post(f"{BASE}/v1/capsules/cl-abc/files/mkdir").respond(
+            200,
+            json={
+                "entry": {
+                    "name": "data",
+                    "path": "/home/user/data",
+                    "type": "directory",
+                    "size": 4096,
+                    "mode": 16877,
+                    "permissions": "drwxr-xr-x",
+                    "owner": "root",
+                    "group": "root",
+                    "modified_at": 1712899200,
+                    "symlink_target": None,
+                }
+            },
+        )
+        entry = cap.files.make_dir("/home/user/data")
+        assert isinstance(entry, FileEntry)
+        assert entry.name == "data"
+        assert entry.type == "directory"
+
+    @respx.mock
+    def test_make_dir_existing_returns_gracefully(self):
+        cap = _make_capsule()
+        respx.post(f"{BASE}/v1/capsules/cl-abc/files/mkdir").respond(
+            409,
+            json={"error": {"code": "conflict", "message": "already exists"}},
+        )
+        respx.post(f"{BASE}/v1/capsules/cl-abc/files/list").respond(
+            200,
+            json={
+                "entries": [
+                    {
+                        "name": "data",
+                        "path": "/home/user/data",
+                        "type": "directory",
+                        "size": 4096,
+                        "mode": 16877,
+                        "permissions": "drwxr-xr-x",
+                        "owner": "root",
+                        "group": "root",
+                        "modified_at": 1712899200,
+                        "symlink_target": None,
+                    }
+                ]
+            },
+        )
+        entry = cap.files.make_dir("/home/user/data")
+        assert entry.name == "data"
+
+
+class TestFilesRemove:
+    @respx.mock
+    def test_remove_succeeds(self):
+        cap = _make_capsule()
+        route = respx.post(f"{BASE}/v1/capsules/cl-abc/files/remove").respond(204)
+        cap.files.remove("/home/user/old_data")
+        assert route.called
+
+    @respx.mock
+    def test_remove_sends_path(self):
+        cap = _make_capsule()
+        route = respx.post(f"{BASE}/v1/capsules/cl-abc/files/remove").respond(204)
+        cap.files.remove("/tmp/test.txt")
+        body = json.loads(route.calls[0].request.content)
+        assert body["path"] == "/tmp/test.txt"
+
+
+class TestFilesExists:
+    @respx.mock
+    def test_exists_true(self):
+        cap = _make_capsule()
+        respx.post(f"{BASE}/v1/capsules/cl-abc/files/list").respond(
+            200,
+            json={
+                "entries": [
+                    {"name": "hello.txt", "path": "/tmp/hello.txt", "type": "file"}
+                ]
+            },
+        )
+        assert cap.files.exists("/tmp/hello.txt") is True
+
+    @respx.mock
+    def test_exists_false(self):
+        cap = _make_capsule()
+        respx.post(f"{BASE}/v1/capsules/cl-abc/files/list").respond(
+            200, json={"entries": []}
+        )
+        assert cap.files.exists("/tmp/nope.txt") is False
+
+
+class TestPtyEventParsing:
+    def test_started_event(self):
+        raw = {"type": "started", "tag": "pty-a1b2c3d4", "pid": 42}
+        event = _parse_pty_event(raw)
+        assert event.type == PtyEventType.started
+        assert event.pid == 42
+        assert event.tag == "pty-a1b2c3d4"
+
+    def test_output_event_base64(self):
+        encoded = base64.b64encode(b"ls -la\n").decode()
+        raw = {"type": "output", "data": encoded}
+        event = _parse_pty_event(raw)
+        assert event.type == PtyEventType.output
+        assert event.data == b"ls -la\n"
+
+    def test_output_event_empty(self):
+        raw = {"type": "output", "data": ""}
+        event = _parse_pty_event(raw)
+        assert event.data == b""
+
+    def test_exit_event(self):
+        raw = {"type": "exit", "exit_code": 0}
+        event = _parse_pty_event(raw)
+        assert event.type == PtyEventType.exit
+        assert event.exit_code == 0
+
+    def test_error_event(self):
+        raw = {"type": "error", "data": "process not found", "fatal": True}
+        event = _parse_pty_event(raw)
+        assert event.type == PtyEventType.error
+        assert event.data == "process not found"
+        assert event.fatal is True
+
+    def test_ping_event(self):
+        raw = {"type": "ping"}
+        event = _parse_pty_event(raw)
+        assert event.type == PtyEventType.ping
+
+
+class TestPtySessionWrite:
+    def test_write_sends_base64_input(self):
+        ws = MagicMock()
+        session = PtySession(ws, "cl-abc")
+        session.write(b"ls -la\n")
+        sent = json.loads(ws.send_text.call_args[0][0])
+        assert sent["type"] == "input"
+        assert base64.b64decode(sent["data"]) == b"ls -la\n"
+
+
+class TestPtySessionResize:
+    def test_resize_sends_dimensions(self):
+        ws = MagicMock()
+        session = PtySession(ws, "cl-abc")
+        session.resize(120, 40)
+        sent = json.loads(ws.send_text.call_args[0][0])
+        assert sent["type"] == "resize"
+        assert sent["cols"] == 120
+        assert sent["rows"] == 40
+
+    def test_resize_zero_raises(self):
+        ws = MagicMock()
+        session = PtySession(ws, "cl-abc")
+        with pytest.raises(ValueError, match="greater than 0"):
+            session.resize(0, 40)
+        with pytest.raises(ValueError, match="greater than 0"):
+            session.resize(80, 0)
+
+
+class TestPtySessionKill:
+    def test_kill_sends_message(self):
+        ws = MagicMock()
+        session = PtySession(ws, "cl-abc")
+        session.kill()
+        sent = json.loads(ws.send_text.call_args[0][0])
+        assert sent["type"] == "kill"
+
+
+class TestPtySessionIteration:
+    def test_iter_yields_events_until_exit(self):
+        ws = MagicMock()
+        messages = [
+            json.dumps({"type": "started", "tag": "pty-abc12345", "pid": 1}),
+            json.dumps({"type": "output", "data": base64.b64encode(b"hello").decode()}),
+            json.dumps({"type": "exit", "exit_code": 0}),
+        ]
+        ws.receive_text.side_effect = messages
+        session = PtySession(ws, "cl-abc")
+        events = list(session)
+        assert len(events) == 2
+        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"
+
+    def test_iter_stops_on_fatal_error(self):
+        ws = MagicMock()
+        messages = [
+            json.dumps({"type": "error", "data": "fatal", "fatal": True}),
+        ]
+        ws.receive_text.side_effect = messages
+        session = PtySession(ws, "cl-abc")
+        events = list(session)
+        assert len(events) == 1
+        assert events[0].type == PtyEventType.error
+
+    def test_iter_stops_on_disconnect(self):
+        import httpx_ws
+
+        ws = MagicMock()
+        ws.receive_text.side_effect = httpx_ws.WebSocketDisconnect()
+        session = PtySession(ws, "cl-abc")
+        events = list(session)
+        assert events == []
+
+
+class TestPtySessionContextManager:
+    def test_exit_kills_and_closes(self):
+        ws = MagicMock()
+        session = PtySession(ws, "cl-abc")
+        with session:
+            pass
+        ws.send_text.assert_called()
+        ws.close.assert_called()
+
+    def test_exit_ignores_errors(self):
+        ws = MagicMock()
+        ws.send_text.side_effect = Exception("already closed")
+        session = PtySession(ws, "cl-abc")
+        with session:
+            pass
+
+
+class TestPtySessionSendStart:
+    def test_send_start_with_defaults(self):
+        ws = MagicMock()
+        session = PtySession(ws, "cl-abc")
+        session._send_start()
+        sent = json.loads(ws.send_text.call_args[0][0])
+        assert sent["type"] == "start"
+        assert sent["cmd"] == "/bin/bash"
+        assert sent["cols"] == 80
+        assert sent["rows"] == 24
+
+    def test_send_start_with_all_params(self):
+        ws = MagicMock()
+        session = PtySession(ws, "cl-abc")
+        session._send_start(
+            cmd="/bin/zsh",
+            args=["-l"],
+            cols=120,
+            rows=40,
+            envs={"TERM": "xterm-256color"},
+            cwd="/home/user",
+        )
+        sent = json.loads(ws.send_text.call_args[0][0])
+        assert sent["cmd"] == "/bin/zsh"
+        assert sent["args"] == ["-l"]
+        assert sent["cols"] == 120
+
+
+class TestPtySessionSendConnect:
+    def test_send_connect(self):
+        ws = MagicMock()
+        session = PtySession(ws, "cl-abc")
+        session._send_connect("pty-abc12345")
+        sent = json.loads(ws.send_text.call_args[0][0])
+        assert sent["type"] == "connect"
+        assert sent["tag"] == "pty-abc12345"
+
+
+class TestAsyncPtySession:
+    @pytest.mark.asyncio
+    async def test_async_write_sends_base64(self):
+        ws = AsyncMock()
+        session = AsyncPtySession(ws, "cl-abc")
+        await session.write(b"hello")
+        sent = json.loads(ws.send_text.call_args[0][0])
+        assert sent["type"] == "input"
+        assert base64.b64decode(sent["data"]) == b"hello"
+
+    @pytest.mark.asyncio
+    async def test_async_resize(self):
+        ws = AsyncMock()
+        session = AsyncPtySession(ws, "cl-abc")
+        await session.resize(100, 30)
+        sent = json.loads(ws.send_text.call_args[0][0])
+        assert sent["type"] == "resize"
+        assert sent["cols"] == 100
+        assert sent["rows"] == 30
+
+    @pytest.mark.asyncio
+    async def test_async_resize_zero_raises(self):
+        ws = AsyncMock()
+        session = AsyncPtySession(ws, "cl-abc")
+        with pytest.raises(ValueError):
+            await session.resize(0, 10)
+
+    @pytest.mark.asyncio
+    async def test_async_kill(self):
+        ws = AsyncMock()
+        session = AsyncPtySession(ws, "cl-abc")
+        await session.kill()
+        sent = json.loads(ws.send_text.call_args[0][0])
+        assert sent["type"] == "kill"
+
+    @pytest.mark.asyncio
+    async def test_async_context_manager(self):
+        ws = AsyncMock()
+        session = AsyncPtySession(ws, "cl-abc")
+        async with session:
+            pass
+        ws.send_text.assert_called()
+        ws.close.assert_called()
+
+    @pytest.mark.asyncio
+    async def test_async_send_start(self):
+        ws = AsyncMock()
+        session = AsyncPtySession(ws, "cl-abc")
+        await session._send_start(cmd="/bin/zsh", cols=100, rows=30)
+        sent = json.loads(ws.send_text.call_args[0][0])
+        assert sent["type"] == "start"
+        assert sent["cmd"] == "/bin/zsh"
+        assert sent["cols"] == 100
+
+    @pytest.mark.asyncio
+    async def test_async_iteration(self):
+        ws = AsyncMock()
+        messages = [
+            json.dumps({"type": "started", "tag": "pty-xyz", "pid": 5}),
+            json.dumps({"type": "output", "data": base64.b64encode(b"hi").decode()}),
+            json.dumps({"type": "exit", "exit_code": 0}),
+        ]
+        ws.receive_text.side_effect = messages
+        session = AsyncPtySession(ws, "cl-abc")
+        events = []
+        async for event in session:
+            events.append(event)
+        assert len(events) == 2
+        assert events[0].type == PtyEventType.started
+        assert session.tag == "pty-xyz"
+        assert session.pid == 5
+
+
+class TestExports:
+    def test_file_entry_importable(self):
+        from wrenn import FileEntry as FE
+
+        assert FE is not None
+
+    def test_pty_session_importable(self):
+        from wrenn import PtySession as PS
+
+        assert PS is not None
+
+    def test_async_pty_session_importable(self):
+        from wrenn import AsyncPtySession as APS
+
+        assert APS is not None
+
+    def test_pty_event_importable(self):
+        from wrenn import PtyEvent as PE
+        from wrenn import PtyEventType as PET
+
+        assert PE is not None
+        assert PET is not None

tests/test_integration.py

@@ -0,0 +1,405 @@
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+
+import pytest
+
+from wrenn import Capsule, CommandResult
+from wrenn.commands import CommandHandle, ProcessInfo
+from wrenn.models import Capsule as CapsuleModel, FileEntry, Status
+
+pytestmark = pytest.mark.integration
+
+_env_loaded = False
+
+
+def _ensure_env() -> None:
+    global _env_loaded
+    if _env_loaded:
+        return
+    _env_loaded = True
+    env_file = Path(__file__).resolve().parent.parent / ".env"
+    if not env_file.exists():
+        return
+    for line in env_file.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key, value = key.strip(), value.strip().strip("\"'")
+        if key and key not in os.environ:
+            os.environ[key] = value
+
+
+class TestCapsuleLifecycle:
+    """Each test manages its own capsule to test create/destroy paths."""
+
+    def setup_method(self):
+        _ensure_env()
+
+    def test_create_and_destroy(self):
+        capsule = Capsule()
+        capsule_id = capsule.capsule_id
+        try:
+            assert capsule_id
+            assert capsule.info is not None
+        finally:
+            capsule.destroy()
+
+        info = Capsule.get_info(capsule_id)
+        assert info.status in (Status.stopped, Status.missing)
+
+    def test_create_with_wait(self):
+        capsule = Capsule(wait=True)
+        try:
+            assert capsule.info is not None
+            assert capsule.info.status == Status.running
+        finally:
+            capsule.destroy()
+
+    def test_context_manager_destroys(self):
+        with Capsule(wait=True) as capsule:
+            capsule_id = capsule.capsule_id
+            assert capsule.is_running()
+
+        info = Capsule.get_info(capsule_id)
+        assert info.status in (Status.stopped, Status.missing)
+
+    def test_get_info(self):
+        capsule = Capsule(wait=True)
+        try:
+            info = capsule.get_info()
+            assert isinstance(info, CapsuleModel)
+            assert info.id == capsule.capsule_id
+            assert info.status == Status.running
+        finally:
+            capsule.destroy()
+
+    def test_pause_and_resume(self):
+        capsule = Capsule(wait=True)
+        try:
+            paused = capsule.pause()
+            assert paused.status == Status.paused
+            assert not capsule.is_running()
+
+            resumed = capsule.resume()
+            assert resumed.status == Status.running
+        finally:
+            capsule.destroy()
+
+    def test_static_destroy(self):
+        capsule = Capsule(wait=True)
+        capsule_id = capsule.capsule_id
+        try:
+            Capsule.destroy(capsule_id)
+        except Exception:
+            capsule.destroy()
+            raise
+
+        info = Capsule.get_info(capsule_id)
+        assert info.status in (Status.stopped, Status.missing)
+
+    def test_connect_to_existing(self):
+        capsule = Capsule(wait=True)
+        try:
+            connected = Capsule.connect(capsule.capsule_id)
+            assert connected.capsule_id == capsule.capsule_id
+            assert connected.info is not None
+            assert connected.info.status == Status.running
+        finally:
+            capsule.destroy()
+
+    def test_connect_resumes_paused(self):
+        capsule = Capsule(wait=True)
+        try:
+            capsule.pause()
+            connected = Capsule.connect(capsule.capsule_id)
+            assert connected.info is not None
+            assert connected.info.status == Status.running
+        finally:
+            capsule.destroy()
+
+    def test_list_capsules(self):
+        capsule = Capsule(wait=True)
+        try:
+            capsules = Capsule.list()
+            assert isinstance(capsules, list)
+            ids = [c.id for c in capsules]
+            assert capsule.capsule_id in ids
+        finally:
+            capsule.destroy()
+
+    def test_wait_ready(self):
+        capsule = Capsule()
+        try:
+            capsule.wait_ready(timeout=60)
+            assert capsule.is_running()
+        finally:
+            capsule.destroy()
+
+    def test_ping(self):
+        capsule = Capsule(wait=True)
+        try:
+            capsule.ping()
+        finally:
+            capsule.destroy()
+
+
+class TestCommands:
+    """Shared capsule for command execution tests."""
+
+    capsule: Capsule
+
+    @classmethod
+    def setup_class(cls):
+        _ensure_env()
+        cls.capsule = Capsule(wait=True)
+
+    @classmethod
+    def teardown_class(cls):
+        try:
+            cls.capsule.destroy()
+        except Exception:
+            pass
+
+    def test_run_foreground(self):
+        result = self.capsule.commands.run("echo hello")
+        assert isinstance(result, CommandResult)
+        assert result.exit_code == 0
+        assert "hello" in result.stdout
+
+    def test_run_stderr(self):
+        result = self.capsule.commands.run("echo error >&2")
+        assert "error" in result.stderr
+
+    def test_run_exit_code(self):
+        result = self.capsule.commands.run("exit 42")
+        assert result.exit_code == 42
+
+    def test_run_with_envs(self):
+        result = self.capsule.commands.run("export MY_VAR=test_value && echo $MY_VAR")
+        assert "test_value" in result.stdout
+
+    def test_run_with_cwd(self):
+        result = self.capsule.commands.run("cd /tmp && pwd")
+        assert result.stdout.strip() == "/tmp"
+
+    def test_run_multiline_output(self):
+        result = self.capsule.commands.run("echo -e 'line1\\nline2\\nline3'")
+        assert result.exit_code == 0
+        lines = result.stdout.strip().splitlines()
+        assert len(lines) == 3
+
+    def test_run_background(self):
+        handle = self.capsule.commands.run("sleep 30", background=True, tag="bg-test")
+        assert isinstance(handle, CommandHandle)
+        assert handle.pid > 0
+        assert handle.tag == "bg-test"
+        assert handle.capsule_id == self.capsule.capsule_id
+
+        self.capsule.commands.kill(handle.pid)
+
+    def test_list_processes(self):
+        handle = self.capsule.commands.run("sleep 30", background=True, tag="list-test")
+        try:
+            time.sleep(0.5)
+            processes = self.capsule.commands.list()
+            assert isinstance(processes, list)
+            pids = [p.pid for p in processes]
+            assert handle.pid in pids
+
+            proc = next(p for p in processes if p.pid == handle.pid)
+            assert isinstance(proc, ProcessInfo)
+        finally:
+            self.capsule.commands.kill(handle.pid)
+
+    def test_kill_process(self):
+        handle = self.capsule.commands.run("sleep 30", background=True)
+        self.capsule.commands.kill(handle.pid)
+        time.sleep(0.5)
+
+        processes = self.capsule.commands.list()
+        pids = [p.pid for p in processes]
+        assert handle.pid not in pids
+
+    def test_run_duration_ms(self):
+        result = self.capsule.commands.run("sleep 1")
+        assert result.duration_ms is None or result.duration_ms >= 900
+
+
+class TestFiles:
+    """Shared capsule for filesystem tests."""
+
+    capsule: Capsule
+
+    @classmethod
+    def setup_class(cls):
+        _ensure_env()
+        cls.capsule = Capsule(wait=True)
+
+    @classmethod
+    def teardown_class(cls):
+        try:
+            cls.capsule.destroy()
+        except Exception:
+            pass
+
+    def test_write_and_read(self):
+        self.capsule.files.write("/tmp/test.txt", "hello world")
+        content = self.capsule.files.read("/tmp/test.txt")
+        assert content == "hello world"
+
+    def test_write_and_read_bytes(self):
+        data = b"\x00\x01\x02\xff"
+        self.capsule.files.write("/tmp/test.bin", data)
+        result = self.capsule.files.read_bytes("/tmp/test.bin")
+        assert result == data
+
+    def test_list_directory(self):
+        self.capsule.files.write("/tmp/listdir/a.txt", "a")
+        self.capsule.files.write("/tmp/listdir/b.txt", "b")
+        entries = self.capsule.files.list("/tmp/listdir")
+        assert isinstance(entries, list)
+        names = [e.name for e in entries]
+        assert "a.txt" in names
+        assert "b.txt" in names
+
+    def test_exists(self):
+        self.capsule.files.write("/tmp/exists_test.txt", "x")
+        assert self.capsule.files.exists("/tmp/exists_test.txt")
+        assert not self.capsule.files.exists("/tmp/does_not_exist_xyz.txt")
+
+    def test_make_dir(self):
+        entry = self.capsule.files.make_dir("/tmp/newdir")
+        assert isinstance(entry, FileEntry)
+        assert self.capsule.files.exists("/tmp/newdir")
+
+    def test_make_dir_idempotent(self):
+        self.capsule.files.make_dir("/tmp/idempotent_dir")
+        entry = self.capsule.files.make_dir("/tmp/idempotent_dir")
+        assert isinstance(entry, FileEntry)
+
+    def test_remove_file(self):
+        self.capsule.files.write("/tmp/to_remove.txt", "delete me")
+        assert self.capsule.files.exists("/tmp/to_remove.txt")
+        self.capsule.files.remove("/tmp/to_remove.txt")
+        assert not self.capsule.files.exists("/tmp/to_remove.txt")
+
+    def test_remove_directory(self):
+        self.capsule.files.make_dir("/tmp/dir_to_remove")
+        self.capsule.files.write("/tmp/dir_to_remove/child.txt", "data")
+        self.capsule.files.remove("/tmp/dir_to_remove")
+        assert not self.capsule.files.exists("/tmp/dir_to_remove")
+
+    def test_write_creates_parent_dirs(self):
+        self.capsule.files.write("/tmp/deep/nested/dir/file.txt", "nested")
+        content = self.capsule.files.read("/tmp/deep/nested/dir/file.txt")
+        assert content == "nested"
+
+    def test_list_with_depth(self):
+        self.capsule.files.write("/tmp/depth_test/a/b.txt", "deep")
+        entries_shallow = self.capsule.files.list("/tmp/depth_test", depth=1)
+        entries_deep = self.capsule.files.list("/tmp/depth_test", depth=2)
+        assert len(entries_deep) >= len(entries_shallow)
+
+    def test_overwrite_file(self):
+        self.capsule.files.write("/tmp/overwrite.txt", "original")
+        self.capsule.files.write("/tmp/overwrite.txt", "updated")
+        content = self.capsule.files.read("/tmp/overwrite.txt")
+        assert content == "updated"
+
+    def test_upload_and_download_stream(self):
+        chunks = [b"chunk1", b"chunk2", b"chunk3"]
+        self.capsule.files.upload_stream("/tmp/streamed.bin", iter(chunks))
+        downloaded = b"".join(self.capsule.files.download_stream("/tmp/streamed.bin"))
+        assert downloaded == b"chunk1chunk2chunk3"
+
+
+class TestGit:
+    """Shared capsule for git operation tests.
+
+    Initializes a repo at /root (default cwd) since the exec API
+    does not support the cwd parameter.
+    """
+
+    capsule: Capsule
+
+    @classmethod
+    def setup_class(cls):
+        _ensure_env()
+        cls.capsule = Capsule(wait=True)
+        cls.capsule.git.init(".", initial_branch="main")
+        cls.capsule.git.configure_user("Test User", "test@example.com")
+
+    @classmethod
+    def teardown_class(cls):
+        try:
+            cls.capsule.destroy()
+        except Exception:
+            pass
+
+    def test_init_created_repo(self):
+        assert self.capsule.files.exists("/root/.git")
+
+    def test_status_clean(self):
+        status = self.capsule.git.status()
+        assert status.branch == "main"
+
+    def test_add_and_commit(self):
+        self.capsule.files.write("/root/hello.txt", "hello git")
+        self.capsule.git.add(all=True)
+        result = self.capsule.git.commit("initial commit")
+        assert result.exit_code == 0
+
+    def test_status_after_commit(self):
+        status = self.capsule.git.status()
+        assert status.is_clean
+
+    def test_status_with_changes(self):
+        self.capsule.files.write("/root/dirty.txt", "uncommitted")
+        try:
+            status = self.capsule.git.status()
+            assert not status.is_clean
+            paths = [f.path for f in status.files]
+            assert "dirty.txt" in paths
+        finally:
+            self.capsule.files.remove("/root/dirty.txt")
+
+    def test_branches(self):
+        branches = self.capsule.git.branches()
+        assert len(branches) >= 1
+        names = [b.name for b in branches]
+        assert "main" in names
+        current = [b for b in branches if b.is_current]
+        assert len(current) == 1
+
+    def test_create_and_checkout_branch(self):
+        self.capsule.git.create_branch("feature-1")
+        branches = self.capsule.git.branches()
+        names = [b.name for b in branches]
+        assert "feature-1" in names
+
+        current = [b for b in branches if b.is_current]
+        assert current[0].name == "feature-1"
+
+        self.capsule.git.checkout_branch("main")
+
+    def test_delete_branch(self):
+        self.capsule.git.create_branch("to-delete")
+        self.capsule.git.checkout_branch("main")
+        self.capsule.git.delete_branch("to-delete")
+
+        branches = self.capsule.git.branches()
+        names = [b.name for b in branches]
+        assert "to-delete" not in names
+
+    def test_set_and_get_config(self):
+        self.capsule.git.set_config("test.key", "test-value")
+        value = self.capsule.git.get_config("test.key")
+        assert value == "test-value"
+
+    def test_get_config_missing_returns_none(self):
+        value = self.capsule.git.get_config("nonexistent.key")
+        assert value is None