[feat]: add HTTP transport to python SDK

Merged
SE
2d ago
+1146-4

why

the protocol now lets the worker ask an SDK to make an HTTP request. the python SDK needs an implementation that can receive that request, send it over HTTP, & return the response while the original Stagehand call is still waiting

this PR adds the python implementation of #3205 using the SDK's existing httpx dependency & RPC connection

what changed

  • added a connection snapshot with the same browser-factory precedence, regional endpoints, & API URL override behavior as the TypeScript implementation
  • added one HTTP attempt per Gateway, cache read, or cache write request. the executor applies bb headers & returns the buffered status, headers, & body, including HTTP errors & redirects.
  • used the caller's remaining timeout through body buffering, without adding an httpx default timeout or a second retry loop
  • added request & cancellation handlers to the existing RPC connection. explicit request cancellation, task cancellation, disconnect, & disposal stop the corresponding HTTP work & release its resources

test plan

  • shared fixtures & connection tests cover endpoint selection, precedence, & snapshots remaining unchanged after caller inputs are mutated.
  • local HTTP tests cover header precedence, response decoding, redirects, network failures, & deadlines before headers and during body delivery.
  • RPC tests cover requests during a pending batch call, cancellation, duplicate IDs, independent connections, & handler disposal

Summary by cubic

Adds the Python SDK implementation of the Browserbase HTTP transport, letting a worker ask the SDK to make HTTP requests over the RPC connection while the original Stagehand call is still pending.

  • Resolves a Browserbase connection snapshot (API key, API URL, session ID) with the same precedence, regional endpoints, and override behavior as the TypeScript SDK.
  • Executes one httpx request per Gateway, cache read, or cache write, returning the buffered status, headers, and body — including HTTP errors and redirects — with no retry loop or httpx default timeout.
  • Uses the caller's remaining timeout through body buffering, without adding a second deadline.
  • Adds request and cancellation handlers to the RPC connection; cancellation, task cancellation, disconnect, and disposal stop in-flight HTTP work and release resources.