feat: add H3 transport infrastructure, sandbox URL resolution, and header refresh

[devin-ai-integration]

feat: add H3 transport infrastructure, sandbox URL resolution, and header refresh

Summary

Adds HTTP/3 (QUIC) transport infrastructure to the Python SDK and fixes several issues with sandbox creation and header caching.

What's included

1. H3 transport module (h3transport.py, h3warm.py): Full QUIC/H3 transport layer using aioquic — includes H3Pool with connection pooling, AsyncH3FallbackTransport / SyncH3FallbackTransport that auto-downgrade to HTTP/2 on QUIC failure, and a negative cache with 300s TTL. This infrastructure is available for future use but not yet wired into the hot path (see note below).

2. Fresh headers via event hooks (default/action.py, sync/action.py): SandboxAction.get_client() now uses httpx event_hooks to inject settings.headers on every request, fixing a bug where the H2 client cached headers at creation time and missed token refreshes.

3. Region apply-back fix (default/sandbox.py, sync/sandbox.py): The else branch in create() (for raw Sandbox objects) now applies the extracted region back to sandbox.spec.region. Previously, the fallback to settings.region was computed but never written back.

4. Race condition fix (h3transport.py): H3Pool._get_or_connect() now holds the async lock across the entire check+connect+store sequence to prevent duplicate QUIC connections for the same (host, port).

5. Cold-call benchmark (tests/benchmarks/bench_cold_call.py): Measures end-to-end latency of sandbox lifecycle operations (create → call → delete) with per-phase breakdown.

Important context

• H3 connection warming was initially wired into SandboxInstance.create() but was removed because the background QUIC connections interfered with anyio task groups used by the MCP library. The H3 transport modules remain available for future integration.
• aioquic is an optional dependency under [h3] extras (pip install blaxel[h3]). All H3 classes are guarded with if AIOQUIC_AVAILABLE: so the module imports cleanly without aioquic.
• The tools/__init__.py sandbox URL resolution changes from earlier revisions have been superseded by main's refactor (merged in commit 4c32ad1). Main introduced _fetch_metadata_url / _resolve_url / retry-based initialize which replaces our earlier _resolved_url / _get_transport_type / fallback approach. This PR now carries no diff in tools/__init__.py.

Updates since last revision

• Merged main to resolve conflicts in tools/__init__.py. Accepted main's refactored URL resolution (_metadata_url, _fetch_metadata_url, _resolve_url, retry-based initialize) which supersedes the sandbox URL resolution code previously in this PR.

Changed files:

• h3transport.py (new): Full async/sync H3 transport with connection pooling, HTTP/2 fallback, and AIOQUIC_AVAILABLE guards
• h3warm.py (new): QUIC connection warming utility
• default/action.py, sync/action.py: httpx event hook for dynamic header injection
• default/sandbox.py, sync/sandbox.py: Region extraction and apply-back
• sandbox/types.py: h3_transport field added to SandboxConfiguration
• autoload.py: Minor comment cleanup
• pyproject.toml: Adds [h3] optional extras with aioquic>=1.2.0
• default/filesystem.py, sync/filesystem.py, default/process.py, sync/process.py: H3 transport scaffolding (currently unused)
• tests/benchmarks/bench_cold_call.py (new): Cold-call latency benchmark
• tests/integration/openai/test_tools.py: Adds wait_for_sandbox_deployed guard

Review & Testing Checklist for Human

• Region fallback behavior change: Sandboxes created via raw Sandbox objects without spec.region will now inherit settings.region. Verify this doesn't break code that expects sandboxes without regions.
• Event hook header injection: The httpx event hooks for dynamic headers aren't covered by unit tests. Test that token refreshes are properly picked up on subsequent requests.
• H3 connection serialization tradeoff: _get_or_connect() serializes all connection attempts (not just same-host), which may impact performance if H3 warming is re-enabled for multiple hosts concurrently.
• Optional dependency pattern: Verify that import blaxel.core works when aioquic is not installed and that H3 gracefully falls back to HTTP/2.

Test Plan

1. Integration tests: All framework tests (crewai, llamaindex, openai, livekit, googleadk, langgraph, pydantic) + unit tests should pass (CI: 15/16 pass, 1 non-required failure).
2. Token refresh: If using client credentials with short-lived tokens, verify requests pick up refreshed tokens without re-creating the client.
3. Optional dependency: Test that import blaxel.core works when aioquic is not installed.
4. Region inheritance: Create a sandbox using a raw Sandbox object without spec.region and verify it inherits settings.region.

Notes

Requested by @Joffref
Devin Session: https://app.devin.ai/sessions/f158717eb819492e8e4307d1ca9a658f

Originally intended to mirror the TypeScript SDK's H2 connection warming (sdk-typescript#260), but background QUIC tasks interfered with MCP library internals. The H3 transport infrastructure remains for future integration. Since aioquic is now an optional dependency, users can experiment with H3 via pip install blaxel[h3].

---

Note

This PR adds HTTP/3 (QUIC) transport infrastructure as an optional dependency (pip install blaxel[h3]), fixes sandbox MCP URL resolution by fetching direct data-plane URLs from the management API, and replaces static header baking with httpx event hooks for automatic token refresh. The H3 transport is available for future use but not yet wired into the hot path. The last commit merges main's tools/__init__.py refactor (PR #119), which replaced the probe-based transport detection with a simpler retry loop.

^{Written by Mendral for commit 4c32ad1.}

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR that start with 'DevinAI' or '@devin'.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[Joffref]

DevinAI fix the code to pass the tests cases please

[Joffref]

DevinAI, address mendral comments please.

[devin-ai-integration]

Addressed all three Mendral comments in caf8e5a:

1. tools/__init__.py — probe_url now respects use_fallback_url, so when initialize() falls back, the transport probe hits the gateway URL instead of the unreachable direct sandbox URL.

2. h3transport.py — Moved _async_transports.pop(key, None) inside the with self._lock block in _mark_failed() to eliminate the data race with _get_or_connect().

3. pyproject.toml — Moved aioquic>=1.2.0 from core dependencies to [project.optional-dependencies] h3 = [...]. Users who don't need H3 transport won't pull in pyopenssl, pylsqpack, service-identity, etc.

[mendral-app]

🤖 Code Review

Assessment ✅

All three previously flagged issues are now resolved in commits caf8e5a and 8f55cd7:

1. aioquic optional dependency ✅ — moved from core dependencies to [project.optional-dependencies] under h3 = ["aioquic>=1.2.0"]. Imports are wrapped in try/except ImportError with AIOQUIC_AVAILABLE guard, and the pool singleton is None when aioquic is absent.

2. _mark_failed data race ✅ — _async_transports.pop() is now inside the with self._lock: block alongside _connect_contexts.pop(), making the cleanup atomic.

3. probe_url fallback correctness ✅ — _get_transport_type() now uses (self._resolved_url if self._resolved_url and not self.use_fallback_url else None) or self._url, so when initialize() sets use_fallback_url = True after a failed connection, the probe correctly targets the gateway URL rather than the unreachable direct sandbox URL. _get_transport() uses the same guard, keeping URL selection consistent.

No new issues introduced by the two new commits. The PR is ready to merge.

Note

Tag @mendral-app with feedback or questions. View session

[mendral-app]

🤖 Code Review

Assessment ✅

All three previously flagged high-severity issues are now resolved:

1. _mark_failed data race — ✅ Fixed in caf8e5a: _async_transports.pop() is now inside the with self._lock: block alongside _connect_contexts.pop().

2. aioquic as mandatory core dependency — ✅ Fixed in caf8e5a + 8f55cd7: moved to [project.optional-dependencies] under the h3 extras group; all aioquic imports are now conditional via try/except, and all aioquic-dependent classes are guarded inside if AIOQUIC_AVAILABLE:.

3. Probe URL using wrong URL on fallback — ✅ Fixed in cbfb12f: probe_url now correctly evaluates self._resolved_url if self._resolved_url and not self.use_fallback_url else None) or self._url, so when use_fallback_url=True, the probe falls through to self._url which returns the gateway fallback URL.

The code is in good shape. No new issues found in the latest commits.

Note

Tag @mendral-app with feedback or questions. View session

[cploujoux]

Please review AI comments before assigning me issue

[Joffref]

DevinAI, can you address the comments of the review?

[devin-ai-integration]

Fixed in a10bb3f — region is now applied back to sandbox.spec.region in the else branch, matching the behavior of the if branch (line 224). Also replaced getattr(sandbox.spec, "region", None) with direct attribute access sandbox.spec.region.

[cploujoux]

Should be a one liner

[devin-ai-integration]

Fixed in a10bb3f — same fix as async variant. Region is now applied back to sandbox.spec.region in the sync else branch.

[cploujoux]

Import at top level

[cploujoux]

Import at top level

[cploujoux]

Should be a one liner

[cploujoux]

Make sure this benchmark is not started on test

[cploujoux]

So we have an optimisation but it is going to be optionnal for now ?

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 9 additional findings in Devin Review.

[devin-ai-integration]

🔴 asyncio.Lock shared across different event loops provides no mutual exclusion

The H3Pool uses a single asyncio.Lock (via _get_async_lock) that is shared between coroutines running on different event loops. get_async_transport calls _get_or_connect on the caller's application event loop, while get_sync_transport schedules _get_or_connect on a separate background thread's event loop (self._bg_loop). An asyncio.Lock is designed for use within a single event loop — when a coroutine on loop A holds the lock and a coroutine on loop B tries to acquire it, the waiter's Future belongs to loop B but release() on loop A would call set_result() on that foreign-loop Future, which is not thread-safe. This defeats the stated purpose of preventing duplicate QUIC connections for the same (host, port), and can lead to leaked connections or crashes when sync and async transports are used concurrently.

Prompt for agents

In src/blaxel/core/common/h3transport.py, the H3Pool._get_async_lock() method (lines 283-286) returns a single asyncio.Lock that is used from two different event loops: the application loop (via get_async_transport) and the background thread loop (via get_sync_transport). asyncio.Lock does not work correctly across event loops.

To fix this, either:
1. Use separate asyncio.Lock instances per event loop (e.g., a dict keyed by loop id), or
2. Use a threading.Lock instead of asyncio.Lock for cross-loop synchronization (but be careful not to block the event loop while holding it — you may need to use asyncio.to_thread or run_in_executor), or
3. Ensure _get_or_connect is always called on the same event loop (e.g., always on the background loop) so the asyncio.Lock is only ever used from one loop.

Additionally, the _get_async_lock method has a race condition: the check-then-assign (if self._async_lock is None: self._async_lock = asyncio.Lock()) is not protected by any lock, so two threads could both create different Lock instances, with one overwriting the other. This should be protected by self._lock (the threading.Lock).

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[mendral-app]

Needs attention — 1 issue in 1 file

All three previously flagged issues are resolved: _mark_failed data race fixed, aioquic moved to optional extras, and the probe-URL/fallback issue is moot after the tools/__init__.py refactor from main. One new memory leak in _H3Transport needs fixing before H3 is wired into the hot path.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.

<assessment>
All three previously flagged issues are resolved: `_mark_failed` data race fixed, `aioquic` moved to optional extras, and the probe-URL/fallback issue is moot after the `tools/__init__.py` refactor from main. One new memory leak in `_H3Transport` needs fixing before H3 is wired into the hot path.
</assessment>

<file name="src/blaxel/core/common/h3transport.py">
<issue location="src/blaxel/core/common/h3transport.py:143">
`_read_queue` and `_read_ready` entries are never deleted after a stream completes, leaking memory on long-lived QUIC connections. Each request adds two dict entries that grow unboundedly.
</issue>
</file>

_{Tag @mendral-app with feedback or questions. View session}

[mendral-app]

bug (P2): _read_queue and _read_ready entries are never deleted after a stream completes, leaking memory on long-lived QUIC connections. Each request adds two dict entries that grow unboundedly.

Suggested change

Suggested change

	async def _receive_response_data(
	self, stream_id: int, stream_ended: bool
	) -> AsyncIterator[bytes]:
	while not stream_ended:
	event = await self._wait_for_http_event(stream_id)
	if isinstance(event, DataReceived):
	stream_ended = event.stream_ended
	yield event.data
	elif isinstance(event, HeadersReceived):
	stream_ended = event.stream_ended
	async def _wait_for_http_event(self, stream_id: int) -> H3Event:
	if not self._read_queue[stream_id]:
	await self._read_ready[stream_id].wait()
	event = self._read_queue[stream_id].popleft()
	if not self._read_queue[stream_id]:
	self._read_ready[stream_id].clear()
	return event
	async def _receive_response_data(
	self, stream_id: int, stream_ended: bool
	) -> AsyncIterator[bytes]:
	try:
	while not stream_ended:
	event = await self._wait_for_http_event(stream_id)
	if isinstance(event, DataReceived):
	stream_ended = event.stream_ended
	yield event.data
	elif isinstance(event, HeadersReceived):
	stream_ended = event.stream_ended
	finally:
	self._read_queue.pop(stream_id, None)
	self._read_ready.pop(stream_id, None)
	async def _wait_for_http_event(self, stream_id: int) -> H3Event:
	if not self._read_queue[stream_id]:
	await self._read_ready[stream_id].wait()
	event = self._read_queue[stream_id].popleft()
	if not self._read_queue[stream_id]:
	self._read_ready[stream_id].clear()
	return event

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/blaxel/core/common/h3transport.py, line 143:

<issue>
`_read_queue` and `_read_ready` entries are never deleted after a stream completes, leaking memory on long-lived QUIC connections. Each request adds two dict entries that grow unboundedly.
</issue>

[cploujoux]

Need fix conflict
and test everything works, t4est also with openai agent sdk