feat(sdks/python): resilient SDK transport (OSEP-0016)

Implement the Python side of OSEP-0016 for the sandbox and
code-interpreter SDKs. Adds a shared retry policy, extended
exception hierarchy, and async/sync httpx transport wrappers.

Retry policy
- New `RetryPolicy` value type on `ConnectionConfig` /
  `ConnectionConfigSync`; defaults enable retry for idempotent
  methods only, `POST`/`PATCH` status-code retry is opt-in.
- Default idempotent retryable status set: `{429, 502, 503}`.
- Decorrelated jitter (default), full jitter, and deterministic
  exponential; `Retry-After` honored with a fixed 60s ceiling.
- `RetryPolicy.disabled()` gives end-to-end fast-fail semantics
  and suppresses fresh-connection recovery.
- `HTTPStatus` used at the public API surface so callers get
  type checking and IDE completion for the status sets.

Exception hierarchy
- Extend `SandboxException` with an `is_retryable` accessor
  reflecting the SDK's actual retry decision at emission time.
- New subclasses: `SandboxRateLimitException` (carries
  `retry_after`), `SandboxTimeoutException`,
  `SandboxConnectionException`. Existing classes and their
  public fields are unchanged.

Transport wrappers
- `RetryAsyncTransport` (httpx.AsyncBaseTransport) and
  `RetrySyncTransport` (httpx.BaseTransport) install the retry
  engine at the same layer the SDK already uses for transport
  concerns. Generated OpenAPI code is not touched.
- `ConnectionConfig` exposes a `sse_transport` property so SSE
  bootstraps bypass retry while sharing the underlying pool.
  Command / isolated / code-interpreter SSE clients now use it.
- `lifecycle_metrics` keeps its own short-lived httpx.Client;
  sharing the SDK transport would let the metrics client's
  `close()` tear down every other adapter's connection pool.

Tests
- Retry policy defaults, validation, and `HTTPStatus` usage.
- Pure decision function: status matrix, transport branch,
  budget/deadline/cancellation predicates, opt-in rules,
  jitter algorithms, and `Retry-After` parsing/clamping.
- Async + sync httpx transport integration via scripted mock
  transports covering success, 4xx pass-through, budget
  exhaustion, pre-send vs. post-send classification, opt-in,
  and observability callback invariants.
- `ConnectionConfig` wiring: default wraps, `disabled()` skips
  wrapping, user-supplied transports are used verbatim.
- SSE clients use the raw inner transport, verified end-to-end.

Author: Pangjiping

sdks/code-interpreter/python/pyproject.toml

@@ -43,7 +43,7 @@ classifiers = [
 ]
 dependencies = [
     "pydantic>=2.4.2,<3.0",
-    "opensandbox>=0.1.10,<0.2.0",
+    "opensandbox>=0.1.14,<0.2.0",
 ]
 
 [project.urls]

sdks/code-interpreter/python/src/code_interpreter/adapters/code_adapter.py

@@ -130,6 +130,12 @@ def __init__(
             "Accept": "text/event-stream",
             "Cache-Control": "no-cache",
         }
+        # SSE bootstraps must not be retried; use the raw transport.
+        # `sse_transport` was introduced in opensandbox 0.1.15; fall
+        # back to `transport` for older sandbox SDKs still on 0.1.14.
+        sse_transport = getattr(
+            self.connection_config, "sse_transport", None
+        ) or self.connection_config.transport
         self._sse_client = httpx.AsyncClient(
             headers=sse_headers,
             timeout=httpx.Timeout(
@@ -138,7 +144,7 @@ def __init__(
                 write=timeout_seconds,
                 pool=None,
             ),
-            transport=self.connection_config.transport,
+            transport=sse_transport,
         )
 
     async def _get_client(self):

sdks/code-interpreter/python/src/code_interpreter/sync/adapters/code_adapter.py

@@ -118,12 +118,18 @@ def __init__(
             "Accept": "text/event-stream",
             "Cache-Control": "no-cache",
         }
+        # SSE bootstraps must not be retried; use the raw transport.
+        # `sse_transport` was introduced in opensandbox 0.1.15; fall
+        # back to `transport` for older sandbox SDKs still on 0.1.14.
+        sse_transport = getattr(
+            self.connection_config, "sse_transport", None
+        ) or self.connection_config.transport
         self._sse_client = httpx.Client(
             headers=sse_headers,
             timeout=httpx.Timeout(
                 connect=timeout_seconds, read=None, write=timeout_seconds, pool=None
             ),
-            transport=self.connection_config.transport,
+            transport=sse_transport,
         )
 
     def _get_execd_url(self, path: str) -> str:

sdks/sandbox/python/src/opensandbox/adapters/command_adapter.py

@@ -39,7 +39,7 @@
     ExecutionEventDispatcher,
 )
 from opensandbox.adapters.converter.response_handler import (
-    extract_request_id,
+    build_api_exception_from_httpx,
     handle_api_error,
 )
 from opensandbox.config import ConnectionConfig
@@ -184,6 +184,9 @@ def __init__(
             "Accept": "text/event-stream",
             "Cache-Control": "no-cache",
         }
+        # SSE bootstraps must not be retried: bodies are not replayable
+        # and resume is out of scope here. Share the raw transport so
+        # the underlying connection pool is still shared.
         self._sse_client = httpx.AsyncClient(
             headers=sse_headers,
             timeout=httpx.Timeout(
@@ -192,7 +195,7 @@ def __init__(
                 write=timeout_seconds,
                 pool=None,
             ),
-            transport=self.connection_config.transport,
+            transport=self.connection_config.sse_transport,
         )
 
     async def _get_client(self):
@@ -228,15 +231,10 @@ async def _execute_streaming_request(
         async with client.stream("POST", url, json=json_body) as response:
             if response.status_code != 200:
                 await response.aread()
-                error_body = response.text
                 logger.error(
-                    f"{failure_message}. Status: {response.status_code}, Body: {error_body}"
-                )
-                raise SandboxApiException(
-                    message=f"{failure_message}. Status code: {response.status_code}",
-                    status_code=response.status_code,
-                    request_id=extract_request_id(response.headers),
+                    f"{failure_message}. Status: {response.status_code}, Body: {response.text}"
                 )
+                raise build_api_exception_from_httpx(response, failure_message)
 
             dispatcher = ExecutionEventDispatcher(execution, handlers)
             async for line in response.aiter_lines():

sdks/sandbox/python/src/opensandbox/adapters/converter/exception_converter.py

@@ -28,14 +28,18 @@
 
 import json
 import logging
+from http import HTTPStatus
 from typing import Any
 
 from httpx import (
     ConnectError,
+    ConnectTimeout,
     HTTPStatusError,
     NetworkError,
+    PoolTimeout,
     ReadTimeout,
     TimeoutException,
+    TransportError,
     WriteTimeout,
 )
 
@@ -46,21 +50,18 @@
 from opensandbox.exceptions import (
     InvalidArgumentException,
     SandboxApiException,
+    SandboxConnectionException,
     SandboxError,
     SandboxException,
     SandboxInternalException,
+    SandboxRateLimitException,
+    SandboxTimeoutException,
 )
+from opensandbox.transport._decision import parse_retry_after
 
 logger = logging.getLogger(__name__)
 
 UNEXPECTED_STATUS_TYPES = (LifecycleUnexpectedStatus, ExecdUnexpectedStatus)
-HTTPX_NETWORK_ERROR_TYPES = (
-    ConnectError,
-    TimeoutException,
-    NetworkError,
-    ReadTimeout,
-    WriteTimeout,
-)
 
 
 class ExceptionConverter:
@@ -101,20 +102,45 @@ def to_sandbox_exception(e: Exception) -> SandboxException:
         if _is_httpx_status_error(e):
             return _convert_httpx_error_to_api_exception(e)
 
-        # Handle network/IO errors
-        if isinstance(e, (IOError, OSError, ConnectionError)):
-            return SandboxInternalException(
+        # httpx connection failures (DNS, TCP connect, TLS handshake,
+        # connect timeout) — pre-send, semantically "cannot reach".
+        # ConnectTimeout must be dispatched before generic TimeoutException
+        # because it is a subclass of both TimeoutException and ConnectError.
+        if isinstance(e, (ConnectTimeout, ConnectError, NetworkError)):
+            return SandboxConnectionException(
                 message=f"Network connectivity error: {e}",
                 cause=e,
             )
 
-        # Handle httpx network errors
-        if _is_httpx_network_error(e):
+        # httpx timeout family (read, write, pool, or the synthetic
+        # ReadTimeout raised by the retry wrapper when overall_deadline
+        # is exhausted) — the request was sent but did not finish in time.
+        if isinstance(e, (ReadTimeout, WriteTimeout, PoolTimeout, TimeoutException)):
+            return SandboxTimeoutException(
+                message=f"Request timed out: {e}",
+                cause=e,
+            )
+
+        # OS-level connectivity errors (DNS, socket errors, etc.) not
+        # already routed through httpx's typed hierarchy.
+        if isinstance(e, (ConnectionError,)):
+            return SandboxConnectionException(
+                message=f"Network connectivity error: {e}",
+                cause=e,
+            )
+        if isinstance(e, (IOError, OSError)):
             return SandboxInternalException(
                 message=f"Network connectivity error: {e}",
                 cause=e,
             )
 
+        # Any other httpx TransportError (opaque low-level failures).
+        if isinstance(e, TransportError):
+            return SandboxConnectionException(
+                message=f"Network connectivity error: {e}",
+                cause=e,
+            )
+
         # Handle validation and argument errors (SDK usage errors)
         # - ValueError/TypeError are typically raised for invalid user inputs or model validation
         # - Pydantic ValidationError represents invalid input data for SDK models
@@ -154,24 +180,57 @@ def _is_httpx_status_error(e: Exception) -> bool:
     return isinstance(e, HTTPStatusError)
 
 
-def _is_httpx_network_error(e: Exception) -> bool:
-    """Check if exception is an httpx network-related error."""
-    return isinstance(e, HTTPX_NETWORK_ERROR_TYPES)
+def _retry_after_from_headers(headers: Any) -> float | None:
+    if not headers:
+        return None
+    try:
+        raw = headers.get("Retry-After") or headers.get("retry-after")
+    except Exception:
+        return None
+    parsed = parse_retry_after(raw if isinstance(raw, str) else None)
+    return parsed.total_seconds() if parsed is not None else None
+
+
+def _build_api_exception(
+    *,
+    status_code: int,
+    content: bytes | None,
+    cause: Exception,
+    request_id: str | None = None,
+    retry_after: float | None = None,
+) -> SandboxApiException:
+    """Build a Sandbox(ApiException|RateLimitException) from raw fields."""
+    sandbox_error = _parse_error_body(content) if content else None
+    if status_code == HTTPStatus.TOO_MANY_REQUESTS:
+        return SandboxRateLimitException(
+            message=f"API error: HTTP {status_code}",
+            status_code=status_code,
+            cause=cause,
+            error=sandbox_error,
+            request_id=request_id,
+            retry_after=retry_after,
+            response_body=content if isinstance(content, bytes) else None,
+        )
+    return SandboxApiException(
+        message=f"API error: HTTP {status_code}",
+        status_code=status_code,
+        cause=cause,
+        error=sandbox_error,
+        request_id=request_id,
+        response_body=content if isinstance(content, bytes) else None,
+    )
 
 
 def _convert_unexpected_status_to_api_exception(e: Exception) -> SandboxApiException:
     """Convert openapi-python-client UnexpectedStatus to SandboxApiException."""
     status_code = getattr(e, "status_code", 0)
     content = getattr(e, "content", b"")
-
-    # Try to parse error body
-    sandbox_error = _parse_error_body(content)
-
-    return SandboxApiException(
-        message=f"API error: HTTP {status_code}",
-        status_code=status_code,
+    # openapi-python-client's UnexpectedStatus does not carry headers,
+    # so Retry-After / request_id are not recoverable here.
+    return _build_api_exception(
+        status_code=int(status_code) if status_code else 0,
+        content=content if isinstance(content, bytes) else None,
         cause=e,
-        error=sandbox_error,
     )
 
 
@@ -181,20 +240,19 @@ def _convert_httpx_error_to_api_exception(e: Exception) -> SandboxApiException:
     status_code = response.status_code if response else 0
     content = response.content if response else b""
     request_id = None
+    retry_after = None
     if response is not None:
         from opensandbox.adapters.converter.response_handler import extract_request_id
 
         request_id = extract_request_id(response.headers)
+        retry_after = _retry_after_from_headers(response.headers)
 
-    # Try to parse error body
-    sandbox_error = _parse_error_body(content)
-
-    return SandboxApiException(
-        message=f"API error: HTTP {status_code}",
-        status_code=status_code,
+    return _build_api_exception(
+        status_code=int(status_code) if status_code else 0,
+        content=content if isinstance(content, bytes) else None,
         cause=e,
-        error=sandbox_error,
         request_id=request_id,
+        retry_after=retry_after,
     )