feat(api): headless browsers

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 17
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-0ac9428eb663361184124cdd6a6e80ae8dc72c927626c949f22aacc4f40095de.yml
-openapi_spec_hash: 27707667d706ac33f2d9ccb23c0f15c3
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-3ec96d0022acb32aa2676c2e7ae20152b899a776ccd499380c334c955b9ba071.yml
+openapi_spec_hash: b64c095d82185c1cd0355abea88b606f
 config_hash: 00ec9df250b9dc077f8d3b93a442d252

src/kernel/resources/browsers.py

@@ -47,6 +47,7 @@ def with_streaming_response(self) -> BrowsersResourceWithStreamingResponse:
     def create(
         self,
         *,
+        headless: bool | NotGiven = NOT_GIVEN,
         invocation_id: str | NotGiven = NOT_GIVEN,
         persistence: BrowserPersistenceParam | NotGiven = NOT_GIVEN,
         stealth: bool | NotGiven = NOT_GIVEN,
@@ -61,6 +62,9 @@ def create(
         Create a new browser session from within an action.
 
         Args:
+          headless: If true, launches the browser using a headless image (no VNC/GUI). Defaults to
+              false.
+
           invocation_id: action invocation ID
 
           persistence: Optional persistence configuration for the browser session.
@@ -80,6 +84,7 @@ def create(
             "/browsers",
             body=maybe_transform(
                 {
+                    "headless": headless,
                     "invocation_id": invocation_id,
                     "persistence": persistence,
                     "stealth": stealth,
@@ -240,6 +245,7 @@ def with_streaming_response(self) -> AsyncBrowsersResourceWithStreamingResponse:
     async def create(
         self,
         *,
+        headless: bool | NotGiven = NOT_GIVEN,
         invocation_id: str | NotGiven = NOT_GIVEN,
         persistence: BrowserPersistenceParam | NotGiven = NOT_GIVEN,
         stealth: bool | NotGiven = NOT_GIVEN,
@@ -254,6 +260,9 @@ async def create(
         Create a new browser session from within an action.
 
         Args:
+          headless: If true, launches the browser using a headless image (no VNC/GUI). Defaults to
+              false.
+
           invocation_id: action invocation ID
 
           persistence: Optional persistence configuration for the browser session.
@@ -273,6 +282,7 @@ async def create(
             "/browsers",
             body=await async_maybe_transform(
                 {
+                    "headless": headless,
                     "invocation_id": invocation_id,
                     "persistence": persistence,
                     "stealth": stealth,

src/kernel/types/browser_create_params.py

@@ -10,6 +10,12 @@
 
 
 class BrowserCreateParams(TypedDict, total=False):
+    headless: bool
+    """If true, launches the browser using a headless image (no VNC/GUI).
+
+    Defaults to false.
+    """
+
     invocation_id: str
     """action invocation ID"""
 

src/kernel/types/browser_create_response.py

@@ -9,14 +9,17 @@
 
 
 class BrowserCreateResponse(BaseModel):
-    browser_live_view_url: str
-    """Remote URL for live viewing the browser session"""
-
     cdp_ws_url: str
     """Websocket URL for Chrome DevTools Protocol connections to the browser session"""
 
     session_id: str
     """Unique identifier for the browser session"""
 
+    browser_live_view_url: Optional[str] = None
+    """Remote URL for live viewing the browser session.
+
+    Only available for non-headless browsers.
+    """
+
     persistence: Optional[BrowserPersistence] = None
     """Optional persistence configuration for the browser session."""

src/kernel/types/browser_list_response.py

@@ -10,15 +10,18 @@
 
 
 class BrowserListResponseItem(BaseModel):
-    browser_live_view_url: str
-    """Remote URL for live viewing the browser session"""
-
     cdp_ws_url: str
     """Websocket URL for Chrome DevTools Protocol connections to the browser session"""
 
     session_id: str
     """Unique identifier for the browser session"""
 
+    browser_live_view_url: Optional[str] = None
+    """Remote URL for live viewing the browser session.
+
+    Only available for non-headless browsers.
+    """
+
     persistence: Optional[BrowserPersistence] = None
     """Optional persistence configuration for the browser session."""
 

src/kernel/types/browser_retrieve_response.py

@@ -9,14 +9,17 @@
 
 
 class BrowserRetrieveResponse(BaseModel):
-    browser_live_view_url: str
-    """Remote URL for live viewing the browser session"""
-
     cdp_ws_url: str
     """Websocket URL for Chrome DevTools Protocol connections to the browser session"""
 
     session_id: str
     """Unique identifier for the browser session"""
 
+    browser_live_view_url: Optional[str] = None
+    """Remote URL for live viewing the browser session.
+
+    Only available for non-headless browsers.
+    """
+
     persistence: Optional[BrowserPersistence] = None
     """Optional persistence configuration for the browser session."""

tests/api_resources/test_browsers.py

@@ -31,6 +31,7 @@ def test_method_create(self, client: Kernel) -> None:
     @parametrize
     def test_method_create_with_all_params(self, client: Kernel) -> None:
         browser = client.browsers.create(
+            headless=False,
             invocation_id="rr33xuugxj9h0bkf1rdt2bet",
             persistence={"id": "my-awesome-browser-for-user-1234"},
             stealth=True,
@@ -221,6 +222,7 @@ async def test_method_create(self, async_client: AsyncKernel) -> None:
     @parametrize
     async def test_method_create_with_all_params(self, async_client: AsyncKernel) -> None:
         browser = await async_client.browsers.create(
+            headless=False,
             invocation_id="rr33xuugxj9h0bkf1rdt2bet",
             persistence={"id": "my-awesome-browser-for-user-1234"},
             stealth=True,