withruntime 0.4.0__tar.gz → 0.5.1__tar.gz

{withruntime-0.4.0/withruntime.egg-info → withruntime-0.5.1}/PKG-INFO

@@ -1,9 +1,13 @@
 Metadata-Version: 2.4
 Name: withruntime
-Version: 0.4.0
+Version: 0.5.1
 Summary: Runtime Cloud: one client (sync and async) for every Runtime product. Sandboxes first.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.22.3; extra == "openai-agents"
+Provides-Extra: deepagents
+Requires-Dist: deepagents>=0.7; extra == "deepagents"
 
 # Runtime Cloud Python SDK
 
@@ -16,9 +20,11 @@ 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.
+approval, no key to copy). On a server or a CI runner, set `RUNTIME_API_KEY`
+from your secret manager: `npx withruntime keys create` prints a new key once
+after an owner, admin or developer of the account approves it in the browser, or create one 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
@@ -29,8 +35,9 @@ with Sandbox.create() as sbx:
 ```
 
 `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:
+leaving the `with` block stops it. With no arguments you get the free trial
+while it lasts: 50 free hours, no card, up to eight sandboxes running at once.
+`AsyncRuntime` is the same client for asyncio, method for method:
 
 ```python
 import asyncio
@@ -46,10 +53,13 @@ async def main():
 asyncio.run(main())
 ```
 
-A sandbox has `exec`, `exec_stream`, `spawn`, `terminal`, `files` (read, write,
+A sandbox has `exec`, `exec_stream`, `spawn`, `terminal`, `forward_port` (any
+TCP port in the sandbox on a local port), `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`,
+`wake`, `extend`, `update`, `keep_alive`, `fork` and `snapshot`, and the
+`interpreter`, `network`, `previews` and `desktop` products. A paused sandbox
+also wakes by itself on the next call, and `Sandbox.get_or_create(name)` returns
+the sandbox with that name or creates it. The client has `sandboxes`, `images`,
 `volumes`, `snapshots`, `limits`, `feedback` and `support`;
 `runtime.limits.get()` (0.3.1 and later) says whether the key is read-only and
 what its agent may still spend today. Every write carries an
@@ -89,6 +99,35 @@ happens, naming what to use instead. Importing `withruntime` alone does not
 load it. The sync `Sandbox` is generated from the async one by
 `scripts/generate_e2b_sync.py`.
 
+## Code written for Daytona or Vercel Sandbox
+
+`withruntime.daytona` and `withruntime.vercel` do the same for Daytona's
+Python SDK and Vercel Sandbox's. Change the import:
+
+```python no-run
+from withruntime.daytona import Daytona, AsyncDaytona  # was: from daytona import ...
+from withruntime.vercel import sandbox  # was: from vercel import sandbox
+from withruntime.vercel.sandbox import sync as sandbox  # was: from vercel.sandbox import sync as sandbox
+```
+
+Sandboxes get the rival's defaults: Daytona's 1 vCPU, 1 GiB and 3 GiB disk,
+pausing after 15 minutes without calls; Vercel's 2 vCPUs with 2048 MiB each, 5
+minutes, persistent. `runtime_create={...}` passes Runtime's own create
+fields. A Daytona or Vercel key is never sent anywhere. What Runtime does not do
+the same way raises `NotSupportedError` before anything happens, naming what to
+use instead. The sync modules are generated from the async ones by
+`scripts/generate_dropin_sync.py`. `DAYTONA.md` and `VERCEL.md` in the
+JavaScript package list every mapping and gap.
+
+## Agent frameworks
+
+`withruntime.openai_agents` is a sandbox client for the OpenAI Agents SDK's
+`SandboxAgent` (`pip install "withruntime[openai-agents]"`), and
+`withruntime.deepagents` is a Deep Agents sandbox backend. `withruntime.tools`
+gives LangChain, CrewAI, LlamaIndex, Pydantic AI, Google ADK and any framework
+that takes typed functions four sandbox tools. See
+https://withruntime.com/docs/frameworks.
+
 Docs: https://withruntime.com/docs/python.
 
 The package was called `withruntime-cloud`, imported as `runtime_cloud`, until

withruntime-0.4.0/PKG-INFO → withruntime-0.5.1/README.md

@@ -1,10 +1,3 @@
-Metadata-Version: 2.4
-Name: withruntime
-Version: 0.4.0
-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
@@ -16,9 +9,11 @@ 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.
+approval, no key to copy). On a server or a CI runner, set `RUNTIME_API_KEY`
+from your secret manager: `npx withruntime keys create` prints a new key once
+after an owner, admin or developer of the account approves it in the browser, or create one 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
@@ -29,8 +24,9 @@ with Sandbox.create() as sbx:
 ```
 
 `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:
+leaving the `with` block stops it. With no arguments you get the free trial
+while it lasts: 50 free hours, no card, up to eight sandboxes running at once.
+`AsyncRuntime` is the same client for asyncio, method for method:
 
 ```python
 import asyncio
@@ -46,10 +42,13 @@ async def main():
 asyncio.run(main())
 ```
 
-A sandbox has `exec`, `exec_stream`, `spawn`, `terminal`, `files` (read, write,
+A sandbox has `exec`, `exec_stream`, `spawn`, `terminal`, `forward_port` (any
+TCP port in the sandbox on a local port), `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`,
+`wake`, `extend`, `update`, `keep_alive`, `fork` and `snapshot`, and the
+`interpreter`, `network`, `previews` and `desktop` products. A paused sandbox
+also wakes by itself on the next call, and `Sandbox.get_or_create(name)` returns
+the sandbox with that name or creates it. The client has `sandboxes`, `images`,
 `volumes`, `snapshots`, `limits`, `feedback` and `support`;
 `runtime.limits.get()` (0.3.1 and later) says whether the key is read-only and
 what its agent may still spend today. Every write carries an
@@ -89,6 +88,35 @@ happens, naming what to use instead. Importing `withruntime` alone does not
 load it. The sync `Sandbox` is generated from the async one by
 `scripts/generate_e2b_sync.py`.
 
+## Code written for Daytona or Vercel Sandbox
+
+`withruntime.daytona` and `withruntime.vercel` do the same for Daytona's
+Python SDK and Vercel Sandbox's. Change the import:
+
+```python no-run
+from withruntime.daytona import Daytona, AsyncDaytona  # was: from daytona import ...
+from withruntime.vercel import sandbox  # was: from vercel import sandbox
+from withruntime.vercel.sandbox import sync as sandbox  # was: from vercel.sandbox import sync as sandbox
+```
+
+Sandboxes get the rival's defaults: Daytona's 1 vCPU, 1 GiB and 3 GiB disk,
+pausing after 15 minutes without calls; Vercel's 2 vCPUs with 2048 MiB each, 5
+minutes, persistent. `runtime_create={...}` passes Runtime's own create
+fields. A Daytona or Vercel key is never sent anywhere. What Runtime does not do
+the same way raises `NotSupportedError` before anything happens, naming what to
+use instead. The sync modules are generated from the async ones by
+`scripts/generate_dropin_sync.py`. `DAYTONA.md` and `VERCEL.md` in the
+JavaScript package list every mapping and gap.
+
+## Agent frameworks
+
+`withruntime.openai_agents` is a sandbox client for the OpenAI Agents SDK's
+`SandboxAgent` (`pip install "withruntime[openai-agents]"`), and
+`withruntime.deepagents` is a Deep Agents sandbox backend. `withruntime.tools`
+gives LangChain, CrewAI, LlamaIndex, Pydantic AI, Google ADK and any framework
+that takes typed functions four sandbox tools. See
+https://withruntime.com/docs/frameworks.
+
 Docs: https://withruntime.com/docs/python.
 
 The package was called `withruntime-cloud`, imported as `runtime_cloud`, until

{withruntime-0.4.0 → withruntime-0.5.1}/pyproject.toml

@@ -4,12 +4,18 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "withruntime"
-version = "0.4.0"
+version = "0.5.1"
 description = "Runtime Cloud: one client (sync and async) for every Runtime product. Sandboxes first."
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = []
 
+[project.optional-dependencies]
+# withruntime.openai_agents: a sandbox client for the OpenAI Agents SDK's SandboxAgent.
+openai-agents = ["openai-agents>=0.22.3"]
+# withruntime.deepagents: a LangChain Deep Agents sandbox backend.
+deepagents = ["deepagents>=0.7"]
+
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["withruntime*"]

withruntime-0.5.1/tests/test_audit.py

@@ -0,0 +1,70 @@
+"""runtime.audit.list() against a stub API, sync and async. The route and who
+may read it are tested in packages/db (teams) and packages/cloud."""
+import asyncio
+import json
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+from withruntime import AsyncRuntime, Runtime
+
+PAGE = {
+    "events": [
+        {
+            "seq": "7",
+            "action": "key.created",
+            "actor": {"kind": "person", "id": "p", "name": "Marc", "person": None},
+            "ip": "203.0.113.7",
+        }
+    ],
+    "next": None,
+}
+
+
+class Stub(BaseHTTPRequestHandler):
+    seen: list = []
+
+    def log_message(self, *args):
+        pass
+
+    def do_GET(self):
+        Stub.seen.append((self.command, self.path))
+        data = json.dumps(PAGE).encode()
+        self.send_response(200)
+        self.send_header("content-type", "application/json")
+        self.send_header("content-length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+
+class AuditTest(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 = []
+
+    def test_sync_list_with_filters(self):
+        with Runtime(api_key="rk_test", base_url=self.url, max_retries=0) as runtime:
+            page = runtime.audit.list(action="member.", limit=10)
+        self.assertEqual(page["events"][0]["action"], "key.created")
+        self.assertEqual(Stub.seen, [("GET", "/v1/audit?action=member.&limit=10")])
+
+    def test_async_list(self):
+        async def go():
+            async with AsyncRuntime(api_key="rk_test", base_url=self.url, max_retries=0) as runtime:
+                return await runtime.audit.list()
+
+        self.assertIsNone(asyncio.run(go())["next"])
+        self.assertEqual(Stub.seen, [("GET", "/v1/audit")])
+
+
+if __name__ == "__main__":
+    unittest.main()

withruntime-0.5.1/tests/test_capacity_wait.py

@@ -0,0 +1,133 @@
+"""A create that finds every trial slot, the account's quota or the region full
+waits for room and sends the same call again, instead of failing a CI job that
+burst past its limit (judge panel, 23 September 2026). Sync and async share
+the transport's code, so both are driven here over a fake wire."""
+import asyncio
+import json
+import time
+import unittest
+
+from withruntime import AsyncRuntime, ConflictError, Runtime
+
+RUNNING = json.dumps({"id": "sbx", "kind": "sandbox", "state": "running", "status": "active"}).encode()
+
+
+def refusal(code, status=409, details=None):
+    error = {"code": code, "status": status, "message": "full", "retryAfterMs": 5}
+    if details is not None:
+        error["details"] = details
+    return status, json.dumps({"error": error}).encode()
+
+
+class Wire:
+    """Answers each call with the next refusal, then with a running sandbox."""
+
+    def __init__(self, refusals, is_async):
+        self.refusals, self.is_async = list(refusals), is_async
+        self.keys, self.bodies, self.targets = [], [], []
+
+    def _answer(self, method, target, headers, data):
+        self.keys.append(headers.get("Idempotency-Key"))
+        self.bodies.append(data)
+        self.targets.append(target)
+        status, body = self.refusals.pop(0) if self.refusals else (200, RUNNING)
+        is_async = self.is_async
+
+        class Answer:
+            def __init__(self):
+                self.status, self.headers = status, {}
+
+            if is_async:
+                async def read(self):
+                    return body
+            else:
+                def read(self):
+                    return body
+        return Answer()
+
+    def send(self, method, target, headers, data, timeout):
+        if self.is_async:
+            async def later():
+                return self._answer(method, target, headers, data)
+            return later()
+        return self._answer(method, target, headers, data)
+
+
+def create(refusals, client_options=None, **create_options):
+    """Runs one create, sync and async, and returns each run's wire and outcome."""
+    runs = []
+    for is_async in (False, True):
+        wire = Wire(refusals, is_async)
+        options = {"api_key": "rk", "base_url": "https://api.example.test", **(client_options or {})}
+        runtime = AsyncRuntime(**options) if is_async else Runtime(**options)
+        runtime._t._http = wire
+        started = time.monotonic()
+        try:
+            if is_async:
+                outcome = asyncio.run(runtime.sandboxes.create(**create_options))
+            else:
+                outcome = runtime.sandboxes.create(**create_options)
+        except Exception as error:  # noqa: BLE001 - the outcome under test
+            outcome = error
+        runs.append((wire, outcome, time.monotonic() - started))
+    return runs
+
+
+class CapacityWait(unittest.TestCase):
+    def test_a_full_trial_is_waited_out_with_the_same_key_and_input(self):
+        busy = refusal("trial_busy", details={"sandboxIds": ["a"], "concurrent": 8})
+        for wire, outcome, _ in create([busy, busy], funding="trial", labels={"ci": "1"}):
+            self.assertEqual(outcome.id, "sbx")
+            self.assertEqual(len(wire.keys), 3)
+            self.assertEqual(len(set(wire.keys)), 1)
+            self.assertIsNotNone(wire.keys[0])
+            self.assertEqual(len(set(wire.bodies)), 1)
+            self.assertEqual(json.loads(wire.bodies[0]), {"funding": "trial", "labels": {"ci": "1"}})
+
+    def test_the_paid_limit_a_domain_limit_and_a_full_region_are_waited_out_too(self):
+        for code in ("quota_exceeded", "trial_domain_limit", "no_capacity"):
+            for wire, outcome, _ in create([refusal(code)]):
+                self.assertEqual(outcome.id, "sbx", code)
+                self.assertEqual(len(wire.keys), 2)
+        # trial_capacity is a 503: waited for as room, not spent from max_retries.
+        for wire, outcome, _ in create([refusal("trial_capacity", 503)] * 6, {"max_retries": 1}):
+            self.assertEqual(outcome.id, "sbx")
+            self.assertEqual(len(wire.keys), 7)
+
+    def test_when_the_wait_runs_out_the_original_refusal_is_raised(self):
+        for wire, outcome, took in create([refusal("trial_busy")] * 1000, {"wait_for_capacity": 0.2}):
+            self.assertIsInstance(outcome, ConflictError)
+            self.assertEqual(outcome.code, "trial_busy")
+            self.assertGreater(len(wire.keys), 2)
+            self.assertGreaterEqual(took, 0.19)
+            self.assertLess(took, 1.5)
+
+    def test_zero_fails_at_once_on_the_client_or_on_one_call(self):
+        for wire, outcome, _ in create([refusal("trial_busy")], {"wait_for_capacity": 0}):
+            self.assertEqual(getattr(outcome, "code", None), "trial_busy")
+            self.assertEqual(len(wire.keys), 1)
+        for wire, outcome, _ in create([refusal("quota_exceeded")], wait_for_capacity=0):
+            self.assertEqual(getattr(outcome, "code", None), "quota_exceeded")
+            self.assertEqual(len(wire.keys), 1)
+
+    def test_a_request_that_can_never_fit_is_not_waited_for(self):
+        never = refusal("trial_busy", details={"field": "count", "concurrent": 8})
+        for wire, outcome, _ in create([never]):
+            self.assertEqual(getattr(outcome, "code", None), "trial_busy")
+            self.assertEqual(len(wire.keys), 1)
+
+    def test_only_a_create_waits(self):
+        # A fork's failure names copies that started, and its key replays that
+        # failure, so a fork is never retried by waiting.
+        wire = Wire([refusal("trial_busy")], False)
+        runtime = Runtime(api_key="rk", base_url="https://api.example.test")
+        runtime._t._http = wire
+        from withruntime._sync_client import Sandbox
+        sandbox = Sandbox(runtime._t, {"id": "sbx", "state": "running"})
+        with self.assertRaises(ConflictError):
+            sandbox.fork()
+        self.assertEqual(len(wire.keys), 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

{withruntime-0.4.0 → withruntime-0.5.1}/tests/test_client.py

@@ -349,5 +349,56 @@ class Routes(unittest.TestCase):
         self.assertTrue(all(r.split(" ")[1].startswith("/v1/") for r in routes))
 
 
+class Retryable(unittest.TestCase):
+    def test_refusals_that_clear_by_themselves_are_retryable(self):
+        from withruntime import ConflictError
+        self.assertTrue(ConflictError("x", code="trial_busy", status=409, details={"sandboxIds": []}).retryable)
+        self.assertTrue(ConflictError("x", code="no_capacity", status=409).retryable)
+        self.assertFalse(ConflictError("x", code="trial_busy", status=409, details={"field": "count"}).retryable)
+        self.assertFalse(ConflictError("x", code="sandbox_stopped", status=409).retryable)
+        self.assertFalse(ServiceUnavailableError("x", code="fork_unavailable", status=503).retryable)
+
+
+class StreamedTruncation(unittest.TestCase):
+    """A streamed result says whether output was lost: False unless the server
+    sent a "truncated" event, which it does when a reader falls behind the
+    process's output buffer."""
+
+    START = {"type": "start", "processId": "p1"}
+    OUT = {"type": "stdout", "data": "hello\n", "offset": 0}
+    DROP = {"type": "truncated", "droppedBytes": 10, "resumeAt": 10}
+    EXIT = {"type": "exit", "exitCode": 0, "state": "exited", "timedOut": False}
+
+    def flags(self, result):
+        return (result.stdout_truncated, result.stderr_truncated)
+
+    def test_sync(self):
+        for events, expected in (([self.START, self.OUT, self.EXIT], (False, False)),
+                                 ([self.START, self.DROP, self.OUT, self.EXIT], (True, True))):
+            sbx = withruntime._Sandbox(None, {"id": ID})
+            sbx.exec_stream = lambda *_, _events=events, **__: iter(_events)
+            self.assertEqual(self.flags(sbx.exec("long job", on_stdout=lambda _: None)), expected)
+            proc = withruntime.Process(None, ID, {"id": "p1"})
+            proc.output = lambda *_, _events=events[1:], **__: iter(_events)
+            self.assertEqual(self.flags(proc.wait()), expected)
+
+    def test_async(self):
+        async def replay(events):
+            for event in events:
+                yield event
+
+        async def main():
+            for events, expected in (([self.START, self.OUT, self.EXIT], (False, False)),
+                                     ([self.START, self.DROP, self.OUT, self.EXIT], (True, True))):
+                sbx = withruntime.AsyncSandbox(None, {"id": ID})
+                sbx.exec_stream = lambda *_, _events=events, **__: replay(_events)
+                self.assertEqual(self.flags(await sbx.exec("long job", on_stdout=lambda _: None)), expected)
+                proc = withruntime.AsyncProcess(None, ID, {"id": "p1"})
+                proc.output = lambda *_, _events=events[1:], **__: replay(_events)
+                self.assertEqual(self.flags(await proc.wait()), expected)
+
+        asyncio.run(main())
+
+
 if __name__ == "__main__":
     unittest.main()