feat: Make the browser pool OpenAPI contract truthful

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 127
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-b20fcf2fc1cdb91b51ffd354adcd12d63b950ea98b69e13bee6a78a58498c2cd.yml
-openapi_spec_hash: bc8b527a963dd2c2d74b6f9e6ca56652
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-d7ab1ecb886cb7f86e7ce0926207db423a6650e8e12e7283a71f8682fbb472ae.yml
+openapi_spec_hash: 9323b0ba38d2d50b8506be4d7401c04d
 config_hash: 77ee715aa17061166f9a02b264a21b8d

src/kernel/resources/browser_pools.py

@@ -96,7 +96,8 @@ def create(
           chrome_policy: Custom Chrome enterprise policy overrides applied to all browsers in this pool.
               Keys are Chrome enterprise policy names; values must match their expected types.
               Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See
-              https://chromeenterprise.google/policies/
+              https://chromeenterprise.google/policies/ The serialized JSON payload is capped
+              at 5 MiB.
 
           extensions: List of browser extensions to load into the session. Provide each by id or name.
 
@@ -107,7 +108,7 @@ def create(
           headless: If true, launches the browser using a headless image. Defaults to false.
 
           kiosk_mode: If true, launches the browser in kiosk mode to hide address bar and tabs in live
-              view.
+              view. Defaults to false.
 
           name: Optional name for the browser pool. Must be unique within the project.
 
@@ -131,7 +132,7 @@ def create(
               chrome:// pages.
 
           stealth: If true, launches the browser in stealth mode to reduce detection by anti-bot
-              mechanisms.
+              mechanisms. Defaults to false.
 
           timeout_seconds: Default idle timeout in seconds for browsers acquired from this pool before they
               are destroyed. Defaults to 600 seconds. Minimum 10, maximum 259200 (72 hours).
@@ -252,10 +253,12 @@ def update(
         `refresh_on_profile_update`.
 
         Args:
-          chrome_policy: Custom Chrome enterprise policy overrides applied to all browsers in this pool.
-              Keys are Chrome enterprise policy names; values must match their expected types.
+          chrome_policy: If provided, replaces the custom Chrome enterprise policy overrides applied to
+              all browsers in this pool. Empty object clears any previously-set policy. Keys
+              are Chrome enterprise policy names; values must match their expected types.
               Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See
-              https://chromeenterprise.google/policies/
+              https://chromeenterprise.google/policies/ The serialized JSON payload is capped
+              at 5 MiB.
 
           discard_all_idle: Whether to discard all idle browsers and rebuild them immediately with the new
               configuration. Defaults to false. Only browsers that are idle when the update
@@ -264,47 +267,44 @@ def update(
               pool with that stale configuration until it is discarded (by this flag on a
               later update, or by flushing the pool).
 
-          extensions: List of browser extensions to load into the session. Provide each by id or name.
+          extensions: If provided, replaces the extension list. Empty array clears all
+              previously-selected extensions. Omit this field to leave extensions unchanged.
 
-          fill_rate_per_minute: Percentage of the pool to fill per minute. Defaults to 10. The cap is 25 for
-              most organizations but can be raised per-organization, so only the lower bound
-              is enforced here.
+          fill_rate_per_minute: If provided, replaces the percentage of the pool to fill per minute. The cap is
+              25 for most organizations but can be raised per-organization, so only the lower
+              bound is enforced here.
 
-          headless: If true, launches the browser using a headless image. Defaults to false.
+          headless: If provided, replaces whether browsers launch using a headless image.
 
-          kiosk_mode: If true, launches the browser in kiosk mode to hide address bar and tabs in live
-              view.
+          kiosk_mode: If provided, replaces whether browsers launch in kiosk mode.
 
-          name: Optional name for the browser pool. Must be unique within the project.
+          name: If provided, replaces the pool name. Empty string is a no-op; the pool name
+              cannot be cleared or reset to empty once assigned.
 
           profile: Profile configuration for browsers in a pool. Provide either id or name.
               Profiles must be created beforehand. Unlike single browser sessions, pools load
               the profile read-only and never persist changes back to it, so save_changes is
               omitted here. Any save_changes value sent on a pool profile is silently ignored
               rather than rejected.
 
-          proxy_id: Optional proxy to associate to the browser session. Must reference a proxy in
-              the same project as the browser session.
+          proxy_id: Empty string clears the previously-selected proxy. Omit this field to leave the
+              proxy unchanged.
 
-          refresh_on_profile_update: When true, flush idle browsers when the profile the pool uses is updated, so
-              pool browsers pick up the latest profile data. Requires a profile to be set on
-              the pool.
+          refresh_on_profile_update: If provided, replaces whether idle browsers are flushed when the profile the
+              pool uses is updated. Requires a profile to be set on the pool.
 
-          size: Number of browsers to maintain in the pool. The maximum size is determined by
-              your organization's pooled sessions limit (the sum of all pool sizes cannot
-              exceed your limit).
+          size: If provided, replaces the number of browsers to maintain in the pool. The
+              maximum size is determined by your organization's pooled sessions limit (the sum
+              of all pool sizes cannot exceed your limit).
 
-          start_url: Optional URL to navigate to when a new browser is warmed into the pool.
-              Best-effort: failures to navigate do not fail pool fill. Only applied to
-              newly-warmed browsers; browsers reused via release/acquire keep whatever URL the
-              previous lease left them on. Accepts any URL Chromium can resolve, including
-              chrome:// pages.
+          start_url: If provided, replaces the URL to navigate to when a new browser is warmed into
+              the pool. Empty string clears the previously-set URL. Omit this field to leave
+              it unchanged.
 
-          stealth: If true, launches the browser in stealth mode to reduce detection by anti-bot
-              mechanisms.
+          stealth: If provided, replaces whether browsers launch in stealth mode.
 
-          timeout_seconds: Default idle timeout in seconds for browsers acquired from this pool before they
-              are destroyed. Defaults to 600 seconds. Minimum 10, maximum 259200 (72 hours).
+          timeout_seconds: If provided, replaces the default idle timeout in seconds for browsers acquired
+              from this pool before they are destroyed. Minimum 10, maximum 259200 (72 hours).
 
           viewport: Initial browser window size in pixels with optional refresh rate. If omitted,
               image defaults apply (1920x1080@25). For GPU images, the default is
@@ -671,7 +671,8 @@ async def create(
           chrome_policy: Custom Chrome enterprise policy overrides applied to all browsers in this pool.
               Keys are Chrome enterprise policy names; values must match their expected types.
               Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See
-              https://chromeenterprise.google/policies/
+              https://chromeenterprise.google/policies/ The serialized JSON payload is capped
+              at 5 MiB.
 
           extensions: List of browser extensions to load into the session. Provide each by id or name.
 
@@ -682,7 +683,7 @@ async def create(
           headless: If true, launches the browser using a headless image. Defaults to false.
 
           kiosk_mode: If true, launches the browser in kiosk mode to hide address bar and tabs in live
-              view.
+              view. Defaults to false.
 
           name: Optional name for the browser pool. Must be unique within the project.
 
@@ -706,7 +707,7 @@ async def create(
               chrome:// pages.
 
           stealth: If true, launches the browser in stealth mode to reduce detection by anti-bot
-              mechanisms.
+              mechanisms. Defaults to false.
 
           timeout_seconds: Default idle timeout in seconds for browsers acquired from this pool before they
               are destroyed. Defaults to 600 seconds. Minimum 10, maximum 259200 (72 hours).
@@ -827,10 +828,12 @@ async def update(
         `refresh_on_profile_update`.
 
         Args:
-          chrome_policy: Custom Chrome enterprise policy overrides applied to all browsers in this pool.
-              Keys are Chrome enterprise policy names; values must match their expected types.
+          chrome_policy: If provided, replaces the custom Chrome enterprise policy overrides applied to
+              all browsers in this pool. Empty object clears any previously-set policy. Keys
+              are Chrome enterprise policy names; values must match their expected types.
               Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See
-              https://chromeenterprise.google/policies/
+              https://chromeenterprise.google/policies/ The serialized JSON payload is capped
+              at 5 MiB.
 
           discard_all_idle: Whether to discard all idle browsers and rebuild them immediately with the new
               configuration. Defaults to false. Only browsers that are idle when the update
@@ -839,47 +842,44 @@ async def update(
               pool with that stale configuration until it is discarded (by this flag on a
               later update, or by flushing the pool).
 
-          extensions: List of browser extensions to load into the session. Provide each by id or name.
+          extensions: If provided, replaces the extension list. Empty array clears all
+              previously-selected extensions. Omit this field to leave extensions unchanged.
 
-          fill_rate_per_minute: Percentage of the pool to fill per minute. Defaults to 10. The cap is 25 for
-              most organizations but can be raised per-organization, so only the lower bound
-              is enforced here.
+          fill_rate_per_minute: If provided, replaces the percentage of the pool to fill per minute. The cap is
+              25 for most organizations but can be raised per-organization, so only the lower
+              bound is enforced here.
 
-          headless: If true, launches the browser using a headless image. Defaults to false.
+          headless: If provided, replaces whether browsers launch using a headless image.
 
-          kiosk_mode: If true, launches the browser in kiosk mode to hide address bar and tabs in live
-              view.
+          kiosk_mode: If provided, replaces whether browsers launch in kiosk mode.
 
-          name: Optional name for the browser pool. Must be unique within the project.
+          name: If provided, replaces the pool name. Empty string is a no-op; the pool name
+              cannot be cleared or reset to empty once assigned.
 
           profile: Profile configuration for browsers in a pool. Provide either id or name.
               Profiles must be created beforehand. Unlike single browser sessions, pools load
               the profile read-only and never persist changes back to it, so save_changes is
               omitted here. Any save_changes value sent on a pool profile is silently ignored
               rather than rejected.
 
-          proxy_id: Optional proxy to associate to the browser session. Must reference a proxy in
-              the same project as the browser session.
+          proxy_id: Empty string clears the previously-selected proxy. Omit this field to leave the
+              proxy unchanged.
 
-          refresh_on_profile_update: When true, flush idle browsers when the profile the pool uses is updated, so
-              pool browsers pick up the latest profile data. Requires a profile to be set on
-              the pool.
+          refresh_on_profile_update: If provided, replaces whether idle browsers are flushed when the profile the
+              pool uses is updated. Requires a profile to be set on the pool.
 
-          size: Number of browsers to maintain in the pool. The maximum size is determined by
-              your organization's pooled sessions limit (the sum of all pool sizes cannot
-              exceed your limit).
+          size: If provided, replaces the number of browsers to maintain in the pool. The
+              maximum size is determined by your organization's pooled sessions limit (the sum
+              of all pool sizes cannot exceed your limit).
 
-          start_url: Optional URL to navigate to when a new browser is warmed into the pool.
-              Best-effort: failures to navigate do not fail pool fill. Only applied to
-              newly-warmed browsers; browsers reused via release/acquire keep whatever URL the
-              previous lease left them on. Accepts any URL Chromium can resolve, including
-              chrome:// pages.
+          start_url: If provided, replaces the URL to navigate to when a new browser is warmed into
+              the pool. Empty string clears the previously-set URL. Omit this field to leave
+              it unchanged.
 
-          stealth: If true, launches the browser in stealth mode to reduce detection by anti-bot
-              mechanisms.
+          stealth: If provided, replaces whether browsers launch in stealth mode.
 
-          timeout_seconds: Default idle timeout in seconds for browsers acquired from this pool before they
-              are destroyed. Defaults to 600 seconds. Minimum 10, maximum 259200 (72 hours).
+          timeout_seconds: If provided, replaces the default idle timeout in seconds for browsers acquired
+              from this pool before they are destroyed. Minimum 10, maximum 259200 (72 hours).
 
           viewport: Initial browser window size in pixels with optional refresh rate. If omitted,
               image defaults apply (1920x1080@25). For GPU images, the default is

src/kernel/types/browser_pool.py

@@ -33,7 +33,7 @@ class BrowserPoolConfig(BaseModel):
     """Configuration used to create all browsers in this pool"""
 
     size: int
-    """Number of browsers to maintain in the pool.
+    """Number of browsers maintained in the pool.
 
     The maximum size is determined by your organization's pooled sessions limit (the
     sum of all pool sizes cannot exceed your limit).
@@ -44,7 +44,8 @@ class BrowserPoolConfig(BaseModel):
 
     Keys are Chrome enterprise policy names; values must match their expected types.
     Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See
-    https://chromeenterprise.google/policies/
+    https://chromeenterprise.google/policies/ The serialized JSON payload is capped
+    at 5 MiB.
     """
 
     extensions: Optional[List[BrowserExtension]] = None
@@ -56,12 +57,12 @@ class BrowserPoolConfig(BaseModel):
     fill_rate_per_minute: Optional[int] = None
     """Percentage of the pool to fill per minute.
 
-    Defaults to 10. The cap is 25 for most organizations but can be raised
-    per-organization, so only the lower bound is enforced here.
+    The cap is 25 for most organizations but can be raised per-organization, so only
+    the lower bound is enforced here.
     """
 
     headless: Optional[bool] = None
-    """If true, launches the browser using a headless image. Defaults to false."""
+    """If true, launches the browser using a headless image."""
 
     kiosk_mode: Optional[bool] = None
     """
@@ -82,9 +83,9 @@ class BrowserPoolConfig(BaseModel):
     """
 
     proxy_id: Optional[str] = None
-    """Optional proxy to associate to the browser session.
+    """Optional proxy associated to the browser session.
 
-    Must reference a proxy in the same project as the browser session.
+    References a proxy in the same project as the browser session.
     """
 
     refresh_on_profile_update: Optional[bool] = None
@@ -112,7 +113,7 @@ class BrowserPoolConfig(BaseModel):
     timeout_seconds: Optional[int] = None
     """
     Default idle timeout in seconds for browsers acquired from this pool before they
-    are destroyed. Defaults to 600 seconds. Minimum 10, maximum 259200 (72 hours).
+    are destroyed. Minimum 10, maximum 259200 (72 hours).
     """
 
     viewport: Optional[BrowserViewport] = None

src/kernel/types/browser_pool_create_params.py

@@ -24,7 +24,8 @@ class BrowserPoolCreateParams(TypedDict, total=False):
 
     Keys are Chrome enterprise policy names; values must match their expected types.
     Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See
-    https://chromeenterprise.google/policies/
+    https://chromeenterprise.google/policies/ The serialized JSON payload is capped
+    at 5 MiB.
     """
 
     extensions: Iterable[BrowserExtension]
@@ -46,7 +47,7 @@ class BrowserPoolCreateParams(TypedDict, total=False):
     kiosk_mode: bool
     """
     If true, launches the browser in kiosk mode to hide address bar and tabs in live
-    view.
+    view. Defaults to false.
     """
 
     name: str
@@ -86,7 +87,7 @@ class BrowserPoolCreateParams(TypedDict, total=False):
     stealth: bool
     """
     If true, launches the browser in stealth mode to reduce detection by anti-bot
-    mechanisms.
+    mechanisms. Defaults to false.
     """
 
     timeout_seconds: int