feat: Layer telemetry request config onto the default set

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 125
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-8af2d28c8540273b1b413f49b8f9bcaa5df25fa2332d187d2693ec01502a2ac2.yml
-openapi_spec_hash: ee71b9231754b4682377a514d1a2c249
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-61dab8d0d01c2838febaf4319114ae35aa169a813a102e93af6598ca0d445da2.yml
+openapi_spec_hash: c9fbe809670384dc5141dccb60e45672
 config_hash: 06186eb40e0058a2a87ac251fc07415d

src/kernel/types/browser_create_params.py

@@ -134,16 +134,26 @@ class Telemetry(TypedDict, total=False):
     browser: BrowserTelemetryCategoriesConfigParam
     """Per-category capture flags.
 
-    Selection is opt-in: only the categories set to enabled=true are captured;
-    anything omitted is off. If enabled is true and browser is omitted or empty, the
-    default category set is used. A browser config that enables nothing stops
-    capture on update and starts no capture on create.
+    The operational categories (control, connection, system, captcha) are captured
+    whenever telemetry is enabled; set one to enabled=false to opt out. The CDP
+    categories (console, network, page, interaction) and screenshot are off by
+    default; set enabled=true to opt in. On create, provided categories layer onto
+    the default set. On update, provided categories merge onto the session's current
+    config; when no telemetry is active this falls back to the default set (matching
+    create). If browser is omitted or empty, the default set is used. A browser
+    config that disables every category stops capture on update and starts no
+    capture on create.
     """
 
     enabled: bool
     """Request shortcut for browser telemetry capture.
 
-    True enables capture using the default category set unless browser category
-    settings are provided. False stops capture on update and starts no capture on
-    create. enabled=false cannot be combined with browser category settings.
+    True enables capture; with no browser category settings it captures the default
+    set (control, connection, system, captcha), and any browser category settings
+    are layered onto that default set. On update, enabled=true resolves the config
+    fresh from the default set plus any provided categories, replacing the session's
+    current selection rather than merging onto it; omit enabled to merge categories
+    onto the current selection instead. False stops capture on update and starts no
+    capture on create. enabled=false cannot be combined with browser category
+    settings.
     """

src/kernel/types/browser_update_params.py

@@ -70,18 +70,28 @@ class Telemetry(TypedDict, total=False):
     browser: BrowserTelemetryCategoriesConfigParam
     """Per-category capture flags.
 
-    Selection is opt-in: only the categories set to enabled=true are captured;
-    anything omitted is off. If enabled is true and browser is omitted or empty, the
-    default category set is used. A browser config that enables nothing stops
-    capture on update and starts no capture on create.
+    The operational categories (control, connection, system, captcha) are captured
+    whenever telemetry is enabled; set one to enabled=false to opt out. The CDP
+    categories (console, network, page, interaction) and screenshot are off by
+    default; set enabled=true to opt in. On create, provided categories layer onto
+    the default set. On update, provided categories merge onto the session's current
+    config; when no telemetry is active this falls back to the default set (matching
+    create). If browser is omitted or empty, the default set is used. A browser
+    config that disables every category stops capture on update and starts no
+    capture on create.
     """
 
     enabled: bool
     """Request shortcut for browser telemetry capture.
 
-    True enables capture using the default category set unless browser category
-    settings are provided. False stops capture on update and starts no capture on
-    create. enabled=false cannot be combined with browser category settings.
+    True enables capture; with no browser category settings it captures the default
+    set (control, connection, system, captcha), and any browser category settings
+    are layered onto that default set. On update, enabled=true resolves the config
+    fresh from the default set plus any provided categories, replacing the session's
+    current selection rather than merging onto it; omit enabled to merge categories
+    onto the current selection instead. False stops capture on update and starts no
+    capture on create. enabled=false cannot be combined with browser category
+    settings.
     """
 
 

src/kernel/types/browsers/browser_telemetry_categories_config.py

@@ -9,9 +9,9 @@
 
 
 class BrowserTelemetryCategoriesConfig(BaseModel):
-    """Per-category telemetry capture settings.
+    """Per-category telemetry capture settings layered onto the default set.
 
-    Selection is opt-in: set a category to enabled=true to capture it; anything omitted is off. The default set (used by enabled=true with no per-category settings) is the lightweight operational signals: control, connection, system, captcha. The CDP categories (console, network, page, interaction) and screenshot are off by default and must be opted into.
+    The operational signals (control, connection, system, captcha) are on by default and are opt-out: set one to enabled=false to stop capturing it. The CDP categories (console, network, page, interaction) and screenshot are off by default and are opt-in: set enabled=true to capture them.
     """
 
     captcha: Optional[BrowserTelemetryCategoryConfig] = None

src/kernel/types/browsers/browser_telemetry_categories_config_param.py

@@ -10,9 +10,9 @@
 
 
 class BrowserTelemetryCategoriesConfigParam(TypedDict, total=False):
-    """Per-category telemetry capture settings.
+    """Per-category telemetry capture settings layered onto the default set.
 
-    Selection is opt-in: set a category to enabled=true to capture it; anything omitted is off. The default set (used by enabled=true with no per-category settings) is the lightweight operational signals: control, connection, system, captcha. The CDP categories (console, network, page, interaction) and screenshot are off by default and must be opted into.
+    The operational signals (control, connection, system, captcha) are on by default and are opt-out: set one to enabled=false to stop capturing it. The CDP categories (console, network, page, interaction) and screenshot are off by default and are opt-in: set enabled=true to capture them.
     """
 
     captcha: BrowserTelemetryCategoryConfigParam

src/kernel/types/browsers/browser_telemetry_category_config.py

@@ -13,5 +13,7 @@ class BrowserTelemetryCategoryConfig(BaseModel):
     enabled: Optional[bool] = None
     """Whether this category is captured.
 
-    Selection is opt-in, so an omitted category is not captured.
+    Operational categories (control, connection, system, captcha) default to true;
+    set false to opt out. CDP categories (console, network, page, interaction) and
+    screenshot default to false; set true to opt in.
     """

src/kernel/types/browsers/browser_telemetry_category_config_param.py

@@ -13,5 +13,7 @@ class BrowserTelemetryCategoryConfigParam(TypedDict, total=False):
     enabled: bool
     """Whether this category is captured.
 
-    Selection is opt-in, so an omitted category is not captured.
+    Operational categories (control, connection, system, captcha) default to true;
+    set false to opt out. CDP categories (console, network, page, interaction) and
+    screenshot default to false; set true to opt in.
     """