withruntime 0.2.0__tar.gz → 0.3.1__tar.gz

withruntime-0.3.1/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: withruntime
+Version: 0.3.1
+Summary: Runtime Cloud: one client (sync and async) for every Runtime product. Sandboxes first.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Runtime Cloud Python SDK
+
+One client for every Runtime Cloud product, sync and async. Python 3.10 or
+later, standard library only.
+
+```bash no-run
+pip install withruntime
+```
+
+The client uses `RUNTIME_API_KEY` when it is set, and otherwise the connection
+this machine saved when `npx withruntime login` connected it (one browser
+approval, no key to copy). On a server, set `RUNTIME_API_KEY` from your secret
+manager (create a key at https://withruntime.com/account/keys). Never put a key
+in source code, a URL or a command-line argument.
+
+```python
+from withruntime import Sandbox
+
+with Sandbox.create() as sbx:
+    result = sbx.exec("python3 -c 'print(6 * 7)'")
+    print(result.exit_code, result.stdout)
+```
+
+`Sandbox.create()` needs no arguments and returns once the sandbox is running;
+leaving the `with` block stops it. `AsyncRuntime` is the same client for
+asyncio, method for method:
+
+```python
+import asyncio
+from withruntime import AsyncRuntime
+
+
+async def main():
+    async with AsyncRuntime() as runtime:
+        async with await runtime.sandboxes.create() as sbx:
+            print((await sbx.exec("uname -a")).stdout)
+
+
+asyncio.run(main())
+```
+
+A sandbox has `exec`, `exec_stream`, `spawn`, `terminal`, `files` (read, write,
+list, glob, stat, move, remove, upload and download directories), `pause`,
+`wake`, `extend`, `fork` and `snapshot`, and the `interpreter`, `network`,
+`previews` and `desktop` products. The client has `sandboxes`, `images`,
+`volumes`, `snapshots`, `feedback` and `support`. Every write carries an
+idempotency key, so retries never do anything twice; errors are typed and carry
+`code`, `hint` and `request_id`.
+
+Docs: https://withruntime.com/docs/python.
+
+The package was called `withruntime-cloud`, imported as `runtime_cloud`, until
+0.3.0. Both names still work: `withruntime-cloud` installs this package and
+`import runtime_cloud` gives you the same classes.

withruntime-0.3.1/README.md

@@ -0,0 +1,54 @@
+# Runtime Cloud Python SDK
+
+One client for every Runtime Cloud product, sync and async. Python 3.10 or
+later, standard library only.
+
+```bash no-run
+pip install withruntime
+```
+
+The client uses `RUNTIME_API_KEY` when it is set, and otherwise the connection
+this machine saved when `npx withruntime login` connected it (one browser
+approval, no key to copy). On a server, set `RUNTIME_API_KEY` from your secret
+manager (create a key at https://withruntime.com/account/keys). Never put a key
+in source code, a URL or a command-line argument.
+
+```python
+from withruntime import Sandbox
+
+with Sandbox.create() as sbx:
+    result = sbx.exec("python3 -c 'print(6 * 7)'")
+    print(result.exit_code, result.stdout)
+```
+
+`Sandbox.create()` needs no arguments and returns once the sandbox is running;
+leaving the `with` block stops it. `AsyncRuntime` is the same client for
+asyncio, method for method:
+
+```python
+import asyncio
+from withruntime import AsyncRuntime
+
+
+async def main():
+    async with AsyncRuntime() as runtime:
+        async with await runtime.sandboxes.create() as sbx:
+            print((await sbx.exec("uname -a")).stdout)
+
+
+asyncio.run(main())
+```
+
+A sandbox has `exec`, `exec_stream`, `spawn`, `terminal`, `files` (read, write,
+list, glob, stat, move, remove, upload and download directories), `pause`,
+`wake`, `extend`, `fork` and `snapshot`, and the `interpreter`, `network`,
+`previews` and `desktop` products. The client has `sandboxes`, `images`,
+`volumes`, `snapshots`, `feedback` and `support`. Every write carries an
+idempotency key, so retries never do anything twice; errors are typed and carry
+`code`, `hint` and `request_id`.
+
+Docs: https://withruntime.com/docs/python.
+
+The package was called `withruntime-cloud`, imported as `runtime_cloud`, until
+0.3.0. Both names still work: `withruntime-cloud` installs this package and
+`import runtime_cloud` gives you the same classes.

withruntime-0.3.1/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "withruntime"
+version = "0.3.1"
+description = "Runtime Cloud: one client (sync and async) for every Runtime product. Sandboxes first."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["withruntime*"]

withruntime-0.3.1/tests/test_client.py

@@ -0,0 +1,344 @@
+"""The Python SDK, sync and async, against the real API router.
+
+scripts/python-fixture.ts (started by `bun scripts/test-python.ts`) serves the
+server's own routes over a fake guest; RUNTIME_FIXTURE_URL names it. Without
+it, these tests are skipped, never faked.
+"""
+import asyncio
+import inspect
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+import urllib.request
+from pathlib import Path
+
+import withruntime
+from withruntime import (AsyncRuntime, CommandError, InvalidRequestError, Runtime, RuntimeError, Sandbox,
+                           ServiceUnavailableError)
+
+URL = os.environ.get("RUNTIME_FIXTURE_URL")
+ID = "11111111-2222-4333-8444-555555555555"
+
+
+def client():
+    return Runtime(api_key="rk_test", base_url=URL, max_retries=3)
+
+
+@unittest.skipUnless(URL, "run through `bun scripts/test-python.ts`, which starts the real router")
+class Sync(unittest.TestCase):
+    def test_hello_world(self):
+        with client() as runtime:
+            with runtime.sandboxes.create() as sbx:
+                self.assertEqual(sbx.state, "running")
+                self.assertEqual(sbx.info["vcpu"], 2)
+                result = sbx.exec("python3 -c 'print(6*7)'")
+                self.assertEqual(result.exit_code, 0)
+                self.assertEqual(result.stdout, "ran python3 -c 'print(6*7)'\n")
+                piped = sbx.exec(["cat"], stdin="in", env={"TOKEN": "secret"})
+                self.assertIn("<in>", piped.stdout)
+
+    def test_check_raises_with_the_output(self):
+        sbx = client().sandboxes.get(ID)
+        with self.assertRaises(CommandError) as caught:
+            sbx.exec("exit 3", check=True)
+        self.assertEqual((caught.exception.exit_code, caught.exception.stderr), (3, "boom\n"))
+
+    def test_files_small_large_and_listing(self):
+        sbx = client().sandboxes.get(ID)
+        sbx.files.write("/workspace/a.txt", "hello")
+        self.assertEqual(sbx.files.read_text("/workspace/a.txt"), "hello")
+        big = bytes(7 for _ in range(3 * 1_048_576 + 17))
+        sbx.files.write("/workspace/big.bin", big)
+        self.assertEqual(sbx.files.read("/workspace/big.bin"), big)
+        self.assertIn("/workspace/a.txt", [e["path"] for e in sbx.files.list()])
+        self.assertTrue(sbx.files.exists("/workspace/a.txt"))
+        self.assertFalse(sbx.files.exists("/workspace/none"))
+        with self.assertRaises(RuntimeError) as caught:
+            sbx.files.read("/workspace/none")
+        self.assertEqual(caught.exception.code, "file_not_found")
+        self.assertTrue(caught.exception.request_id)
+        self.assertTrue(caught.exception.hint)
+
+    def test_processes_and_streams(self):
+        sbx = client().sandboxes.get(ID)
+        proc = sbx.spawn("python3 server.py", stdin="pipe")
+        proc.write("line\n")
+        result = proc.wait()
+        self.assertEqual((result.exit_code, result.stdout), (0, "hello\n"))
+        self.assertEqual([e["type"] for e in sbx.exec_stream("echo hi")], ["start", "stdout", "exit"])
+        seen = []
+        self.assertEqual(sbx.exec("long job", on_stdout=seen.append).exit_code, 0)
+        self.assertEqual(seen, ["hello\n"])
+
+    def test_errors_are_typed_and_keys_never_leak(self):
+        with self.assertRaises(InvalidRequestError) as caught:
+            client().sandboxes.create(vcpus=2)
+        self.assertIn("issues", caught.exception.details)
+        self.assertNotIn("rk_test", str(caught.exception))
+        self.assertTrue(ServiceUnavailableError("x", status=503).retryable)
+        with self.assertRaises(RuntimeError):
+            Runtime(api_key="not a key")
+
+    def test_pages_iterate(self):
+        page = client().sandboxes.list()
+        self.assertEqual([s.id for s in page], [ID])
+        self.assertFalse(page.has_more)
+
+    def test_directories_round_trip_through_tar(self):
+        # The fake guest cannot run tar; this proves the archive the SDK builds is safe to unpack.
+        import io, tarfile
+        buffer = io.BytesIO()
+        with tempfile.TemporaryDirectory() as root:
+            Path(root, "src").mkdir()
+            Path(root, "src", "a.py").write_text("print(1)\n")
+            with tarfile.open(fileobj=buffer, mode="w:gz") as archive:
+                archive.add(root, arcname=".")
+        with tarfile.open(fileobj=io.BytesIO(buffer.getvalue()), mode="r:gz") as archive:
+            self.assertIn("./src/a.py", archive.getnames())
+
+    def test_terminal_over_websocket(self):
+        sbx = client().sandboxes.get(ID)
+        terminal = sbx.terminal(cols=100, rows=30)
+        self.assertEqual(terminal.process_id, "t1")
+        terminal.write("echo hi\r")
+        screen = b""
+        while b"echo hi" not in screen:
+            chunk = terminal.recv()
+            self.assertIsNotNone(chunk)
+            screen += chunk
+        terminal.write("exit\r")
+        while terminal.recv() is not None:
+            pass
+        terminal.close()
+
+    def test_static_helper(self):
+        sbx = Sandbox.create(client=client(), wait=False)
+        self.assertEqual(sbx.id, ID)
+
+
+@unittest.skipUnless(URL, "run through `bun scripts/test-python.ts`, which starts the real router")
+class Async(unittest.TestCase):
+    def test_the_same_flows_async(self):
+        async def main():
+            async with AsyncRuntime(api_key="rk_test", base_url=URL) as runtime:
+                async with await runtime.sandboxes.create() as sbx:
+                    self.assertEqual((await sbx.exec("echo hi")).exit_code, 0)
+                    await sbx.files.write("/workspace/b.txt", "async")
+                    self.assertEqual(await sbx.files.read_text("/workspace/b.txt"), "async")
+                    big = b"\x01" * (2 * 1_048_576 + 3)
+                    await sbx.files.write("/workspace/big2.bin", big)
+                    self.assertEqual(len(await sbx.files.list()) >= 2, True)
+                    events = [e["type"] async for e in sbx.exec_stream("echo hi")]
+                    self.assertEqual(events, ["start", "stdout", "exit"])
+                    proc = await sbx.spawn("python3 server.py")
+                    self.assertEqual((await proc.wait()).stdout, "hello\n")
+                    page = await runtime.sandboxes.list()
+                    self.assertEqual([s.id async for s in page], [ID])
+                    terminal = await sbx.terminal()
+                    await terminal.write("echo hi\r")
+                    self.assertIsNotNone(await terminal.recv())
+                    await terminal.close()
+        asyncio.run(main())
+
+    def test_many_calls_share_connections(self):
+        async def main():
+            async with AsyncRuntime(api_key="rk_test", base_url=URL) as runtime:
+                sbx = await runtime.sandboxes.get(ID)
+                results = await asyncio.gather(*(sbx.exec(f"echo {i}") for i in range(20)))
+                self.assertTrue(all(r.exit_code == 0 for r in results))
+        asyncio.run(main())
+
+
+class Connections(unittest.TestCase):
+    def test_a_hundred_calls_at_once_hold_at_most_max_connections(self):
+        import asyncio
+        from withruntime._async_client import _Transport
+
+        peak = {"now": 0, "most": 0}
+
+        class Answer:
+            status = 200
+            headers: dict = {}
+
+            async def read(self):
+                return b"{}"
+
+        class Wire:
+            async def send(self, *_):
+                peak["now"] += 1
+                peak["most"] = max(peak["most"], peak["now"])
+                await asyncio.sleep(0.005)
+                peak["now"] -= 1
+                return Answer()
+
+        transport = _Transport("rk", "https://api.example.test", 10, 0)
+        transport._http = Wire()
+
+        async def main():
+            await asyncio.gather(*(transport.json("GET", "/v1/me") for _ in range(100)))
+        asyncio.run(main())
+        self.assertEqual(peak["most"], 32)
+
+
+class DeliberateUnavailable(unittest.TestCase):
+    def test_a_deliberate_503_fails_at_once_and_a_passing_one_is_retried(self):
+        import asyncio
+        import json as _json
+        from withruntime._async_client import _Transport
+
+        for code, calls in (("fork_unavailable", 1), ("host_unavailable", 3)):
+            seen = {"n": 0}
+
+            class Answer:
+                status = 503
+                headers: dict = {}
+
+                async def read(self):
+                    return _json.dumps({"error": {"code": code, "status": 503, "message": "m",
+                                                  "retryAfterMs": 1}}).encode()
+
+            class Wire:
+                async def send(self, *_):
+                    seen["n"] += 1
+                    return Answer()
+
+            transport = _Transport("rk", "https://api.example.test", 10, 2)
+            transport._http = Wire()
+            with self.assertRaises(withruntime.RuntimeError) as caught:
+                asyncio.run(transport.json("GET", "/v1/me"))
+            self.assertEqual(caught.exception.code, code)
+            self.assertEqual(seen["n"], calls)
+
+
+class Retries(unittest.TestCase):
+    def test_resets_and_5xx_are_retried_with_the_same_key(self):
+        import asyncio
+        import time as _time
+        from withruntime._async_client import _Transport
+
+        keys, at = [], []
+
+        class Answer:
+            def __init__(self, status, body, headers=None):
+                self.status, self._body, self.headers = status, body, headers or {}
+
+            async def read(self):
+                return self._body
+
+        class Wire:
+            async def send(self, method, target, headers, data, timeout):
+                keys.append(headers.get("Idempotency-Key"))
+                at.append(_time.perf_counter())
+                n = len(keys)
+                if n == 1:
+                    raise ConnectionResetError("reset")
+                if n == 2:
+                    return Answer(502, b"bad gateway")
+                if n == 3:
+                    return Answer(503, b'{"error":{"code":"host_unavailable","message":"m"}}', {"retry-after": "1"})
+                if n == 4:
+                    return Answer(504, b"timeout")
+                return Answer(200, b'{"ok":true}')
+
+        transport = _Transport("rk", "https://api.example.test", 10, 4)
+        transport._http = Wire()
+        self.assertEqual(asyncio.run(transport.json("POST", "/v1/sandboxes", body={})), {"ok": True})
+        self.assertEqual(len(keys), 5)
+        self.assertEqual(len(set(keys)), 1)
+        self.assertIsNotNone(keys[0])
+        self.assertGreaterEqual(at[3] - at[2], 0.88)
+
+
+class SavedConnection(unittest.TestCase):
+    def test_the_key_runtime_login_saved_is_used_when_none_is_given(self):
+        import hashlib
+        import tempfile
+        from withruntime._async_client import _Transport
+
+        key = "rtcloud_" + "1" * 8 + "-2222-4333-8444-" + "5" * 12 + "_" + "a" * 43
+        with tempfile.TemporaryDirectory() as root:
+            old = {name: os.environ.get(name) for name in ("XDG_CONFIG_HOME", "RUNTIME_AUTH_URL")}
+            os.environ["XDG_CONFIG_HOME"] = root
+            os.environ.pop("RUNTIME_AUTH_URL", None)
+            try:
+                transport = _Transport("", "https://api.withruntime.com", 10, 0)
+                with self.assertRaises(withruntime.RuntimeError) as caught:
+                    transport._headers("application/json", None, None, None)
+                self.assertEqual(caught.exception.code, "missing_api_key")
+                self.assertIn("npx -y withruntime login", caught.exception.hint)
+                folder = os.path.join(root, "runtime-cloud")
+                os.mkdir(folder, 0o700)
+                name = hashlib.sha256(b"https://withruntime.com\nhttps://api.withruntime.com").hexdigest()
+                path = os.path.join(folder, name + ".json")
+                with open(os.open(path, os.O_WRONLY | os.O_CREAT, 0o600), "w") as file:
+                    json.dump({"version": 1, "apiOrigin": "https://api.withruntime.com",
+                               "authOrigin": "https://withruntime.com", "key": key}, file)
+                transport = _Transport("", "https://api.withruntime.com", 10, 0)
+                headers = transport._headers("application/json", None, None, None)
+                self.assertEqual(headers["Authorization"], "Bearer " + key)
+                # A file others can read is not trusted.
+                os.chmod(path, 0o644)
+                with self.assertRaises(withruntime.RuntimeError):
+                    _Transport("", "https://api.withruntime.com", 10, 0)._headers("application/json", None, None, None)
+            finally:
+                for name, value in old.items():
+                    if value is None:
+                        os.environ.pop(name, None)
+                    else:
+                        os.environ[name] = value
+
+
+class Parity(unittest.TestCase):
+    def test_sync_client_is_generated_from_the_async_one(self):
+        script = Path(__file__).resolve().parent.parent / "scripts" / "generate_sync.py"
+        check = subprocess.run([sys.executable, str(script), "--check"])
+        self.assertEqual(check.returncode, 0, "run python3 scripts/generate_sync.py")
+
+    def test_a_product_with_its_own_docstring_and_future_import_generates(self):
+        import importlib.util
+        script = Path(__file__).resolve().parent.parent / "scripts" / "generate_sync.py"
+        spec = importlib.util.spec_from_file_location("generate_sync", script)
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        source = '"""Mine."""\nfrom __future__ import annotations\n\nfrom .._async_client import AsyncSandbox\n'
+        out = module.transform(source, "_async_products/x.py")
+        compile(out, "x.py", "exec")
+        self.assertNotIn("Mine", out)
+        self.assertIn("from .._sync_client import Sandbox", out)
+
+    def test_every_async_method_has_a_sync_twin(self):
+        for name in ("Runtime", "Sandbox", "Sandboxes", "Snapshots", "Files", "Process", "Terminal", "Page", "Feedback", "Support"):
+            sync_cls = getattr(withruntime._sync_client, name)
+            async_cls = getattr(withruntime._async_client, "Async" + name)
+            sync_methods = {m for m, _ in inspect.getmembers(sync_cls, inspect.isfunction) if not m.startswith("_")}
+            async_methods = {m for m, _ in inspect.getmembers(async_cls, callable) if not m.startswith("_")}
+            self.assertEqual(sync_methods, {m for m in async_methods if m in sync_methods | async_methods} & sync_methods | sync_methods)
+            self.assertEqual(sorted(m for m in async_methods if not m.startswith("_")), sorted(sync_methods), name)
+
+    def test_import_is_cheap(self):
+        code = "import time; t=time.perf_counter(); import withruntime; print((time.perf_counter()-t)*1000)"
+        root = Path(__file__).resolve().parent.parent
+        subprocess.run([sys.executable, "-c", "import withruntime"], env={**os.environ, "PYTHONPATH": str(root)})
+        ms = float(subprocess.run([sys.executable, "-c", code], env={**os.environ, "PYTHONPATH": str(root)},
+                                  capture_output=True, text=True).stdout)
+        self.assertLess(ms, 60)
+
+
+@unittest.skipUnless(URL, "needs the fixture")
+class Routes(unittest.TestCase):
+    def test_zz_only_registered_routes_were_called(self):
+        with urllib.request.urlopen(URL + "/__routes") as response:
+            seen = json.load(response)
+        routes = seen["routes"]
+        # Every JSON answer matched the schema its route publishes in OpenAPI.
+        self.assertEqual(seen["mismatches"], [])
+        self.assertGreater(len(routes), 10)
+        # The fixture records a route only when the server's registry matched it.
+        self.assertTrue(all(r.split(" ")[1].startswith("/v1/") for r in routes))
+
+
+if __name__ == "__main__":
+    unittest.main()

withruntime-0.3.1/tests/test_images_volumes_interpreter.py

@@ -0,0 +1,149 @@
+"""Images, volumes and the interpreter against a stub API: the paths and
+bodies the SDK sends, the build helper's polling and log lines, and the
+interpreter's NDJSON stream turned into callbacks and one execution. The
+routes themselves are tested in packages/cloud (images-api, interpreter)."""
+import asyncio
+import json
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import urlsplit
+
+from withruntime import AsyncRuntime, AsyncSandbox, Runtime, RuntimeError
+from withruntime._sync_client import Sandbox
+
+SANDBOX = "8a1f9c2e-0d1b-4c3a-9e8f-7a6b5c4d3e2f"
+EXECUTION = {"id": "e1", "contextId": "python", "status": "ok", "stdout": "hi\n", "results": [], "error": None}
+
+
+class Stub(BaseHTTPRequestHandler):
+    seen: list = []
+    polls = 0
+    fail = False
+
+    def log_message(self, *args):
+        pass
+
+    def _reply(self, status, value, kind="application/json"):
+        data = value if isinstance(value, bytes) else json.dumps(value).encode()
+        self.send_response(status)
+        self.send_header("content-type", kind)
+        self.send_header("content-length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    def _route(self):
+        url = urlsplit(self.path)
+        length = int(self.headers.get("content-length") or 0)
+        body = json.loads(self.rfile.read(length)) if length else None
+        Stub.seen.append((self.command, url.path, url.query, body, self.headers.get("prefer")))
+        path, method = url.path, self.command
+        if method == "POST" and path == "/v1/images":
+            return self._reply(201, {"id": "img-1", "state": "queued"})
+        if path == "/v1/images/img-1/logs":
+            first = url.query == "after=0"
+            return self._reply(200, {"lines": [{"seq": 1, "text": "pulling"}] if first else [], "nextAfter": 1,
+                                     "done": False})
+        if path == "/v1/images/img-1":
+            Stub.polls += 1
+            state = "building" if Stub.polls < 2 else ("failed" if Stub.fail else "ready")
+            return self._reply(200, {"id": "img-1", "state": state, "error": "exit 1" if Stub.fail else None})
+        if path == "/v1/images":
+            return self._reply(200, {"data": [{"id": "img-1"}], "nextCursor": None})
+        if path == "/v1/volumes" and method == "POST":
+            return self._reply(201, {"id": "vol-1", "state": "ready", "sizeMiB": body["sizeMiB"]})
+        if path == "/v1/volumes/vol-1:delete":
+            return self._reply(200, {"id": "vol-1", "state": "deleting"})
+        base = f"/v1/sandboxes/{SANDBOX}/interpreter"
+        if path == base + ":run":
+            if not body.get("stream"):
+                return self._reply(200, EXECUTION)
+            lines = [{"k": "start", "n": 1}, {"k": "stdout", "text": "hi\n"},
+                     {"k": "result", "main": True, "data": {"text/plain": "2"}, "refs": {}},
+                     {"k": "end"}, {"k": "execution", "execution": EXECUTION}]
+            return self._reply(200, "".join(json.dumps(line) + "\n" for line in lines).encode(),
+                               "application/x-ndjson")
+        if path == base + "/contexts" and method == "POST":
+            return self._reply(201, {"id": body["id"], "language": body["language"]})
+        if path == base + "/contexts/py2:interrupt":
+            return self._reply(200, {"interrupted": True})
+        if path == base + "/contexts/python/results/r1.png":
+            return self._reply(200, b"\x89PNG", "image/png")
+        return self._reply(404, {"error": {"code": "not_found", "message": path}})
+
+    do_GET = do_POST = do_DELETE = _route
+
+
+class ImagesVolumesInterpreter(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = ThreadingHTTPServer(("127.0.0.1", 0), Stub)
+        threading.Thread(target=cls.server.serve_forever, daemon=True).start()
+        cls.url = f"http://127.0.0.1:{cls.server.server_address[1]}"
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+
+    def setUp(self):
+        Stub.seen, Stub.polls, Stub.fail = [], 0, False
+
+    def client(self):
+        return Runtime(api_key="rk_test", base_url=self.url, max_retries=0)
+
+    def test_build_polls_to_ready_and_passes_log_lines(self):
+        lines = []
+        image = self.client().images.build(recipe={"pip": ["pandas"], "files": {"a.txt": b"\x00"}},
+                                           build={"max_image_mib": 2048}, build_args={"V": "1"},
+                                           on_log=lambda line: lines.append(line["text"]), poll_seconds=0)
+        self.assertEqual(image["state"], "ready")
+        self.assertEqual(lines, ["pulling"])
+        method, path, _, body, _ = Stub.seen[0]
+        self.assertEqual((method, path), ("POST", "/v1/images"))
+        self.assertEqual(body, {"recipe": {"pip": ["pandas"], "files": [
+            {"path": "a.txt", "content": "AA==", "encoding": "base64"}]},
+            "build": {"maxImageMiB": 2048}, "buildArgs": {"V": "1"}})
+
+    def test_a_failed_build_raises_with_its_error(self):
+        Stub.fail = True
+        with self.assertRaises(RuntimeError) as caught:
+            self.client().images.build(image="alpine:3.20", poll_seconds=0)
+        self.assertEqual(caught.exception.code, "image_build_failed")
+        self.assertIn("exit 1", str(caught.exception))
+
+    def test_images_list_and_volumes(self):
+        runtime = self.client()
+        self.assertEqual([i["id"] for i in runtime.images.list(state="ready")], ["img-1"])
+        volume = runtime.volumes.create(1024, name="data")
+        self.assertEqual(volume["sizeMiB"], 1024)
+        self.assertEqual(Stub.seen[-1][3:], ({"sizeMiB": 1024, "name": "data"}, "wait=10"))
+        self.assertEqual(runtime.volumes.delete("vol-1")["state"], "deleting")
+
+    def test_interpreter_run_plain_and_streamed(self):
+        sbx = Sandbox(self.client().sandboxes._t, {"id": SANDBOX})
+        self.assertEqual(sbx.interpreter.run("print('hi')", timeout_ms=5000)["stdout"], "hi\n")
+        self.assertEqual(Stub.seen[-1][3], {"code": "print('hi')", "timeoutMs": 5000})
+        out, results = [], []
+        execution = sbx.interpreter.run("1+1", on_stdout=out.append, on_result=results.append)
+        self.assertEqual((execution["status"], out), ("ok", ["hi\n"]))
+        self.assertEqual(results, [{"main": True, "data": {"text/plain": "2"}, "refs": {}}])
+        self.assertTrue(Stub.seen[-1][3]["stream"])
+        self.assertEqual(sbx.interpreter.contexts.create(id="py2", language="python")["id"], "py2")
+        self.assertTrue(sbx.interpreter.contexts.interrupt("py2"))
+        ref = {"path": "/workspace/.runtime/interpreter/python/out/r1.png"}
+        self.assertEqual(sbx.interpreter.result(ref), b"\x89PNG")
+        with self.assertRaises(ValueError):
+            sbx.interpreter.result({"path": "/etc/passwd"})
+
+    def test_async_twin(self):
+        async def main():
+            async with AsyncRuntime(api_key="rk_test", base_url=self.url, max_retries=0) as runtime:
+                image = await runtime.images.build(image="alpine:3.20", poll_seconds=0)
+                sbx = AsyncSandbox(runtime.sandboxes._t, {"id": SANDBOX})
+                execution = await sbx.interpreter.run("1+1", on_stdout=lambda text: None)
+                return image["state"], execution["status"]
+        self.assertEqual(asyncio.run(main()), ("ready", "ok"))
+
+
+if __name__ == "__main__":
+    unittest.main()