feat: propagate cancellation_token through all resource polling methods

- Update Blueprints: await_build_complete, create_and_await_build_complete
- Update ScenarioRuns: await_scored, score_and_await
- Update Devboxes: await_running, await_suspended, create_and_await_running
- Update DiskSnapshots: await_completed
- Update Executions: await_completed
- Update SDK wrappers: ScenarioRun.await_env_ready
- Add comprehensive docstrings with PollingCancelled exception

All methods support both sync and async variants.
Part of porting TypeScript PR #765 features to Python SDK.

Author: tode-rl

src/runloop_api_client/resources/devboxes/devboxes.py

@@ -98,6 +98,7 @@
     AsyncDiskSnapshotsResourceWithStreamingResponse,
 )
 from ...lib.polling_async import async_poll_until
+from ...lib.cancellation import CancellationToken
 from ...types.devbox_view import DevboxView
 from ...types.tunnel_view import TunnelView
 from ...types.shared_params.mount import Mount
@@ -401,12 +402,14 @@ def await_running(
         *,
         # Use polling_config to configure the "long" polling behavior.
         polling_config: PollingConfig | None = None,
+        cancellation_token: CancellationToken | None = None,
     ) -> DevboxView:
         """Wait for a devbox to be in running state.
 
         Args:
             id: The ID of the devbox to wait for
             config: Optional polling configuration
+            cancellation_token: Token to cancel the wait operation
             extra_headers: Send extra headers
             extra_query: Add additional query parameters to the request
             extra_body: Add additional JSON properties to the request
@@ -417,6 +420,7 @@ def await_running(
 
         Raises:
             PollingTimeout: If polling times out before devbox is running
+            PollingCancelled: If cancellation_token.cancel() is called
             RunloopError: If devbox enters a non-running terminal state
         """
 
@@ -443,7 +447,13 @@ def handle_timeout_error(error: Exception) -> DevboxView:
         def is_done_booting(devbox: DevboxView) -> bool:
             return devbox.status not in DEVBOX_BOOTING_STATES
 
-        devbox = poll_until(wait_for_devbox_status, is_done_booting, polling_config, handle_timeout_error)
+        devbox = poll_until(
+            wait_for_devbox_status,
+            is_done_booting,
+            polling_config,
+            handle_timeout_error,
+            cancellation_token=cancellation_token,
+        )
 
         if devbox.status != "running":
             raise RunloopError(f"Devbox entered non-running terminal state: {devbox.status}")
@@ -455,18 +465,21 @@ def await_suspended(
         id: str,
         *,
         polling_config: PollingConfig | None = None,
+        cancellation_token: CancellationToken | None = None,
     ) -> DevboxView:
         """Wait for a devbox to reach the suspended state.
 
         Args:
             id: The ID of the devbox to wait for.
             polling_config: Optional polling configuration.
+            cancellation_token: Token to cancel the wait operation.
 
         Returns:
             The devbox in the suspended state.
 
         Raises:
             PollingTimeout: If polling times out before the devbox is suspended.
+            PollingCancelled: If cancellation_token.cancel() is called.
             RunloopError: If the devbox enters a non-suspended terminal state.
         """
 
@@ -487,7 +500,13 @@ def handle_timeout_error(error: Exception) -> DevboxView:
         def is_terminal_state(devbox: DevboxView) -> bool:
             return devbox.status in DEVBOX_TERMINAL_STATES
 
-        devbox = poll_until(wait_for_devbox_status, is_terminal_state, polling_config, handle_timeout_error)
+        devbox = poll_until(
+            wait_for_devbox_status,
+            is_terminal_state,
+            polling_config,
+            handle_timeout_error,
+            cancellation_token=cancellation_token,
+        )
 
         if devbox.status != "suspended":
             raise RunloopError(f"Devbox entered non-suspended terminal state: {devbox.status}")
@@ -510,6 +529,7 @@ def create_and_await_running(
         mounts: Optional[Iterable[Mount]] | Omit = omit,
         name: Optional[str] | Omit = omit,
         polling_config: PollingConfig | None = None,
+        cancellation_token: CancellationToken | None = None,
         repo_connection_id: Optional[str] | Omit = omit,
         secrets: Optional[Dict[str, str]] | Omit = omit,
         snapshot_id: Optional[str] | Omit = omit,
@@ -535,6 +555,7 @@ def create_and_await_running(
 
         Raises:
             PollingTimeout: If polling times out before devbox is running
+            PollingCancelled: If cancellation_token.cancel() is called
             RunloopError: If devbox enters a non-running terminal state
         """
         # Pass all create_args to the underlying create method
@@ -565,6 +586,7 @@ def create_and_await_running(
         return self.await_running(
             devbox.id,
             polling_config=polling_config,
+            cancellation_token=cancellation_token,
         )
 
     def list(
@@ -2001,6 +2023,7 @@ async def create_and_await_running(
         mounts: Optional[Iterable[Mount]] | Omit = omit,
         name: Optional[str] | Omit = omit,
         polling_config: PollingConfig | None = None,
+        cancellation_token: CancellationToken | None = None,
         repo_connection_id: Optional[str] | Omit = omit,
         secrets: Optional[Dict[str, str]] | Omit = omit,
         snapshot_id: Optional[str] | Omit = omit,
@@ -2020,12 +2043,14 @@ async def create_and_await_running(
         Args:
             See the `create` method for detailed documentation.
             polling_config: Optional polling configuration
+            cancellation_token: Token to cancel the wait operation
 
         Returns:
             The devbox in running state
 
         Raises:
             PollingTimeout: If polling times out before devbox is running
+            PollingCancelled: If cancellation_token.cancel() is called
             RunloopError: If devbox enters a non-running terminal state
         """
 
@@ -2057,6 +2082,7 @@ async def create_and_await_running(
         return await self.await_running(
             devbox.id,
             polling_config=polling_config,
+            cancellation_token=cancellation_token,
         )
 
     async def await_running(
@@ -2065,12 +2091,14 @@ async def await_running(
         *,
         # Use polling_config to configure the "long" polling behavior.
         polling_config: PollingConfig | None = None,
+        cancellation_token: CancellationToken | None = None,
     ) -> DevboxView:
         """Wait for a devbox to be in running state.
 
         Args:
             id: The ID of the devbox to wait for
             config: Optional polling configuration
+            cancellation_token: Token to cancel the wait operation
             extra_headers: Send extra headers
             extra_query: Add additional query parameters to the request
             extra_body: Add additional JSON properties to the request
@@ -2081,6 +2109,7 @@ async def await_running(
 
         Raises:
             PollingTimeout: If polling times out before devbox is running
+            PollingCancelled: If cancellation_token.cancel() is called
             RunloopError: If devbox enters a non-running terminal state
         """
 
@@ -2105,7 +2134,12 @@ async def wait_for_devbox_status() -> DevboxView:
         def is_done_booting(devbox: DevboxView) -> bool:
             return devbox.status not in DEVBOX_BOOTING_STATES
 
-        devbox = await async_poll_until(wait_for_devbox_status, is_done_booting, polling_config)
+        devbox = await async_poll_until(
+            wait_for_devbox_status,
+            is_done_booting,
+            polling_config,
+            cancellation_token=cancellation_token,
+        )
 
         if devbox.status != "running":
             raise RunloopError(f"Devbox entered non-running terminal state: {devbox.status}")
@@ -2117,18 +2151,21 @@ async def await_suspended(
         id: str,
         *,
         polling_config: PollingConfig | None = None,
+        cancellation_token: CancellationToken | None = None,
     ) -> DevboxView:
         """Wait for a devbox to reach the suspended state.
 
         Args:
             id: The ID of the devbox to wait for.
             polling_config: Optional polling configuration.
+            cancellation_token: Token to cancel the wait operation.
 
         Returns:
             The devbox in the suspended state.
 
         Raises:
             PollingTimeout: If polling times out before the devbox is suspended.
+            PollingCancelled: If cancellation_token.cancel() is called.
             RunloopError: If the devbox enters a non-suspended terminal state.
         """
 
@@ -2147,7 +2184,12 @@ async def wait_for_devbox_status() -> DevboxView:
         def is_terminal_state(devbox: DevboxView) -> bool:
             return devbox.status in DEVBOX_TERMINAL_STATES
 
-        devbox = await async_poll_until(wait_for_devbox_status, is_terminal_state, polling_config)
+        devbox = await async_poll_until(
+            wait_for_devbox_status,
+            is_terminal_state,
+            polling_config,
+            cancellation_token=cancellation_token,
+        )
 
         if devbox.status != "suspended":
             raise RunloopError(f"Devbox entered non-suspended terminal state: {devbox.status}")

src/runloop_api_client/resources/devboxes/disk_snapshots.py

@@ -22,6 +22,7 @@
 from ..._base_client import AsyncPaginator, make_request_options
 from ...types.devboxes import disk_snapshot_list_params, disk_snapshot_update_params
 from ...lib.polling_async import async_poll_until
+from ...lib.cancellation import CancellationToken
 from ...types.devbox_snapshot_view import DevboxSnapshotView
 from ...types.devboxes.devbox_snapshot_async_status_view import DevboxSnapshotAsyncStatusView
 
@@ -256,12 +257,31 @@ def await_completed(
         id: str,
         *,
         polling_config: PollingConfig | None = None,
+        cancellation_token: CancellationToken | None = None,
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> DevboxSnapshotAsyncStatusView:
-        """Wait for a disk snapshot operation to complete."""
+        """Wait for a disk snapshot operation to complete.
+
+        Args:
+            id: The ID of the disk snapshot to wait for
+            polling_config: Optional polling configuration
+            cancellation_token: Token to cancel the wait operation
+            extra_headers: Send extra headers
+            extra_query: Add additional query parameters to the request
+            extra_body: Add additional JSON properties to the request
+            timeout: Override the client-level default timeout for this request, in seconds
+
+        Returns:
+            The completed snapshot status
+
+        Raises:
+            PollingTimeout: If polling times out before snapshot completes
+            PollingCancelled: If cancellation_token.cancel() is called
+            RunloopError: If snapshot enters error state
+        """
 
         if not id:
             raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
@@ -275,6 +295,7 @@ def is_terminal(result: DevboxSnapshotAsyncStatusView) -> bool:
             ),
             is_terminal,
             polling_config,
+            cancellation_token=cancellation_token,
         )
 
         if status.status == "error":
@@ -512,12 +533,31 @@ async def await_completed(
         id: str,
         *,
         polling_config: PollingConfig | None = None,
+        cancellation_token: CancellationToken | None = None,
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> DevboxSnapshotAsyncStatusView:
-        """Wait asynchronously for a disk snapshot operation to complete."""
+        """Wait asynchronously for a disk snapshot operation to complete.
+
+        Args:
+            id: The ID of the disk snapshot to wait for
+            polling_config: Optional polling configuration
+            cancellation_token: Token to cancel the wait operation
+            extra_headers: Send extra headers
+            extra_query: Add additional query parameters to the request
+            extra_body: Add additional JSON properties to the request
+            timeout: Override the client-level default timeout for this request, in seconds
+
+        Returns:
+            The completed snapshot status
+
+        Raises:
+            PollingTimeout: If polling times out before snapshot completes
+            PollingCancelled: If cancellation_token.cancel() is called
+            RunloopError: If snapshot enters error state
+        """
 
         if not id:
             raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
@@ -531,6 +571,7 @@ def is_terminal(result: DevboxSnapshotAsyncStatusView) -> bool:
             ),
             is_terminal,
             polling_config,
+            cancellation_token=cancellation_token,
         )
 
         if status.status == "error":

src/runloop_api_client/resources/devboxes/executions.py

@@ -33,6 +33,7 @@
     execution_stream_stdout_updates_params,
 )
 from ...lib.polling_async import async_poll_until
+from ...lib.cancellation import CancellationToken
 from ...types.devbox_send_std_in_result import DevboxSendStdInResult
 from ...types.devbox_execution_detail_view import DevboxExecutionDetailView
 from ...types.devboxes.execution_update_chunk import ExecutionUpdateChunk
@@ -124,13 +125,15 @@ def await_completed(
         *,
         # Use polling_config to configure the "long" polling behavior.
         polling_config: PollingConfig | None = None,
+        cancellation_token: CancellationToken | None = None,
     ) -> DevboxAsyncExecutionDetailView:
         """Wait for an execution to complete.
 
         Args:
             execution_id: The ID of the execution to wait for
             id: The ID of the devbox
             config: Optional polling configuration
+            cancellation_token: Token to cancel the wait operation
             extra_headers: Send extra headers
             extra_query: Add additional query parameters to the request
             extra_body: Add additional JSON properties to the request
@@ -141,6 +144,7 @@ def await_completed(
 
         Raises:
             PollingTimeout: If polling times out before execution completes
+            PollingCancelled: If cancellation_token.cancel() is called
         """
 
         def wait_for_execution_status() -> DevboxAsyncExecutionDetailView:
@@ -165,7 +169,13 @@ def handle_timeout_error(error: Exception) -> DevboxAsyncExecutionDetailView:
         def is_done(execution: DevboxAsyncExecutionDetailView) -> bool:
             return execution.status == "completed"
 
-        return poll_until(wait_for_execution_status, is_done, polling_config, handle_timeout_error)
+        return poll_until(
+            wait_for_execution_status,
+            is_done,
+            polling_config,
+            handle_timeout_error,
+            cancellation_token=cancellation_token,
+        )
 
     def execute_async(
         self,
@@ -670,13 +680,15 @@ async def await_completed(
         devbox_id: str,
         # Use polling_config to configure the "long" polling behavior.
         polling_config: PollingConfig | None = None,
+        cancellation_token: CancellationToken | None = None,
     ) -> DevboxAsyncExecutionDetailView:
         """Wait for an execution to complete.
 
         Args:
             execution_id: The ID of the execution to wait for
             id: The ID of the devbox
             polling_config: Optional polling configuration
+            cancellation_token: Token to cancel the wait operation
             extra_headers: Send extra headers
             extra_query: Add additional query parameters to the request
             extra_body: Add additional JSON properties to the request
@@ -687,6 +699,7 @@ async def await_completed(
 
         Raises:
             PollingTimeout: If polling times out before execution completes
+            PollingCancelled: If cancellation_token.cancel() is called
         """
 
         async def wait_for_execution_status() -> DevboxAsyncExecutionDetailView:
@@ -707,7 +720,12 @@ async def wait_for_execution_status() -> DevboxAsyncExecutionDetailView:
         def is_done(execution: DevboxAsyncExecutionDetailView) -> bool:
             return execution.status == "completed"
 
-        return await async_poll_until(wait_for_execution_status, is_done, polling_config)
+        return await async_poll_until(
+            wait_for_execution_status,
+            is_done,
+            polling_config,
+            cancellation_token=cancellation_token,
+        )
 
     async def execute_async(
         self,

src/runloop_api_client/sdk/scenario_run.py

@@ -106,7 +106,11 @@ def await_env_ready(
         :return: Scenario run state after environment is ready
         :rtype: ScenarioRunView
         """
-        self._client.devboxes.await_running(self._devbox_id, polling_config=options.get("polling_config"))
+        self._client.devboxes.await_running(
+            self._devbox_id,
+            polling_config=options.get("polling_config"),
+            cancellation_token=options.get("cancellation_token"),
+        )
         return self.get_info(**filter_params(options, BaseRequestOptions))
 
     def score(