opensandbox 0.1.17.dev0__tar.gz → 1.1.1__tar.gz

{opensandbox-0.1.17.dev0 → opensandbox-1.1.1}/.gitignore

@@ -269,12 +269,12 @@ nbdist/
 generated/
 **/generated/**
 
-# fleets FastPath gRPC stubs are committed intentionally (deterministic protoc
+# Fast Sandbox FastPath gRPC stubs are committed intentionally (deterministic protoc
 # output; the server package needs them at install time, so they are checked
 # in rather than regenerated).
-!server/opensandbox_server/services/fleets/generated/
-!server/opensandbox_server/services/fleets/generated/**
-server/opensandbox_server/services/fleets/generated/__pycache__/
+!server/opensandbox_server/services/fast_sandbox/generated/
+!server/opensandbox_server/services/fast_sandbox/generated/**
+server/opensandbox_server/services/fast_sandbox/generated/__pycache__/
 
 # execd eBPF kernel BTF dumps (bpf2go build-time only, never committed —
 # see components/execd/pkg/ebpf/prog/audit.bpf.c; regenerate with:
@@ -290,3 +290,7 @@ obj/
 
 .qoder/
 /.vs
+
+# fast-sandbox pinned source checkout (materialized by
+# manifests/release/build-fast-sandbox.sh from manifests/third-party/fast-sandbox.commit)
+.fast-sandbox/

{opensandbox-0.1.17.dev0 → opensandbox-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opensandbox
-Version: 0.1.17.dev0
+Version: 1.1.1
 Summary: OpenSandbox Python SDK - Secure, isolated execution environments
 Project-URL: Homepage, https://open-sandbox.ai
 Project-URL: Repository, https://github.com/opensandbox-group/OpenSandbox
@@ -224,12 +224,14 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: attrs>=21.3.0
+Requires-Dist: httpcore<2.0,>=1.0.0
 Requires-Dist: httpx-sse<0.5,>=0.4.3
 Requires-Dist: httpx<1.0,>=0.27.0
+Requires-Dist: opentelemetry-api<2.0,>=1.20
 Requires-Dist: pydantic<3.0,>=2.4.2
 Requires-Dist: python-dateutil<3.0,>=2.8.2
 Provides-Extra: pool-redis
-Requires-Dist: pyjwt>=2.13.0; extra == 'pool-redis'
+Requires-Dist: pyjwt>=2.14.0; extra == 'pool-redis'
 Requires-Dist: redis<6.0,>=5.0; extra == 'pool-redis'
 Description-Content-Type: text/markdown
 
@@ -354,7 +356,8 @@ pool = SandboxPoolSync(
     state_store=InMemoryPoolStateStore(),  # single-process only
     connection_config=ConnectionConfigSync(domain="api.opensandbox.io"),
     creation_spec=PoolCreationSpec(image="ubuntu:22.04"),
-    reconcile_interval=timedelta(seconds=5),
+    warmup_create_qps=10,
+    warmup_concurrency=128,
 )
 
 pool.start()
@@ -598,7 +601,94 @@ for f in files:
 await sandbox.files.delete_files(["/tmp/hello.txt"])
 ```
 
-### 5. Sandbox Management (Admin)
+### 5. Snapshots
+
+Capture a sandbox's state and restore new sandboxes from it. Snapshots are
+administered through `SandboxManager`:
+
+```python
+from opensandbox.manager import SandboxManager
+from opensandbox.models.sandboxes import SnapshotFilter
+
+async with await SandboxManager.create(connection_config=config) as manager:
+    # Create a snapshot from a running sandbox, then wait until it is Ready
+    snapshot = await manager.create_snapshot(sandbox_id, name="pre-migration")
+
+    info = await manager.get_snapshot(snapshot.id)
+    while info.status.state == "Creating":
+        await asyncio.sleep(2)
+        info = await manager.get_snapshot(snapshot.id)
+    if info.status.state != "Ready":
+        raise RuntimeError(
+            f"snapshot not Ready: state={info.status.state} reason={info.status.reason}"
+        )
+
+    # List all snapshots
+    page = await manager.list_snapshots(SnapshotFilter())
+
+# Restore: create a new sandbox FROM a snapshot (image and snapshot_id are
+# mutually exclusive — set exactly one)
+restored = await Sandbox.create(
+    snapshot_id=snapshot.id,
+    connection_config=config,
+)
+
+# Only delete the snapshot after the restore has succeeded
+async with await SandboxManager.create(connection_config=config) as manager:
+    await manager.delete_snapshot(snapshot.id)
+```
+
+A `Sandbox` can also snapshot itself directly:
+`await sandbox.create_snapshot(name="checkpoint-1")`.
+
+### 6. Isolated Sessions
+
+Isolated sessions run multi-step code in a hardened, resource-bounded
+namespace with bind mounts — reachable through `sandbox.isolation`:
+
+```python
+from opensandbox.models.isolated import (
+    CreateIsolatedSessionRequest,
+    IsolatedRunOpts,
+    IsolatedWorkspaceSpec,
+    BindMount,
+)
+
+session = await sandbox.isolation.create(
+    CreateIsolatedSessionRequest(
+        workspace=IsolatedWorkspaceSpec(path="/workspace", mode="rw"),
+        profile="strict",
+        # Optional bind mounts (source on host, dest inside the session)
+        binds=[BindMount(source="/data", dest="/data", readonly=True)],
+        # Auto-destroy after 10 idle minutes; omitting this leaves the
+        # session alive with no idle GC
+        idle_timeout_seconds=600,
+    )
+)
+try:
+    # Foreground run — timeout_seconds applies here only; background
+    # runs are deliberately not time-limited
+    run = await session.run(
+        "python -c 'print(1+1)'",
+        opts=IsolatedRunOpts(timeout_seconds=30),
+    )
+    print(run.logs.stdout[0].text)
+
+    # Background runs: start, poll until finished, then fetch logs
+    bg = await session.run_background("make build")
+    status = await session.run_status(bg.run_id)
+    while status.running:
+        await asyncio.sleep(2)
+        status = await session.run_status(bg.run_id)
+    logs = await session.run_logs(bg.run_id)
+finally:
+    # Runs even if a foreground run, polling, or log fetch raises —
+    # without this the session leaks (idle GC only fires if
+    # idle_timeout_seconds was set)
+    await session.delete()
+```
+
+### 7. Sandbox Management (Admin)
 
 Use `SandboxManager` for administrative tasks and finding existing sandboxes.
 
@@ -637,9 +727,31 @@ The `ConnectionConfig` class manages API server connection settings.
 | `request_timeout` | Timeout for API requests                   | 30 seconds                   | -                      |
 | `debug`           | Enable debug logging for HTTP requests     | `False`                      | -                      |
 | `headers`         | Custom HTTP headers                        | Empty                        | -                      |
+| `follow_redirects` | Follow HTTP redirects for SDK requests      | `False`                      | -                      |
+| `event_hooks`     | Additional httpx hooks for adapter clients   | Empty                        | -                      |
 | `transport`       | Shared httpx transport (pool/proxy/retry)  | SDK-created per instance     | -                      |
 | `use_server_proxy` | Use sandbox server as proxy for execd/endpoint requests (e.g. when client cannot reach the sandbox directly) | `False` | -                      |
 
+When `follow_redirects` is enabled, same-origin redirects preserve request
+headers. An origin is the combination of scheme, host, and port, so changing
+any of those values is cross-origin. Before following a cross-origin redirect,
+the SDK removes every header whose name starts with `OPEN-SANDBOX-` or
+`OPENSANDBOX-` (case-insensitive). Other custom headers are not stripped
+automatically.
+
+File uploads never follow redirects, even when `follow_redirects` is enabled,
+because streamed or file-backed multipart request bodies cannot always be
+safely replayed. This applies to both direct chunked uploads and uploads through
+the server proxy. A redirect response from an upload is surfaced as a
+`SandboxApiException` with the original 3xx status.
+
+`ConnectionConfig.event_hooks` accepts async httpx hooks, while
+`ConnectionConfigSync.event_hooks` accepts synchronous hooks. Configured
+request hooks run before the SDK safety hook, so they cannot re-add protected
+OpenSandbox headers to a cross-origin request. Lifecycle telemetry honors
+`follow_redirects` and the SDK safety hook, but does not invoke configured user
+hooks.
+
 ```python
 from datetime import timedelta
 

{opensandbox-0.1.17.dev0 → opensandbox-1.1.1}/README.md

@@ -119,7 +119,8 @@ pool = SandboxPoolSync(
     state_store=InMemoryPoolStateStore(),  # single-process only
     connection_config=ConnectionConfigSync(domain="api.opensandbox.io"),
     creation_spec=PoolCreationSpec(image="ubuntu:22.04"),
-    reconcile_interval=timedelta(seconds=5),
+    warmup_create_qps=10,
+    warmup_concurrency=128,
 )
 
 pool.start()
@@ -363,7 +364,94 @@ for f in files:
 await sandbox.files.delete_files(["/tmp/hello.txt"])
 ```
 
-### 5. Sandbox Management (Admin)
+### 5. Snapshots
+
+Capture a sandbox's state and restore new sandboxes from it. Snapshots are
+administered through `SandboxManager`:
+
+```python
+from opensandbox.manager import SandboxManager
+from opensandbox.models.sandboxes import SnapshotFilter
+
+async with await SandboxManager.create(connection_config=config) as manager:
+    # Create a snapshot from a running sandbox, then wait until it is Ready
+    snapshot = await manager.create_snapshot(sandbox_id, name="pre-migration")
+
+    info = await manager.get_snapshot(snapshot.id)
+    while info.status.state == "Creating":
+        await asyncio.sleep(2)
+        info = await manager.get_snapshot(snapshot.id)
+    if info.status.state != "Ready":
+        raise RuntimeError(
+            f"snapshot not Ready: state={info.status.state} reason={info.status.reason}"
+        )
+
+    # List all snapshots
+    page = await manager.list_snapshots(SnapshotFilter())
+
+# Restore: create a new sandbox FROM a snapshot (image and snapshot_id are
+# mutually exclusive — set exactly one)
+restored = await Sandbox.create(
+    snapshot_id=snapshot.id,
+    connection_config=config,
+)
+
+# Only delete the snapshot after the restore has succeeded
+async with await SandboxManager.create(connection_config=config) as manager:
+    await manager.delete_snapshot(snapshot.id)
+```
+
+A `Sandbox` can also snapshot itself directly:
+`await sandbox.create_snapshot(name="checkpoint-1")`.
+
+### 6. Isolated Sessions
+
+Isolated sessions run multi-step code in a hardened, resource-bounded
+namespace with bind mounts — reachable through `sandbox.isolation`:
+
+```python
+from opensandbox.models.isolated import (
+    CreateIsolatedSessionRequest,
+    IsolatedRunOpts,
+    IsolatedWorkspaceSpec,
+    BindMount,
+)
+
+session = await sandbox.isolation.create(
+    CreateIsolatedSessionRequest(
+        workspace=IsolatedWorkspaceSpec(path="/workspace", mode="rw"),
+        profile="strict",
+        # Optional bind mounts (source on host, dest inside the session)
+        binds=[BindMount(source="/data", dest="/data", readonly=True)],
+        # Auto-destroy after 10 idle minutes; omitting this leaves the
+        # session alive with no idle GC
+        idle_timeout_seconds=600,
+    )
+)
+try:
+    # Foreground run — timeout_seconds applies here only; background
+    # runs are deliberately not time-limited
+    run = await session.run(
+        "python -c 'print(1+1)'",
+        opts=IsolatedRunOpts(timeout_seconds=30),
+    )
+    print(run.logs.stdout[0].text)
+
+    # Background runs: start, poll until finished, then fetch logs
+    bg = await session.run_background("make build")
+    status = await session.run_status(bg.run_id)
+    while status.running:
+        await asyncio.sleep(2)
+        status = await session.run_status(bg.run_id)
+    logs = await session.run_logs(bg.run_id)
+finally:
+    # Runs even if a foreground run, polling, or log fetch raises —
+    # without this the session leaks (idle GC only fires if
+    # idle_timeout_seconds was set)
+    await session.delete()
+```
+
+### 7. Sandbox Management (Admin)
 
 Use `SandboxManager` for administrative tasks and finding existing sandboxes.
 
@@ -402,9 +490,31 @@ The `ConnectionConfig` class manages API server connection settings.
 | `request_timeout` | Timeout for API requests                   | 30 seconds                   | -                      |
 | `debug`           | Enable debug logging for HTTP requests     | `False`                      | -                      |
 | `headers`         | Custom HTTP headers                        | Empty                        | -                      |
+| `follow_redirects` | Follow HTTP redirects for SDK requests      | `False`                      | -                      |
+| `event_hooks`     | Additional httpx hooks for adapter clients   | Empty                        | -                      |
 | `transport`       | Shared httpx transport (pool/proxy/retry)  | SDK-created per instance     | -                      |
 | `use_server_proxy` | Use sandbox server as proxy for execd/endpoint requests (e.g. when client cannot reach the sandbox directly) | `False` | -                      |
 
+When `follow_redirects` is enabled, same-origin redirects preserve request
+headers. An origin is the combination of scheme, host, and port, so changing
+any of those values is cross-origin. Before following a cross-origin redirect,
+the SDK removes every header whose name starts with `OPEN-SANDBOX-` or
+`OPENSANDBOX-` (case-insensitive). Other custom headers are not stripped
+automatically.
+
+File uploads never follow redirects, even when `follow_redirects` is enabled,
+because streamed or file-backed multipart request bodies cannot always be
+safely replayed. This applies to both direct chunked uploads and uploads through
+the server proxy. A redirect response from an upload is surfaced as a
+`SandboxApiException` with the original 3xx status.
+
+`ConnectionConfig.event_hooks` accepts async httpx hooks, while
+`ConnectionConfigSync.event_hooks` accepts synchronous hooks. Configured
+request hooks run before the SDK safety hook, so they cannot re-add protected
+OpenSandbox headers to a cross-origin request. Lifecycle telemetry honors
+`follow_redirects` and the SDK safety hook, but does not invoke configured user
+hooks.
+
 ```python
 from datetime import timedelta
 

{opensandbox-0.1.17.dev0 → opensandbox-1.1.1}/pyproject.toml

@@ -1,4 +1,4 @@
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -46,13 +46,15 @@ dependencies = [
     "python-dateutil>=2.8.2,<3.0",
     "attrs>=21.3.0",
     "httpx>=0.27.0,<1.0",
+    "httpcore>=1.0.0,<2.0",
     "httpx-sse>=0.4.3,<0.5",
+    "opentelemetry-api>=1.20,<2.0",
 ]
 
 [project.optional-dependencies]
 pool-redis = [
     "redis>=5.0,<6.0",
-    "pyjwt>=2.13.0",
+    "pyjwt>=2.14.0",
 ]
 
 [project.urls]
@@ -67,8 +69,8 @@ source = "vcs"
 [tool.hatch.version.raw-options]
 # This package is in a subdirectory; explicitly point setuptools-scm at the git root.
 root = "../../.."
-tag_regex = "^python/sandbox/v(?P<version>\\d+\\.\\d+\\.\\d+(?:[\\.\\w\\+\\-]*)?)$"
-git_describe_command = 'git describe --dirty --tags --long --match "python/sandbox/v*"'
+tag_regex = "^release-(?P<version>\\d+\\.\\d+\\.\\d+(?:[\\.\\w\\+\\-]*)?)$"
+git_describe_command = 'git describe --dirty --tags --long --match "release-*"'
 fallback_version = "0.1.16"
 
 [tool.hatch.build]
@@ -140,7 +142,7 @@ asyncio_mode = "auto"
 
 [tool.uv]
 constraint-dependencies = [
-    "pyjwt>=2.13.0",
+    "pyjwt>=2.14.0",
 ]
 
 [tool.coverage.run]
@@ -156,4 +158,5 @@ dev = [
     "ruff>=0.14.8",
     "pyright>=1.1.0",
     "openapi-python-client>=0.28.0",
+    "opentelemetry-sdk>=1.20,<2.0",
 ]

{opensandbox-0.1.17.dev0 → opensandbox-1.1.1}/src/opensandbox/__init__.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

opensandbox-1.1.1/src/opensandbox/_async_pool_reconciler.py

@@ -0,0 +1,135 @@
+#
+# Copyright 2025 The OpenSandbox Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""Async sandbox pool reconciliation logic."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable
+from datetime import datetime, timezone
+
+from opensandbox.pool_types import (
+    AsyncPoolConfig,
+    AsyncPoolStateStore,
+)
+from opensandbox.pool_types import (
+    reap_expired_idle_with_min_ttl_async as _reap_expired_idle_with_min_ttl_async,
+)
+
+logger = logging.getLogger(__name__)
+
+
+async def run_async_reconcile_tick(
+    *,
+    config: AsyncPoolConfig,
+    state_store: AsyncPoolStateStore,
+    on_discard_sandbox: Callable[[str], Awaitable[None]],
+    warming_count: int,
+    submit_warmups: Callable[[int], None],
+    on_primary_acquired: Callable[[], None] = lambda: None,
+) -> bool:
+    pool_name = config.pool_name
+    owner_id = str(config.owner_id)
+    ttl = config.primary_lock_ttl
+
+    if not await state_store.try_acquire_primary_lock(pool_name, owner_id, ttl):
+        logger.debug(f"Async reconcile skip (not primary): pool_name={pool_name}")
+        return False
+    on_primary_acquired()
+    await _run_primary_replenish_once(
+        config=config,
+        state_store=state_store,
+        on_discard_sandbox=on_discard_sandbox,
+        warming_count=warming_count,
+        submit_warmups=submit_warmups,
+    )
+    return True
+
+
+async def _run_primary_replenish_once(
+    *,
+    config: AsyncPoolConfig,
+    state_store: AsyncPoolStateStore,
+    on_discard_sandbox: Callable[[str], Awaitable[None]],
+    warming_count: int,
+    submit_warmups: Callable[[int], None],
+) -> None:
+    pool_name = config.pool_name
+    owner_id = str(config.owner_id)
+    ttl = config.primary_lock_ttl
+    now = datetime.now(timezone.utc)
+
+    discarded_alive = await _reap_expired_idle_with_min_ttl_async(
+        state_store, pool_name, now, config.acquire_min_remaining_ttl
+    )
+    for sandbox_id in discarded_alive:
+        await on_discard_sandbox(sandbox_id)
+    counters = await state_store.snapshot_counters(pool_name)
+    excess = max(0, counters.idle_count - config.max_idle)
+    to_remove = min(excess, int(config.warmup_concurrency or 1))
+    if to_remove > 0:
+        await _shrink_excess_idle(config, state_store, on_discard_sandbox, to_remove)
+        return
+
+    deficit = max(0, config.max_idle - counters.idle_count - warming_count)
+    to_create = min(deficit, config.warmup_create_qps)
+    if to_create == 0:
+        await state_store.renew_primary_lock(pool_name, owner_id, ttl)
+        return
+
+    if not await state_store.renew_primary_lock(pool_name, owner_id, ttl):
+        return
+
+    submit_warmups(to_create)
+
+
+async def _shrink_excess_idle(
+    config: AsyncPoolConfig,
+    state_store: AsyncPoolStateStore,
+    on_discard_sandbox: Callable[[str], Awaitable[None]],
+    to_remove: int,
+) -> None:
+    pool_name = config.pool_name
+    owner_id = str(config.owner_id)
+    ttl = config.primary_lock_ttl
+    removed = 0
+    for _ in range(to_remove):
+        if not await state_store.renew_primary_lock(pool_name, owner_id, ttl):
+            logger.warning(
+                f"Async reconcile lost primary lock before shrinking idle: pool_name={pool_name} removed={removed}"
+            )
+            return
+        sandbox_id = await state_store.try_take_idle(pool_name)
+        if sandbox_id is None:
+            return
+        await _discard(on_discard_sandbox, sandbox_id)
+        removed += 1
+
+    await state_store.renew_primary_lock(pool_name, owner_id, ttl)
+    logger.debug(
+        f"Async reconcile shrunk {removed} idle sandbox(es): pool_name={pool_name}"
+    )
+
+
+async def _discard(
+    on_discard_sandbox: Callable[[str], Awaitable[None]], sandbox_id: str
+) -> None:
+    try:
+        await on_discard_sandbox(sandbox_id)
+    except Exception as exc:
+        logger.warning(
+            f"Async reconcile sandbox cleanup failed: sandbox_id={sandbox_id} error={exc}"
+        )

{opensandbox-0.1.17.dev0 → opensandbox-1.1.1}/src/opensandbox/_async_pool_store.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

opensandbox-1.1.1/src/opensandbox/_httpx.py

@@ -0,0 +1,162 @@
+#
+# Copyright 2026 The OpenSandbox Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""httpx helpers shared by handwritten SDK adapters.
+
+These helpers preserve user-provided event hooks while appending the SDK's
+request hook that strips protected OpenSandbox headers from cross-origin
+requests. The SDK hook must run last so user hooks cannot accidentally re-add
+protected headers before httpx sends a redirected request.
+"""
+
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from typing import Protocol, TypedDict, TypeVar
+
+import httpx
+
+SyncEventHook = Callable[..., None]
+AsyncEventHook = Callable[..., Awaitable[None]]
+SyncEventHooks = Mapping[str, Sequence[SyncEventHook]]
+AsyncEventHooks = Mapping[str, Sequence[AsyncEventHook]]
+
+_HookT = TypeVar("_HookT")
+_PROTECTED_HEADER_PREFIXES = ("OPEN-SANDBOX-", "OPENSANDBOX-")
+
+_DEFAULT_PORTS = {
+    "http": 80,
+    "https": 443,
+}
+
+
+class _SyncRedirectConfig(Protocol):
+    follow_redirects: bool
+    event_hooks: dict[str, list[SyncEventHook]]
+
+
+class _AsyncRedirectConfig(Protocol):
+    follow_redirects: bool
+    event_hooks: dict[str, list[AsyncEventHook]]
+
+
+class SyncRedirectClientOptions(TypedDict):
+    """Redirect-related options accepted by ``httpx.Client``."""
+
+    follow_redirects: bool
+    event_hooks: dict[str, list[SyncEventHook]]
+
+
+class AsyncRedirectClientOptions(TypedDict):
+    """Redirect-related options accepted by ``httpx.AsyncClient``."""
+
+    follow_redirects: bool
+    event_hooks: dict[str, list[AsyncEventHook]]
+
+
+def _origin(url: httpx.URL) -> tuple[str, str | None, int | None]:
+    return (url.scheme, url.host, url.port or _DEFAULT_PORTS.get(url.scheme))
+
+
+def _strip_protected_headers_for_cross_origin_request(
+    request: httpx.Request,
+    *,
+    base_origin: tuple[str, str | None, int | None],
+) -> None:
+    if _origin(request.url) == base_origin:
+        return
+    protected_headers = [
+        name
+        for name in request.headers
+        if name.upper().startswith(_PROTECTED_HEADER_PREFIXES)
+    ]
+    for name in protected_headers:
+        del request.headers[name]
+
+
+def _copy_event_hooks(
+    event_hooks: Mapping[str, Sequence[_HookT]] | None,
+) -> dict[str, list[_HookT]]:
+    if event_hooks is None:
+        return {}
+    return {event: list(hooks) for event, hooks in event_hooks.items()}
+
+
+def build_redirect_event_hooks(
+    base_url: str,
+    event_hooks: SyncEventHooks | None = None,
+) -> dict[str, list[SyncEventHook]]:
+    """Build sync hooks for SDK clients.
+
+    Existing user hooks are copied and preserved. The SDK request hook is
+    appended after user request hooks so protected OpenSandbox headers are
+    removed from any request whose origin differs from ``base_url``.
+    """
+    base_origin = _origin(httpx.URL(base_url))
+
+    def strip_protected_headers(request: httpx.Request) -> None:
+        _strip_protected_headers_for_cross_origin_request(
+            request, base_origin=base_origin
+        )
+
+    hooks = _copy_event_hooks(event_hooks)
+    hooks.setdefault("request", []).append(strip_protected_headers)
+    return hooks
+
+
+def build_async_redirect_event_hooks(
+    base_url: str,
+    event_hooks: AsyncEventHooks | None = None,
+) -> dict[str, list[AsyncEventHook]]:
+    """Build async hooks for SDK clients.
+
+    Existing user hooks are copied and preserved. The SDK request hook is
+    appended after user request hooks so protected OpenSandbox headers are
+    removed from any request whose origin differs from ``base_url``.
+    """
+    base_origin = _origin(httpx.URL(base_url))
+
+    async def strip_protected_headers(request: httpx.Request) -> None:
+        _strip_protected_headers_for_cross_origin_request(
+            request, base_origin=base_origin
+        )
+
+    hooks = _copy_event_hooks(event_hooks)
+    hooks.setdefault("request", []).append(strip_protected_headers)
+    return hooks
+
+
+def build_redirect_client_options(
+    config: _SyncRedirectConfig,
+    base_url: str,
+    *,
+    additional_request_hooks: Sequence[SyncEventHook] = (),
+) -> SyncRedirectClientOptions:
+    """Build redirect options for a synchronous adapter client."""
+    event_hooks = build_redirect_event_hooks(base_url, config.event_hooks)
+    event_hooks.setdefault("request", [])[0:0] = additional_request_hooks
+    return {
+        "follow_redirects": config.follow_redirects,
+        "event_hooks": event_hooks,
+    }
+
+
+def build_async_redirect_client_options(
+    config: _AsyncRedirectConfig,
+    base_url: str,
+) -> AsyncRedirectClientOptions:
+    """Build redirect options for an asynchronous adapter client."""
+    return {
+        "follow_redirects": config.follow_redirects,
+        "event_hooks": build_async_redirect_event_hooks(base_url, config.event_hooks),
+    }