feat: add sandbox filesystem and terminal support

Add sandbox filesystem methods (list_dir, mkdir, remove, upload,
download, stream_upload, stream_download) and interactive PTY sessions
(PtySession, AsyncPtySession) with reconnect support per
FILE_TERMINAL.md spec. Refactor error handling into exceptions.py as
shared handle_response(). Replace API-key-only proxy auth with unified
_proxy_headers() supporting both API key and JWT. Fix stream_upload to
build multipart manually instead of relying on httpx files= with
generators. Switch Makefile SPEC_URL from main to dev branch. Regenerate
models from updated OpenAPI spec (adds teams, channels, metrics, PTY
endpoints). Add comprehensive unit and integration tests. Trim AGENTS.md
to verified facts only.

tests/test_filesystem_pty.py

@@ -0,0 +1,506 @@
+from __future__ import annotations
+
+import base64
+import json
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+import respx
+
+from wrenn.client import WrennClient
+from wrenn.models import FileEntry
+from wrenn.pty import (
+    AsyncPtySession,
+    PtyEventType,
+    PtySession,
+    _parse_pty_event,
+)
+from wrenn.sandbox import Sandbox
+
+
+@pytest.fixture
+def client():
+    with WrennClient(api_key="wrn_test1234567890abcdef12345678") as c:
+        yield c
+
+
+def _make_sandbox(client: WrennClient, sb_id: str = "cl-abc") -> Sandbox:
+    respx.post("https://api.wrenn.dev/v1/sandboxes").respond(
+        201, json={"id": sb_id, "status": "running"}
+    )
+    return client.sandboxes.create()
+
+
+class TestListDir:
+    @respx.mock
+    def test_list_dir_returns_entries(self, client):
+        sb = _make_sandbox(client)
+        respx.post("https://api.wrenn.dev/v1/sandboxes/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 = sb.list_dir("/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_dir_with_depth(self, client):
+        sb = _make_sandbox(client)
+        route = respx.post(
+            "https://api.wrenn.dev/v1/sandboxes/cl-abc/files/list"
+        ).respond(200, json={"entries": []})
+        sb.list_dir("/home/user", depth=3)
+        body = json.loads(route.calls[0].request.content)
+        assert body["depth"] == 3
+
+    @respx.mock
+    def test_list_dir_empty(self, client):
+        sb = _make_sandbox(client)
+        respx.post("https://api.wrenn.dev/v1/sandboxes/cl-abc/files/list").respond(
+            200, json={"entries": []}
+        )
+        entries = sb.list_dir("/empty")
+        assert entries == []
+
+    @respx.mock
+    def test_list_dir_symlink(self, client):
+        sb = _make_sandbox(client)
+        respx.post("https://api.wrenn.dev/v1/sandboxes/cl-abc/files/list").respond(
+            200,
+            json={
+                "entries": [
+                    {
+                        "name": "link",
+                        "path": "/home/user/link",
+                        "type": "symlink",
+                        "size": 4,
+                        "mode": 41471,
+                        "permissions": "lrwxrwxrwx",
+                        "owner": "root",
+                        "group": "root",
+                        "modified_at": 1712899000,
+                        "symlink_target": "/bin",
+                    }
+                ]
+            },
+        )
+        entries = sb.list_dir("/home/user")
+        assert len(entries) == 1
+        assert entries[0].type == "symlink"
+        assert entries[0].symlink_target == "/bin"
+
+
+class TestMkdir:
+    @respx.mock
+    def test_mkdir_returns_entry(self, client):
+        sb = _make_sandbox(client)
+        respx.post("https://api.wrenn.dev/v1/sandboxes/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 = sb.mkdir("/home/user/data")
+        assert isinstance(entry, FileEntry)
+        assert entry.name == "data"
+        assert entry.type == "directory"
+
+    @respx.mock
+    def test_mkdir_existing_returns_gracefully(self, client):
+        sb = _make_sandbox(client)
+        respx.post("https://api.wrenn.dev/v1/sandboxes/cl-abc/files/mkdir").respond(
+            409,
+            json={"error": {"code": "conflict", "message": "already exists"}},
+        )
+        respx.post("https://api.wrenn.dev/v1/sandboxes/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 = sb.mkdir("/home/user/data")
+        assert entry.name == "data"
+
+
+class TestRemove:
+    @respx.mock
+    def test_remove_succeeds(self, client):
+        sb = _make_sandbox(client)
+        route = respx.post(
+            "https://api.wrenn.dev/v1/sandboxes/cl-abc/files/remove"
+        ).respond(204)
+        sb.remove("/home/user/old_data")
+        assert route.called
+
+    @respx.mock
+    def test_remove_sends_path(self, client):
+        sb = _make_sandbox(client)
+        route = respx.post(
+            "https://api.wrenn.dev/v1/sandboxes/cl-abc/files/remove"
+        ).respond(204)
+        sb.remove("/tmp/test.txt")
+        body = json.loads(route.calls[0].request.content)
+        assert body["path"] == "/tmp/test.txt"
+
+
+class TestUpload:
+    @respx.mock
+    def test_upload_sends_multipart(self, client):
+        sb = _make_sandbox(client)
+        route = respx.post(
+            "https://api.wrenn.dev/v1/sandboxes/cl-abc/files/write"
+        ).respond(204)
+        sb.upload("/app/main.py", b"print('hello')")
+        assert route.called
+        req = route.calls[0].request
+        assert b"multipart/form-data" in req.headers.get("content-type", "").encode()
+
+    @respx.mock
+    def test_download_returns_bytes(self, client):
+        sb = _make_sandbox(client)
+        content = b"file contents here"
+        respx.post("https://api.wrenn.dev/v1/sandboxes/cl-abc/files/read").respond(
+            200, content=content
+        )
+        data = sb.download("/app/main.py")
+        assert data == content
+
+
+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_error_event_non_fatal(self):
+        raw = {"type": "error", "data": "something", "fatal": False}
+        event = _parse_pty_event(raw)
+        assert event.fatal is False
+
+    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
+        assert sent["rows"] == 40
+        assert sent["envs"] == {"TERM": "xterm-256color"}
+        assert sent["cwd"] == "/home/user"
+
+
+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
+        assert sent["rows"] == 30
+
+    @pytest.mark.asyncio
+    async def test_async_send_connect(self):
+        ws = AsyncMock()
+        session = AsyncPtySession(ws, "cl-abc")
+        await session._send_connect("pty-abc12345")
+        sent = json.loads(ws.send_text.call_args[0][0])
+        assert sent["type"] == "connect"
+        assert sent["tag"] == "pty-abc12345"
+
+    @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, PtyEventType as PET
+
+        assert PE is not None
+        assert PET is not None

tests/test_integration.py

@@ -7,6 +7,7 @@ import pytest
 
 from wrenn.client import AsyncWrennClient, WrennClient
 from wrenn.exceptions import WrennNotFoundError, WrennValidationError
+from wrenn.pty import PtyEventType
 
 WRENN_API_KEY = os.environ.get("WRENN_API_KEY")
 WRENN_TOKEN = os.environ.get("WRENN_TOKEN")
@@ -287,3 +288,281 @@ class TestAsyncSandboxLifecycle:
                 assert r.text == "84"
             finally:
                 await sb.async_destroy()
+
+
+@requires_auth
+class TestFilesystemListDir:
+    def test_list_dir_root(self, client: WrennClient):
+        with client.sandboxes.create(template="minimal", timeout_sec=120) as sb:
+            sb.wait_ready(timeout=60, interval=1)
+            sb.mkdir("/tmp/ls_test_root")
+            sb.upload("/tmp/ls_test_root/hello.txt", b"hello")
+            entries = sb.list_dir("/tmp/ls_test_root")
+            assert isinstance(entries, list)
+            names = [e.name for e in entries]
+            assert "hello.txt" in names
+
+    def test_list_dir_after_mkdir(self, client):
+        with client.sandboxes.create(template="minimal", timeout_sec=120) as sb:
+            sb.wait_ready(timeout=60, interval=1)
+            sb.mkdir("/tmp/fs_test_dir")
+            entries = sb.list_dir("/tmp")
+            names = [e.name for e in entries]
+            assert "fs_test_dir" in names
+
+    def test_list_dir_file_metadata(self, client):
+        with client.sandboxes.create(template="minimal", timeout_sec=120) as sb:
+            sb.wait_ready(timeout=60, interval=1)
+            sb.upload("/tmp/meta_test.txt", b"hello world")
+            entries = sb.list_dir("/tmp")
+            match = [e for e in entries if e.name == "meta_test.txt"]
+            assert len(match) == 1
+            f = match[0]
+            assert f.type == "file"
+            assert f.size == 11
+            assert f.permissions is not None
+            assert f.owner is not None
+            assert f.group is not None
+            assert f.modified_at is not None
+
+    def test_list_dir_depth(self, client):
+        with client.sandboxes.create(template="minimal", timeout_sec=120) as sb:
+            sb.wait_ready(timeout=60, interval=1)
+            sb.mkdir("/tmp/depth_a/depth_b")
+            sb.upload("/tmp/depth_a/depth_b/nested.txt", b"deep")
+            entries = sb.list_dir("/tmp/depth_a", depth=2)
+            paths = [e.path for e in entries]
+            assert any("nested.txt" in p for p in paths)
+
+    def test_list_dir_empty_directory(self, client):
+        with client.sandboxes.create(template="minimal", timeout_sec=120) as sb:
+            sb.wait_ready(timeout=60, interval=1)
+            sb.mkdir("/tmp/empty_dir_test")
+            entries = sb.list_dir("/tmp/empty_dir_test")
+            assert entries == []
+
+
+@requires_auth
+class TestFilesystemMkdir:
+    def test_mkdir_creates_directory(self, client):
+        with client.sandboxes.create(template="minimal", timeout_sec=120) as sb:
+            sb.wait_ready(timeout=60, interval=1)
+            entry = sb.mkdir("/tmp/mkdir_test")
+            assert entry.name == "mkdir_test"
+            assert entry.type == "directory"
+            assert entry.path == "/tmp/mkdir_test"
+
+    def test_mkdir_creates_parents(self, client):
+        with client.sandboxes.create(template="minimal", timeout_sec=120) as sb:
+            sb.wait_ready(timeout=60, interval=1)
+            entry = sb.mkdir("/tmp/a/b/c/d")
+            assert entry.type == "directory"
+
+    def test_mkdir_already_exists(self, client: WrennClient):
+        with client.sandboxes.create(template="minimal", timeout_sec=120) as sb:
+            sb.wait_ready(timeout=60, interval=1)
+            sb.mkdir("/tmp/exist_test")
+            entry = sb.mkdir("/tmp/exist_test")
+            assert entry.type == "directory"
+
+
+@requires_auth
+class TestFilesystemRemove:
+    def test_remove_file(self, client):
+        with client.sandboxes.create(template="minimal", timeout_sec=120) as sb:
+            sb.wait_ready(timeout=60, interval=1)
+            sb.upload("/tmp/rm_test.txt", b"delete me")
+            entries_before = sb.list_dir("/tmp")
+            assert any(e.name == "rm_test.txt" for e in entries_before)
+            sb.remove("/tmp/rm_test.txt")
+            entries_after = sb.list_dir("/tmp")
+            assert not any(e.name == "rm_test.txt" for e in entries_after)
+
+    def test_remove_directory(self, client):
+        with client.sandboxes.create(template="minimal", timeout_sec=120) as sb:
+            sb.wait_ready(timeout=60, interval=1)
+            sb.mkdir("/tmp/rm_dir_test")
+            sb.upload("/tmp/rm_dir_test/file.txt", b"inside")
+            sb.remove("/tmp/rm_dir_test")
+            entries = sb.list_dir("/tmp")
+            assert not any(e.name == "rm_dir_test" for e in entries)
+
+    def test_upload_download_remove_roundtrip(self, client):
+        with client.sandboxes.create(template="minimal", timeout_sec=120) as sb:
+            sb.wait_ready(timeout=60, interval=1)
+            content = b"round trip test data " * 100
+            sb.upload("/tmp/rt.txt", content)
+            downloaded = sb.download("/tmp/rt.txt")
+            assert downloaded == content
+            sb.remove("/tmp/rt.txt")
+            with pytest.raises(Exception):
+                sb.download("/tmp/rt.txt")
+
+
+@requires_auth
+class TestStreamUploadDownload:
+    def test_stream_upload_and_download(self, client: WrennClient):
+        with client.sandboxes.create(template="minimal", timeout_sec=120) as sb:
+            sb.wait_ready(timeout=60, interval=1)
+            chunks = [b"chunk0_", b"chunk1_", b"chunk2"]
+
+            def data_gen():
+                yield from chunks
+
+            sb.stream_upload("/tmp/stream_test.bin", data_gen())
+            downloaded = sb.download("/tmp/stream_test.bin")
+            assert downloaded == b"chunk0_chunk1_chunk2"
+
+    def test_stream_download_large(self, client):
+        with client.sandboxes.create(template="minimal", timeout_sec=120) as sb:
+            sb.wait_ready(timeout=60, interval=1)
+            content = b"x" * 65536 * 3
+            sb.upload("/tmp/large.bin", content)
+            collected = b""
+            for chunk in sb.stream_download("/tmp/large.bin"):
+                collected += chunk
+            assert collected == content
+
+
+@requires_auth
+class TestPty:
+    def test_pty_basic_output(self, client):
+        with client.sandboxes.create(template="minimal", timeout_sec=120) as sb:
+            sb.wait_ready(timeout=60, interval=1)
+            with sb.pty(cmd="/bin/sh", cwd="/tmp") as term:
+                term.write(b"echo pty_hello\n")
+                output = b""
+                for event in term:
+                    if event.type == PtyEventType.output:
+                        output += event.data
+                    elif event.type == PtyEventType.exit:
+                        break
+                    if b"pty_hello" in output:
+                        term.write(b"exit\n")
+                assert b"pty_hello" in output
+
+    def test_pty_tag_and_pid(self, client):
+        with client.sandboxes.create(template="minimal", timeout_sec=120) as sb:
+            sb.wait_ready(timeout=60, interval=1)
+            with sb.pty(cmd="/bin/sh") as term:
+                started = False
+                for event in term:
+                    if event.type == PtyEventType.started:
+                        started = True
+                        assert term.tag is not None
+                        assert term.pid is not None
+                        assert term.tag.startswith("pty-")
+                    elif event.type == PtyEventType.output:
+                        term.write(b"exit\n")
+                    elif event.type == PtyEventType.exit:
+                        break
+                assert started
+
+    def test_pty_exit_on_command_exit(self, client):
+        with client.sandboxes.create(template="minimal", timeout_sec=120) as sb:
+            sb.wait_ready(timeout=60, interval=1)
+            with sb.pty(cmd="/bin/echo", args=["immediate"]) as term:
+                events = list(term)
+                types = [e.type for e in events]
+                assert PtyEventType.started in types
+                assert PtyEventType.output in types or PtyEventType.exit in types
+
+    def test_pty_resize(self, client):
+        with client.sandboxes.create(template="minimal", timeout_sec=120) as sb:
+            sb.wait_ready(timeout=60, interval=1)
+            with sb.pty(cmd="/bin/sh", cols=80, rows=24) as term:
+                for event in term:
+                    if event.type == PtyEventType.started:
+                        term.resize(120, 40)
+                        term.write(b"exit\n")
+                    elif event.type == PtyEventType.exit:
+                        break
+
+    def test_pty_envs(self, client):
+        with client.sandboxes.create(template="minimal", timeout_sec=120) as sb:
+            sb.wait_ready(timeout=60, interval=1)
+            with sb.pty(cmd="/bin/sh", envs={"MY_VAR": "hello_env"}) as term:
+                output = b""
+                for event in term:
+                    if event.type == PtyEventType.started:
+                        term.write(b"echo $MY_VAR\n")
+                    elif event.type == PtyEventType.output:
+                        output += event.data
+                        if b"hello_env" in output:
+                            term.write(b"exit\n")
+                    elif event.type == PtyEventType.exit:
+                        break
+                assert b"hello_env" in output
+
+
+@requires_auth
+class TestAsyncFilesystem:
+    @pytest.mark.asyncio
+    async def test_async_list_dir(self, async_client):
+        async with async_client:
+            sb = await async_client.sandboxes.create(
+                template="minimal", timeout_sec=120
+            )
+            try:
+                await sb.async_wait_ready(timeout=60, interval=1)
+                await sb.async_mkdir("/tmp/async_ls_test")
+                await sb.async_upload("/tmp/async_ls_test/file.txt", b"data")
+                entries = await sb.async_list_dir("/tmp/async_ls_test")
+                assert isinstance(entries, list)
+                assert any(e.name == "file.txt" for e in entries)
+            finally:
+                await sb.async_destroy()
+
+    @pytest.mark.asyncio
+    async def test_async_mkdir(self, async_client):
+        async with async_client:
+            sb = await async_client.sandboxes.create(
+                template="minimal", timeout_sec=120
+            )
+            try:
+                await sb.async_wait_ready(timeout=60, interval=1)
+                entry = await sb.async_mkdir("/tmp/async_mkdir_test")
+                assert entry.type == "directory"
+                assert entry.name == "async_mkdir_test"
+            finally:
+                await sb.async_destroy()
+
+    @pytest.mark.asyncio
+    async def test_async_remove(self, async_client):
+        async with async_client:
+            sb = await async_client.sandboxes.create(
+                template="minimal", timeout_sec=120
+            )
+            try:
+                await sb.async_wait_ready(timeout=60, interval=1)
+                await sb.async_upload("/tmp/async_rm.txt", b"bye")
+                entries = await sb.async_list_dir("/tmp")
+                assert any(e.name == "async_rm.txt" for e in entries)
+                await sb.async_remove("/tmp/async_rm.txt")
+                entries = await sb.async_list_dir("/tmp")
+                assert not any(e.name == "async_rm.txt" for e in entries)
+            finally:
+                await sb.async_destroy()
+
+    @pytest.mark.asyncio
+    async def test_async_full_filesystem_roundtrip(self, async_client):
+        async with async_client:
+            sb = await async_client.sandboxes.create(
+                template="minimal", timeout_sec=120
+            )
+            try:
+                await sb.async_wait_ready(timeout=60, interval=1)
+
+                await sb.async_mkdir("/tmp/async_rt")
+                await sb.async_upload("/tmp/async_rt/file.txt", b"async content")
+                entries = await sb.async_list_dir("/tmp/async_rt")
+                assert any(e.name == "file.txt" for e in entries)
+
+                data = await sb.async_download("/tmp/async_rt/file.txt")
+                assert data == b"async content"
+
+                await sb.async_remove("/tmp/async_rt/file.txt")
+                entries = await sb.async_list_dir("/tmp/async_rt")
+                assert not any(e.name == "file.txt" for e in entries)
+            finally:
+                await sb.async_destroy()

tests/test_sandbox_features.py

@@ -5,7 +5,6 @@ import pytest
 import respx
 
 from wrenn.client import WrennClient
-from wrenn.exceptions import WrennAuthenticationError
 from wrenn.sandbox import CodeResult, Sandbox, _build_proxy_url
 
 
@@ -57,22 +56,6 @@ class TestSandboxGetUrl:
             assert url == "ws://3000-cl-xyz.localhost:8080"
 
 
-class TestProxyAuthGuard:
-    def test_jwt_only_get_url_raises(self):
-        with WrennClient(token="jwt-abc") as c:
-            sb = Sandbox(id="cl-abc")
-            sb._bind(c._http, str(c._http.base_url), api_key=None, token="jwt-abc")
-            with pytest.raises(WrennAuthenticationError):
-                sb.get_url(8888)
-
-    def test_jwt_only_http_client_raises(self):
-        with WrennClient(token="jwt-abc") as c:
-            sb = Sandbox(id="cl-abc")
-            sb._bind(c._http, str(c._http.base_url), api_key=None, token="jwt-abc")
-            with pytest.raises(WrennAuthenticationError):
-                _ = sb.http_client
-
-
 class TestSandboxHttpClient:
     @respx.mock
     def test_http_client_has_api_key_header(self, client):
@@ -96,6 +79,20 @@ class TestSandboxHttpClient:
         assert resp.status_code == 200
         assert route.called
 
+    def test_jwt_only_get_url_works(self):
+        with WrennClient(token="jwt-abc") as c:
+            sb = Sandbox(id="cl-abc")
+            sb._bind(c._http, str(c._http.base_url), api_key=None, token="jwt-abc")
+            url = sb.get_url(8888)
+            assert "8888-cl-abc" in url
+
+    def test_jwt_only_http_client_has_bearer_header(self):
+        with WrennClient(token="jwt-abc") as c:
+            sb = Sandbox(id="cl-abc")
+            sb._bind(c._http, str(c._http.base_url), api_key=None, token="jwt-abc")
+            hc = sb.http_client
+            assert hc.headers["Authorization"] == "Bearer jwt-abc"
+
 
 class TestCreateReturnsBoundSandbox:
     @respx.mock
@@ -148,15 +145,6 @@ class TestCodeResult:
         assert "ZeroDivisionError" in r.error
 
 
-class TestRunCodeAuthGuard:
-    def test_jwt_only_run_code_raises(self):
-        with WrennClient(token="jwt-abc") as c:
-            sb = Sandbox(id="cl-abc")
-            sb._bind(c._http, str(c._http.base_url), api_key=None, token="jwt-abc")
-            with pytest.raises(WrennAuthenticationError):
-                sb.run_code("print(1)")
-
-
 class TestJupyterMessageFormat:
     def test_execute_request_structure(self):
         sb = Sandbox(id="test")