feat: api: surface category field on browser telemetry events

stainless-app[bot] · stainless-app[bot] · commit 06a2f7babbc8 · 2026-05-29T17:40:31.000Z
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 117
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-04da2c2ed5f83c54f59f6c148abcf013cc37282fde2b3b5b263dffab927d5ba2.yml
-openapi_spec_hash: 9b05d6877797e55051a83222fa7652d0
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-4bada2a5bdbde93018e5a1b1e80e134acbc5509cfdea94db6e4c5b799eba7b82.yml
+openapi_spec_hash: e0d541d480f5663b1e6bd3bb19a0fe61
 config_hash: e0741f8035aea13f71e54e0fdb88eaa4
diff --git a/src/kernel/types/browsers/browser_console_error_event.py b/src/kernel/types/browsers/browser_console_error_event.py
@@ -65,6 +65,8 @@ class BrowserConsoleErrorEvent(BaseModel):
     Emitted from two distinct CDP sources with different data shapes. Runtime.consoleAPICalled (console.error calls) produces level, text, args, and stack_trace. Runtime.exceptionThrown (uncaught exceptions) produces text, line, column, source_url, and stack_trace. Fields not applicable to the source are absent.
     """
 
+    category: Literal["console"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_console_log_event.py b/src/kernel/types/browsers/browser_console_log_event.py
@@ -42,6 +42,8 @@ class Data(BrowserEventContext):
 class BrowserConsoleLogEvent(BaseModel):
     """A browser console log event (console.log, console.info, console.warn, etc.)."""
 
+    category: Literal["console"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_interaction_click_event.py b/src/kernel/types/browsers/browser_interaction_click_event.py
@@ -35,6 +35,8 @@ class Data(BrowserEventContext):
 class BrowserInteractionClickEvent(BaseModel):
     """A browser user click event captured via injected page script."""
 
+    category: Literal["interaction"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_interaction_key_event.py b/src/kernel/types/browsers/browser_interaction_key_event.py
@@ -29,6 +29,8 @@ class Data(BrowserEventContext):
 class BrowserInteractionKeyEvent(BaseModel):
     """A browser keyboard event captured via injected page script."""
 
+    category: Literal["interaction"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_interaction_scroll_settled_event.py b/src/kernel/types/browsers/browser_interaction_scroll_settled_event.py
@@ -37,6 +37,8 @@ class BrowserInteractionScrollSettledEvent(BaseModel):
     A browser scroll settled event emitted after scroll position stops changing, captured via injected page script.
     """
 
+    category: Literal["interaction"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_monitor_disconnected_event.py b/src/kernel/types/browsers/browser_monitor_disconnected_event.py
@@ -20,6 +20,8 @@ class BrowserMonitorDisconnectedEvent(BaseModel):
     Telemetry events may be dropped until monitor_reconnected arrives. Treat any in-progress computed state (network_idle, page_layout_settled) as unreliable until then.
     """
 
+    category: Literal["system"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_monitor_init_failed_event.py b/src/kernel/types/browsers/browser_monitor_init_failed_event.py
@@ -17,6 +17,8 @@ class Data(BaseModel):
 class BrowserMonitorInitFailedEvent(BaseModel):
     """The CDP session could not be initialized."""
 
+    category: Literal["system"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_monitor_reconnect_failed_event.py b/src/kernel/types/browsers/browser_monitor_reconnect_failed_event.py
@@ -23,6 +23,8 @@ class BrowserMonitorReconnectFailedEvent(BaseModel):
     The CDP connection to Chrome could not be re-established after exhausting all reconnection attempts. No further telemetry events will arrive on this session.
     """
 
+    category: Literal["system"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_monitor_reconnected_event.py b/src/kernel/types/browsers/browser_monitor_reconnected_event.py
@@ -19,6 +19,8 @@ class BrowserMonitorReconnectedEvent(BaseModel):
     The CDP connection to Chrome was successfully re-established after a disconnection. Events emitted during the gap are lost. Computed state is reset, so navigation and network tracking restart fresh from this point.
     """
 
+    category: Literal["system"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_monitor_screenshot_event.py b/src/kernel/types/browsers/browser_monitor_screenshot_event.py
@@ -17,6 +17,8 @@ class Data(BaseModel):
 class BrowserMonitorScreenshotEvent(BaseModel):
     """A periodic screenshot of the browser viewport."""
 
+    category: Literal["system"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_network_idle_event.py b/src/kernel/types/browsers/browser_network_idle_event.py
@@ -15,6 +15,8 @@ class BrowserNetworkIdleEvent(BaseModel):
     A browser network idle event emitted after a 500ms quiet period with no in-flight HTTP requests.
     """
 
+    category: Literal["network"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_network_loading_failed_event.py b/src/kernel/types/browsers/browser_network_loading_failed_event.py
@@ -39,6 +39,8 @@ class BrowserNetworkLoadingFailedEvent(BaseModel):
     If the request was already in flight when CDP attached (no prior network_request was emitted for it), url, frame_id, loader_id, and resource_type are absent; BrowserEventContext is partially populated in that case.
     """
 
+    category: Literal["network"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_network_request_event.py b/src/kernel/types/browsers/browser_network_request_event.py
@@ -55,6 +55,8 @@ class Data(BrowserEventContext):
 class BrowserNetworkRequestEvent(BaseModel):
     """A browser network request sent event."""
 
+    category: Literal["network"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_network_response_event.py b/src/kernel/types/browsers/browser_network_response_event.py
@@ -52,6 +52,8 @@ class BrowserNetworkResponseEvent(BaseModel):
     Fired after the response body is fully received, not when headers arrive.
     """
 
+    category: Literal["network"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_page_dom_content_loaded_event.py b/src/kernel/types/browsers/browser_page_dom_content_loaded_event.py
@@ -26,6 +26,8 @@ class Data(BrowserEventContext):
 class BrowserPageDomContentLoadedEvent(BaseModel):
     """A browser DOMContentLoaded event (CDP Page.domContentEventFired)."""
 
+    category: Literal["page"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_page_layout_settled_event.py b/src/kernel/types/browsers/browser_page_layout_settled_event.py
@@ -15,6 +15,8 @@ class BrowserPageLayoutSettledEvent(BaseModel):
     A browser layout settled event emitted 1 second after page load with no intervening layout shifts, indicating visual stability. Each layout shift resets the 1-second timer.
     """
 
+    category: Literal["page"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_page_layout_shift_event.py b/src/kernel/types/browsers/browser_page_layout_shift_event.py
@@ -50,6 +50,8 @@ class BrowserPageLayoutShiftEvent(BaseModel):
     A browser cumulative layout shift (CLS) event from the Performance Timeline API.
     """
 
+    category: Literal["page"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_page_lcp_event.py b/src/kernel/types/browsers/browser_page_lcp_event.py
@@ -56,6 +56,8 @@ class BrowserPageLcpEvent(BaseModel):
     A browser Largest Contentful Paint (LCP) event from the Performance Timeline API.
     """
 
+    category: Literal["page"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_page_load_event.py b/src/kernel/types/browsers/browser_page_load_event.py
@@ -26,6 +26,8 @@ class Data(BrowserEventContext):
 class BrowserPageLoadEvent(BaseModel):
     """A browser page load event (CDP Page.loadEventFired)."""
 
+    category: Literal["page"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_page_navigation_event.py b/src/kernel/types/browsers/browser_page_navigation_event.py
@@ -41,6 +41,8 @@ class BrowserPageNavigationEvent(BaseModel):
     Carries nav context fields inline but not nav_seq, as this event resets the navigation epoch.
     """
 
+    category: Literal["page"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_page_navigation_settled_event.py b/src/kernel/types/browsers/browser_page_navigation_settled_event.py
@@ -15,6 +15,8 @@ class BrowserPageNavigationSettledEvent(BaseModel):
     Emitted when page_dom_content_loaded and page_layout_settled have both fired for the same navigation, indicating the page is loaded and visually stable. Independent of network_idle; a single pending request does not block it.
     """
 
+    category: Literal["page"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
diff --git a/src/kernel/types/browsers/browser_page_tab_opened_event.py b/src/kernel/types/browsers/browser_page_tab_opened_event.py
@@ -31,6 +31,8 @@ class BrowserPageTabOpenedEvent(BaseModel):
     A new browser tab or target was opened (CDP Target.attachedToTarget for page targets). Fires before a CDP session is attached to the new target, so session_id, frame_id, loader_id, and nav_seq are absent; this event does not compose BrowserEventContext. Consumers reading context fields generically should treat it as a special case.
     """
 
+    category: Literal["page"]
+
     source: BrowserEventSource
     """Provenance metadata identifying which producer emitted the event."""
 
