added notes about sync vs async devbox state behaviour

Author: sid-rl

README-SDK.md

@@ -356,6 +356,8 @@ devbox.await_suspended()
 devbox.shutdown()
 ```
 
+> **State-waiting behavior:** In the synchronous SDK, `DevboxOps.from_id()` and `Devbox.resume()` block until the devbox reaches the `running` state, and `Devbox.suspend()` blocks until the devbox is `suspended`. The async counterparts (`AsyncDevboxOps.from_id()`, `AsyncDevbox.resume()`, `AsyncDevbox.suspend()`) return immediately; call `await_running()` / `await_suspended()` explicitly if you need to wait for the state transition.
+
 #### Context Manager Support
 
 Devboxes support context managers for automatic cleanup:

src/runloop_api_client/sdk/async_.py

@@ -130,6 +130,10 @@ async def create_from_snapshot(
     def from_id(self, devbox_id: str) -> AsyncDevbox:
         """Attach to an existing devbox by ID.
 
+        Returns immediately without waiting for the devbox to reach ``running``
+        state. Call ``await_running()`` on the returned :class:`AsyncDevbox` if
+        you need to wait for readiness (contrast with the synchronous SDK, which blocks).
+
         Args:
             devbox_id: Existing devbox ID.
 

src/runloop_api_client/sdk/async_devbox.py

@@ -169,6 +169,10 @@ async def suspend(
     ) -> DevboxView:
         """Suspend the devbox without destroying state.
 
+        Returns immediately after issuing the suspend request. Call
+        :meth:`await_suspended` if you need to wait for the devbox to reach the
+        ``suspended`` state (contrast with the synchronous SDK, which blocks).
+
         Args:
             **options: Optional long-running request configuration.
 
@@ -186,6 +190,10 @@ async def resume(
     ) -> DevboxView:
         """Resume a suspended devbox.
 
+        Returns immediately after issuing the resume request. Call
+        :meth:`await_running` if you need to wait for the devbox to reach the
+        ``running`` state (contrast with the synchronous SDK, which blocks).
+
         Args:
             **options: Optional long-running request configuration.
 

src/runloop_api_client/sdk/sync.py

@@ -130,6 +130,9 @@ def create_from_snapshot(
     def from_id(self, devbox_id: str) -> Devbox:
         """Attach to an existing devbox by ID.
 
+        Blocks until the devbox reaches ``running`` state so callers can begin
+        issuing commands immediately.
+
         Args:
             devbox_id: Existing devbox ID.