stagehand 4.2.0a0.dev1580__tar.gz → 4.2.0a0.dev1584__tar.gz

{stagehand-4.2.0a0.dev1580 → stagehand-4.2.0a0.dev1584}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stagehand
-Version: 4.2.0a0.dev1580
+Version: 4.2.0a0.dev1584
 Summary: Browserbase's SDK for building browser agents
 Keywords: ai,agent,ai-agent,browser,browser-agent,browser-automation,computer-use,headless,playwright,cdp,llm,automation,web-scraping,testing
 Author: Browserbase
@@ -18,6 +18,7 @@ Classifier: Topic :: Software Development :: Testing
 Classifier: Typing :: Typed
 Classifier: Framework :: AsyncIO
 Requires-Dist: browserbase>=1.15,<2
+Requires-Dist: httpx>=0.23,<1
 Requires-Dist: opentelemetry-api>=1.35,<2
 Requires-Dist: pydantic>=2.12,<3
 Requires-Dist: typing-extensions>=4.12,<5

{stagehand-4.2.0a0.dev1580 → stagehand-4.2.0a0.dev1584}/pyproject.toml

@@ -1,11 +1,12 @@
 [project]
 name = "stagehand"
-version = "4.2.0a0.dev1580"
+version = "4.2.0a0.dev1584"
 description = "Browserbase's SDK for building browser agents"
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
   "browserbase>=1.15,<2",
+  "httpx>=0.23,<1",
   "opentelemetry-api>=1.35,<2",
   "pydantic>=2.12,<3",
   "typing_extensions>=4.12,<5",
@@ -86,7 +87,7 @@ strict = true
 dev = [
   "datamodel-code-generator==0.68.1",
   "openai>=2,<3",
-  "pytest==9.0.2",
+  "pytest==9.0.3",
   "pytest-asyncio==1.3.0",
   "ruff==0.15.7",
   "ty==0.0.82",

{stagehand-4.2.0a0.dev1580 → stagehand-4.2.0a0.dev1584}/src/stagehand/__init__.py

@@ -68,6 +68,7 @@ from .client_models import (
     ExtractResult,
 )
 from .client_types import (
+    BrowserbaseClientOptions,
     CacheOptions,
     LLMGenerateCallback,
     LLMGenerateInput,
@@ -102,6 +103,7 @@ __all__ = [
     "BrowserClipboard",
     "BrowserContext",
     "BrowserbaseBrowserSettings",
+    "BrowserbaseClientOptions",
     "BrowserbaseFetchResult",
     "BrowserbaseProxyConfig",
     "BrowserbaseRegion",

{stagehand-4.2.0a0.dev1580 → stagehand-4.2.0a0.dev1584}/src/stagehand/_extension/service-worker.js

@@ -7363,7 +7363,7 @@ function isRecord$1(value) {
 }
 var package_default$1 = {
 	name: "@browserbasehq/stagehand-protocol",
-	version: "2.1.0-alpha-198d503e4e28c0cbfdf4294fa987e90652ebf24c",
+	version: "2.1.0-alpha-100e201a019aa55fadfce36744f560b37b66b682",
 	"private": true,
 	type: "module",
 	exports: {
@@ -12560,29 +12560,38 @@ strictObject({
 	extensionId: string().min(1).optional()
 }).meta({ id: "LocalBrowserConnectOptions" });
 var DEFAULT_BROWSERBASE_URL = "https://api.browserbase.com";
+var BrowserbaseClientOptionsSchema = strictObject({
+	timeout: int().nonnegative().optional(),
+	maxRetries: int().nonnegative().optional(),
+	defaultHeaders: record(string(), string().nullable().optional()).optional(),
+	defaultQuery: record(string(), string().optional()).optional(),
+	fetch: custom((value) => typeof value === "function", { message: "fetch must be a function" }).optional()
+});
 looseObject({
 	apiKey: string().min(1),
 	baseUrl: url().default(DEFAULT_BROWSERBASE_URL),
+	clientOptions: BrowserbaseClientOptionsSchema.optional(),
 	apiUrl: never().optional(),
 	type: never().optional()
 }).meta({ id: "BrowserbaseLaunchOptions" });
 strictObject({
 	apiKey: string().min(1),
 	baseUrl: url().default(DEFAULT_BROWSERBASE_URL),
+	clientOptions: BrowserbaseClientOptionsSchema.optional(),
 	sessionId: string().min(1),
 	extensionId: string().min(1).optional()
 }).meta({ id: "BrowserbaseConnectOptions" });
-var BrowserbaseClientOptionsSchema = {
+var BrowserbaseCredentialsShape = {
 	apiKey: string().min(1),
 	baseUrl: url().default(DEFAULT_BROWSERBASE_URL)
 };
 strictObject({
-	...BrowserbaseClientOptionsSchema,
+	...BrowserbaseCredentialsShape,
 	query: string().min(1).max(200),
 	numResults: int().min(1).max(25).optional()
 }).meta({ id: "BrowserbaseSearchOptions" });
 strictObject({
-	...BrowserbaseClientOptionsSchema,
+	...BrowserbaseCredentialsShape,
 	url: url(),
 	allowInsecureSsl: boolean().optional(),
 	allowRedirects: boolean().optional(),
@@ -54385,7 +54394,7 @@ var WebTracerProvider = class extends BasicTracerProvider {
 };
 var package_default = {
 	name: "@browserbasehq/stagehand-extension",
-	version: "1.1.0-alpha-198d503e4e28c0cbfdf4294fa987e90652ebf24c",
+	version: "1.1.0-alpha-100e201a019aa55fadfce36744f560b37b66b682",
 	"private": true,
 	type: "module",
 	scripts: {

{stagehand-4.2.0a0.dev1580 → stagehand-4.2.0a0.dev1584}/src/stagehand/_generated/protocol_version.py

@@ -1,4 +1,4 @@
 """Generated from packages/protocol/package.json. Do not edit."""
 
 PROTOCOL_SEMVER_PATTERN = '^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$'
-STAGEHAND_PROTOCOL_VERSION = '2.1.0-alpha-198d503e4e28c0cbfdf4294fa987e90652ebf24c'
+STAGEHAND_PROTOCOL_VERSION = '2.1.0-alpha-100e201a019aa55fadfce36744f560b37b66b682'

{stagehand-4.2.0a0.dev1580 → stagehand-4.2.0a0.dev1584}/src/stagehand/browser.py

@@ -30,6 +30,7 @@ from .browserbase_services import fetch_browserbase, search_browserbase
 from .browserbase_session import DEFAULT_BROWSERBASE_URL, _create_browserbase_session_client
 from .cdp_client import CDPClient, CDPConnectionClosedError
 from .client_models import (
+    BrowserbaseClientOptions,
     BrowserbaseConnectOptions,
     BrowserbaseFetchResult,
     BrowserbaseSearchResult,
@@ -40,6 +41,7 @@ from .client_models import (
     _BrowserbaseFetchOptions,
     _BrowserbaseSearchOptions,
 )
+from .client_types import BrowserbaseClientOptions as BrowserbaseClientOptionsInput
 from .extension_assets import extension_directory
 from .timeouts import stagehand_init_deadline
 
@@ -558,6 +560,17 @@ class _ConnectedBrowserSource:
         return None
 
 
+def _sdk_client_options(options: BrowserbaseClientOptions | None) -> dict[str, Any] | None:
+    if options is None:
+        return None
+    # Read attributes rather than model_dump so a caller's http_client passes through as-is.
+    return {
+        name: value
+        for name in type(options).model_fields
+        if (value := getattr(options, name)) is not None
+    }
+
+
 class BrowserbaseBrowser:
     @stagehand_init_deadline
     async def launch(
@@ -565,6 +578,7 @@ class BrowserbaseBrowser:
         *,
         api_key: str,
         base_url: str = DEFAULT_BROWSERBASE_URL,
+        client_options: BrowserbaseClientOptionsInput | None = None,
         browser_settings: BrowserbaseBrowserSettings | None = None,
         extension_id: str | None = None,
         keep_alive: bool | None = None,
@@ -598,9 +612,14 @@ class BrowserbaseBrowser:
             and not options.browser_settings.extension_id.strip()
         ):
             raise ValueError("browser_settings.extension_id must not be empty")
-        session = await _create_browserbase_session_client(api_key, base_url).create_session(
-            options
+        validated_client_options = (
+            BrowserbaseClientOptions.model_validate(client_options)
+            if client_options is not None
+            else None
         )
+        session = await _create_browserbase_session_client(
+            api_key, base_url, _sdk_client_options(validated_client_options)
+        ).create_session(options)
         source = ResolvedBrowserSource(
             cdp_url=session.cdp_url,
             keep_alive=options.keep_alive or False,
@@ -623,6 +642,7 @@ class BrowserbaseBrowser:
         *,
         api_key: str,
         base_url: str = DEFAULT_BROWSERBASE_URL,
+        client_options: BrowserbaseClientOptionsInput | None = None,
         session_id: str,
         extension_id: str | None = None,
     ) -> StagehandBrowser:
@@ -631,13 +651,14 @@ class BrowserbaseBrowser:
             for name, value in (
                 ("api_key", api_key),
                 ("base_url", base_url),
+                ("client_options", client_options),
                 ("session_id", session_id),
                 ("extension_id", extension_id),
             )
             if value is not None
         })
         connection = await _create_browserbase_session_client(
-            options.api_key, options.base_url
+            options.api_key, options.base_url, _sdk_client_options(options.client_options)
         ).connect_session(options.session_id)
         return await _connect_browser(
             provider="browserbase",

{stagehand-4.2.0a0.dev1580 → stagehand-4.2.0a0.dev1584}/src/stagehand/browserbase_session.py

@@ -1,14 +1,18 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Awaitable, Callable, Mapping
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
+from contextlib import asynccontextmanager
 from dataclasses import dataclass, field
-from typing import Any, Protocol
+from typing import TYPE_CHECKING, Any, Protocol
 
 from ._generated.models import BrowserbaseRegion, BrowserbaseSessionCreateParams
 from ._sdk_identity import STAGEHAND_SESSION_METADATA
 from .extension_assets import build_extension_archive
 
+if TYPE_CHECKING:
+    from browserbase import AsyncBrowserbase
+
 DEFAULT_BROWSERBASE_URL = "https://api.browserbase.com"
 
 
@@ -81,21 +85,41 @@ class _BrowserbaseAPI(Protocol):
 
 
 class _OfficialBrowserbaseAPI:
-    def __init__(self, api_key: str, base_url: str) -> None:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        client_options: Mapping[str, Any] | None = None,
+    ) -> None:
         self._api_key = api_key
         self._base_url = base_url
+        self._client_options = dict(client_options or {})
 
-    async def upload_extension(self, archive: bytes) -> str:
+    @asynccontextmanager
+    async def _client(self) -> AsyncIterator[AsyncBrowserbase]:
         from browserbase import AsyncBrowserbase
 
-        async with AsyncBrowserbase(api_key=self._api_key, base_url=self._base_url) as client:
+        client = AsyncBrowserbase(
+            **self._client_options,
+            api_key=self._api_key,
+            base_url=self._base_url,
+        )
+        if self._client_options.get("http_client") is not None:
+            # Closing AsyncBrowserbase closes its HTTP client, which the caller owns.
+            yield client
+            return
+        async with client:
+            yield client
+
+    async def upload_extension(self, archive: bytes) -> str:
+        async with self._client() as client:
             extension = await client.extensions.create(file=("stagehand-extension.zip", archive))
         return extension.id
 
     async def delete_extension(self, extension_id: str) -> None:
-        from browserbase import AsyncBrowserbase, omit
+        from browserbase import omit
 
-        async with AsyncBrowserbase(api_key=self._api_key, base_url=self._base_url) as client:
+        async with self._client() as client:
             await client.extensions.delete(extension_id, extra_headers={"Content-Type": omit})
 
     async def create_session(
@@ -105,14 +129,12 @@ class _OfficialBrowserbaseAPI:
         user_metadata: Mapping[str, Any],
         extension_id: str | None,
     ) -> tuple[str, str]:
-        from browserbase import AsyncBrowserbase
-
         kwargs = _session_create_kwargs(
             options,
             user_metadata=user_metadata,
             extension_id=extension_id,
         )
-        async with AsyncBrowserbase(api_key=self._api_key, base_url=self._base_url) as client:
+        async with self._client() as client:
             session = await client.sessions.create(**kwargs)
         return session.id, session.connect_url
 
@@ -120,9 +142,7 @@ class _OfficialBrowserbaseAPI:
         self,
         session_id: str,
     ) -> tuple[str, str | None, BrowserbaseRegion | None]:
-        from browserbase import AsyncBrowserbase
-
-        async with AsyncBrowserbase(api_key=self._api_key, base_url=self._base_url) as client:
+        async with self._client() as client:
             session = await client.sessions.retrieve(session_id)
         return (
             session.id,
@@ -131,9 +151,7 @@ class _OfficialBrowserbaseAPI:
         )
 
     async def release_session(self, session_id: str) -> None:
-        from browserbase import AsyncBrowserbase
-
-        async with AsyncBrowserbase(api_key=self._api_key, base_url=self._base_url) as client:
+        async with self._client() as client:
             await client.sessions.update(session_id, status="REQUEST_RELEASE")
 
 
@@ -298,5 +316,9 @@ class _BrowserbaseSessionClient:
         await self._delete_extension_best_effort(extension_id)
 
 
-def _create_browserbase_session_client(api_key: str, base_url: str) -> _BrowserbaseSessionClient:
-    return _BrowserbaseSessionClient(_OfficialBrowserbaseAPI(api_key, base_url))
+def _create_browserbase_session_client(
+    api_key: str,
+    base_url: str,
+    client_options: Mapping[str, Any] | None = None,
+) -> _BrowserbaseSessionClient:
+    return _BrowserbaseSessionClient(_OfficialBrowserbaseAPI(api_key, base_url, client_options))

{stagehand-4.2.0a0.dev1580 → stagehand-4.2.0a0.dev1584}/src/stagehand/client_models.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from collections.abc import Awaitable, Callable
 from typing import Annotated, Any, Generic, Literal, TypeVar
 
+import httpx
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from ._generated import models as _models
@@ -107,11 +108,22 @@ class LocalBrowserConnectOptions(WireModel):
     extension_id: Annotated[str | None, Field(min_length=1)] = None
 
 
+class BrowserbaseClientOptions(WireModel):
+    model_config = ConfigDict(extra="forbid", strict=True, arbitrary_types_allowed=True)
+
+    timeout: Annotated[float | None, Field(ge=0)] = None
+    max_retries: Annotated[int | None, Field(ge=0)] = None
+    default_headers: dict[str, str] | None = None
+    default_query: dict[str, str] | None = None
+    http_client: httpx.AsyncClient | None = None
+
+
 class BrowserbaseConnectOptions(WireModel):
     model_config = ConfigDict(extra="forbid", strict=True)
 
     api_key: Annotated[str, Field(min_length=1)]
     base_url: Annotated[str, Field(min_length=1)] = DEFAULT_BROWSERBASE_URL
+    client_options: BrowserbaseClientOptions | None = None
     session_id: Annotated[str, Field(min_length=1)]
     extension_id: Annotated[str | None, Field(min_length=1)] = None
 

{stagehand-4.2.0a0.dev1580 → stagehand-4.2.0a0.dev1584}/src/stagehand/client_types.py

@@ -3,6 +3,8 @@
 from collections.abc import Awaitable, Callable
 from typing import Literal, NotRequired, TypedDict
 
+import httpx
+
 from ._generated.input_types import (
     ModelConfig,
     TelemetryConfig,
@@ -66,9 +68,21 @@ class LocalBrowserConnectOptions(TypedDict):
     extension_id: NotRequired[str]
 
 
+class BrowserbaseClientOptions(TypedDict, total=False):
+    """HTTP settings for the Browserbase client Stagehand creates for session management."""
+
+    timeout: float
+    max_retries: int
+    default_headers: dict[str, str]
+    default_query: dict[str, str]
+    http_client: httpx.AsyncClient
+    """Caller-owned; Stagehand never closes it. Keep it open until `browser.close()` returns."""
+
+
 class BrowserbaseConnectOptions(TypedDict):
     api_key: str
     base_url: NotRequired[str]
+    client_options: NotRequired[BrowserbaseClientOptions]
     session_id: str
     extension_id: NotRequired[str]
 
@@ -96,6 +110,7 @@ class StagehandClientCreateConfig(TypedDict, total=False):
 
 
 __all__ = [
+    "BrowserbaseClientOptions",
     "BrowserbaseConnectOptions",
     "Cache",
     "CacheOptions",