# why
to address comments on earlier PRs in this stack

# what changed
- aligned request-header handling across SDKs. HTTP clients supply host
& transfer headers; SDKs supply the Browserbase key & Gateway session
header. ordinary application headers remain supported. malformed headers
fail before HTTP dispatch, so Go no longer reports them as retryable
network failures.
- preserved non-ASCII response header bytes in Python so the worker can
reconstruct the response without rejecting its headers.
- cancelled pending TypeScript Browserbase requests when the browser
closes, including when the socket does not deliver another close event.
- reused Python HTTP connections across requests on the same RPC
connection, closing the pool after pending requests are cancelled during
cleanup.
- skipped cache request bodies larger than 25 MB (25,000,000 UTF-8
bytes) before sending them over RPC. normal execution continues. an
oversized read reports `payload_too_large` & skips the later write; an
independently oversized write is skipped without replacing the read's
metadata.
- reported cache read deadlines as `timeout`, keeping `read_failed` for
other failures & preserving cancellation of the user's operation.

# test plan

- shared header fixtures & local HTTP tests cover filtering, malformed
input, preserved application headers, & Python response header decoding.
- lifecycle tests cover explicit browser close, cancellation, Python
connection reuse, disconnects, & pool cleanup.
- cache tests cover the exact size boundary, multibyte UTF-8, skipped
reads/writes, normal execution after a skip, timeouts, & caller
cancellation.
- protocol & SDK tests cover valid initialization, missing browser
metadata, removed init fields, & rejection before dispatch. generator
checks verify the validation survives regeneration

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Aligns Browserbase HTTP transport behavior across the Go, Python, and
TypeScript SDKs so header validation, connection handling, cancellation,
and cache error semantics are consistent. Malformed request headers now
fail before HTTP dispatch instead of surfacing as retryable network
failures, and client Browserbase init params now require browser
metadata and reject `api_key` and `api_url` since the browser handle's
connection supplies those.

**What changed**
- SDKs validate request headers and strip host, content-length,
hop-by-hop, and forwarding headers; they supply `x-bb-api-key`, and for
`gateway.responses` also `x-bb-session-id` and a default
`Authorization`.
- Python preserves non-ASCII response header bytes as Latin-1 so the
worker can reconstruct the response without rejecting its headers.
- TypeScript cancels pending Browserbase requests when the browser or
context closes, including when the socket never emits a close event;
Python reuses one HTTP connection per RPC connection and closes the pool
during cleanup.
- Cache requests whose serialized body exceeds 25,000,000 UTF-8 bytes
are skipped with `payload_too_large`; an independently oversized write
is skipped without replacing the read metadata, and cache read timeouts
are reported as `timeout` rather than `read_failed`.

<sup>Written for commit 1900e78351789c5e32603ccd0b768b4eb56ad230.
Summary will update on new commits.</sup>

<a
href="https://cubic.dev/pr/browserbase/stagehand/pull/3229?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="View guided diff"
src="https://www.cubic.dev/buttons/review-in-cubic-light.svg"></picture></a>
<a
href="https://www.cubic.dev/action/auto-fix/pr/browserbase/stagehand/3229?returnTo=https%3A%2F%2Fgithub.com%2Fbrowserbase%2Fstagehand%2Fpull%2F3229&source=description"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/turn-on-auto-fix-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/turn-on-auto-fix-light.svg"><img
alt="Turn on auto-fix"
src="https://www.cubic.dev/buttons/turn-on-auto-fix-light.svg"></picture></a>

<!-- End of auto-generated description by cubic. -->