feat: Telemetry: expose opt-in categories + full event taxonomy (public API)

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 117
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-53de38ec04ee49846c89946b2fe72641c5ee005956d1fff4e8a50de9ba22e874.yml
-openapi_spec_hash: 96162b6a1e4a2521be1b6c4fb9b0e5ce
-config_hash: 590bf8cb85948cf1e63b7b5ef60686c8
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-9d489e3e43edfa64a754d4281241718e01c85d9a82ef3687df12bbd3c4ff5b42.yml
+openapi_spec_hash: a953cafb7f40ec8495dbd7df8bab8bad
+config_hash: bb7acce8576a50dd449b0c8f58ef0f1d

api.md

@@ -108,7 +108,11 @@ Types:
 
 ```python
 from kernel.types.browsers import (
+    BrowserAPICallEvent,
     BrowserCallStack,
+    BrowserCaptchaSolveResultEvent,
+    BrowserCdpConnectEvent,
+    BrowserCdpDisconnectEvent,
     BrowserConsoleErrorEvent,
     BrowserConsoleLogEvent,
     BrowserEventContext,
@@ -117,6 +121,8 @@ from kernel.types.browsers import (
     BrowserInteractionClickEvent,
     BrowserInteractionKeyEvent,
     BrowserInteractionScrollSettledEvent,
+    BrowserLiveViewConnectEvent,
+    BrowserLiveViewDisconnectEvent,
     BrowserMonitorDisconnectedEvent,
     BrowserMonitorInitFailedEvent,
     BrowserMonitorReconnectFailedEvent,
@@ -134,6 +140,8 @@ from kernel.types.browsers import (
     BrowserPageNavigationEvent,
     BrowserPageNavigationSettledEvent,
     BrowserPageTabOpenedEvent,
+    BrowserServiceCrashedEvent,
+    BrowserSystemOomKillEvent,
     BrowserTelemetryCategoriesConfig,
     BrowserTelemetryCategoryConfig,
     BrowserTelemetryConfig,

src/kernel/types/browser_create_params.py

@@ -131,17 +131,18 @@ class Telemetry(TypedDict, total=False):
     """
 
     browser: BrowserTelemetryCategoriesConfigParam
-    """Per-category enable/disable flags.
+    """Per-category capture flags.
 
-    If enabled is true and browser is omitted or empty, the VM default category set
-    is used. Explicitly disabling all four categories stops capture on update and
-    starts no capture on create.
+    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.
     """
 
     enabled: bool
     """Request shortcut for browser telemetry capture.
 
-    True enables capture using VM defaults 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 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.
     """

src/kernel/types/browser_update_params.py

@@ -52,19 +52,20 @@ class Telemetry(TypedDict, total=False):
     """
 
     browser: BrowserTelemetryCategoriesConfigParam
-    """Per-category enable/disable flags.
+    """Per-category capture flags.
 
-    If enabled is true and browser is omitted or empty, the VM default category set
-    is used. Explicitly disabling all four categories stops capture on update and
-    starts no capture on create.
+    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.
     """
 
     enabled: bool
     """Request shortcut for browser telemetry capture.
 
-    True enables capture using VM defaults 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 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.
     """
 
 

src/kernel/types/browsers/__init__.py

@@ -28,6 +28,7 @@
 from .process_kill_response import ProcessKillResponse as ProcessKillResponse
 from .process_resize_params import ProcessResizeParams as ProcessResizeParams
 from .replay_start_response import ReplayStartResponse as ReplayStartResponse
+from .browser_api_call_event import BrowserAPICallEvent as BrowserAPICallEvent
 from .browser_page_lcp_event import BrowserPageLcpEvent as BrowserPageLcpEvent
 from .computer_scroll_params import ComputerScrollParams as ComputerScrollParams
 from .process_spawn_response import ProcessSpawnResponse as ProcessSpawnResponse
@@ -37,6 +38,7 @@
 from .process_resize_response import ProcessResizeResponse as ProcessResizeResponse
 from .process_status_response import ProcessStatusResponse as ProcessStatusResponse
 from .browser_telemetry_config import BrowserTelemetryConfig as BrowserTelemetryConfig
+from .browser_cdp_connect_event import BrowserCdpConnectEvent as BrowserCdpConnectEvent
 from .browser_console_log_event import BrowserConsoleLogEvent as BrowserConsoleLogEvent
 from .computer_press_key_params import ComputerPressKeyParams as ComputerPressKeyParams
 from .computer_type_text_params import ComputerTypeTextParams as ComputerTypeTextParams
@@ -51,14 +53,18 @@
 from .browser_console_error_event import BrowserConsoleErrorEvent as BrowserConsoleErrorEvent
 from .computer_click_mouse_params import ComputerClickMouseParams as ComputerClickMouseParams
 from .playwright_execute_response import PlaywrightExecuteResponse as PlaywrightExecuteResponse
+from .browser_cdp_disconnect_event import BrowserCdpDisconnectEvent as BrowserCdpDisconnectEvent
 from .browser_interaction_key_event import BrowserInteractionKeyEvent as BrowserInteractionKeyEvent
 from .browser_network_request_event import BrowserNetworkRequestEvent as BrowserNetworkRequestEvent
 from .browser_page_navigation_event import BrowserPageNavigationEvent as BrowserPageNavigationEvent
 from .browser_page_tab_opened_event import BrowserPageTabOpenedEvent as BrowserPageTabOpenedEvent
+from .browser_service_crashed_event import BrowserServiceCrashedEvent as BrowserServiceCrashedEvent
+from .browser_system_oom_kill_event import BrowserSystemOomKillEvent as BrowserSystemOomKillEvent
 from .f_set_file_permissions_params import FSetFilePermissionsParams as FSetFilePermissionsParams
 from .browser_network_response_event import BrowserNetworkResponseEvent as BrowserNetworkResponseEvent
 from .process_stdout_stream_response import ProcessStdoutStreamResponse as ProcessStdoutStreamResponse
 from .browser_interaction_click_event import BrowserInteractionClickEvent as BrowserInteractionClickEvent
+from .browser_live_view_connect_event import BrowserLiveViewConnectEvent as BrowserLiveViewConnectEvent
 from .browser_page_layout_shift_event import BrowserPageLayoutShiftEvent as BrowserPageLayoutShiftEvent
 from .computer_write_clipboard_params import ComputerWriteClipboardParams as ComputerWriteClipboardParams
 from .browser_monitor_screenshot_event import BrowserMonitorScreenshotEvent as BrowserMonitorScreenshotEvent
@@ -67,6 +73,8 @@
 from .browser_monitor_reconnected_event import BrowserMonitorReconnectedEvent as BrowserMonitorReconnectedEvent
 from .browser_page_layout_settled_event import BrowserPageLayoutSettledEvent as BrowserPageLayoutSettledEvent
 from .browser_telemetry_category_config import BrowserTelemetryCategoryConfig as BrowserTelemetryCategoryConfig
+from .browser_captcha_solve_result_event import BrowserCaptchaSolveResultEvent as BrowserCaptchaSolveResultEvent
+from .browser_live_view_disconnect_event import BrowserLiveViewDisconnectEvent as BrowserLiveViewDisconnectEvent
 from .browser_monitor_disconnected_event import BrowserMonitorDisconnectedEvent as BrowserMonitorDisconnectedEvent
 from .computer_capture_screenshot_params import ComputerCaptureScreenshotParams as ComputerCaptureScreenshotParams
 from .browser_telemetry_categories_config import BrowserTelemetryCategoriesConfig as BrowserTelemetryCategoriesConfig

src/kernel/types/browsers/browser_api_call_event.py

@@ -0,0 +1,42 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+from typing_extensions import Literal
+
+from ..._models import BaseModel
+from .browser_event_source import BrowserEventSource
+
+__all__ = ["BrowserAPICallEvent", "Data"]
+
+
+class Data(BaseModel):
+    duration_ms: float
+    """Wall-clock duration of the handler in milliseconds."""
+
+    operation_id: str
+    """OpenAPI operationId of the matched route (e.g. processExec, takeScreenshot)."""
+
+    request_id: str
+    """Per-request identifier from the in-VM API request middleware."""
+
+    status: int
+    """HTTP response status code."""
+
+
+class BrowserAPICallEvent(BaseModel):
+    """An agent-driven HTTP call handled by the in-VM API server."""
+
+    category: Literal["control"]
+
+    source: BrowserEventSource
+    """Provenance metadata identifying which producer emitted the event."""
+
+    ts: int
+    """Event timestamp in Unix microseconds."""
+
+    type: Literal["api_call"]
+
+    data: Optional[Data] = None
+
+    truncated: Optional[bool] = None
+    """True if the data field was truncated due to size limits."""

src/kernel/types/browsers/browser_captcha_solve_result_event.py

@@ -0,0 +1,63 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+from typing_extensions import Literal
+
+from ..._models import BaseModel
+from .browser_event_source import BrowserEventSource
+
+__all__ = ["BrowserCaptchaSolveResultEvent", "Data"]
+
+
+class Data(BaseModel):
+    captcha_type: Literal["hcaptcha", "recaptcha_v2", "recaptcha_v3", "turnstile", "geetest", "other"]
+    """Captcha vendor family.
+
+    Provider-specific task names are normalized into this set; anything not covered
+    is reported as other.
+    """
+
+    duration_ms: float
+    """Wall-clock duration from solve start to terminal outcome."""
+
+    status: Literal["success", "failure", "timeout", "abandoned"]
+    """Terminal outcome.
+
+    success: solver returned a usable solution. failure: solver returned an error
+    (see error_code). timeout: solver did not return within the caller's wait
+    budget. abandoned: caller cancelled or the page navigated away mid-solve.
+    """
+
+    error_code: Optional[str] = None
+    """Solver-specific error code on failure (e.g.
+
+    ERROR_CAPTCHA_UNSOLVABLE). Absent on success.
+    """
+
+    task_id: Optional[str] = None
+    """Solver-assigned identifier. Opaque, useful for support cross-references."""
+
+    website_host: Optional[str] = None
+    """Host of the page where the captcha was solved."""
+
+    website_path: Optional[str] = None
+    """Path of the page where the captcha was solved. Query string excluded."""
+
+
+class BrowserCaptchaSolveResultEvent(BaseModel):
+    """A captcha solve attempt reached a terminal outcome."""
+
+    category: Literal["captcha"]
+
+    source: BrowserEventSource
+    """Provenance metadata identifying which producer emitted the event."""
+
+    ts: int
+    """Event timestamp in Unix microseconds."""
+
+    type: Literal["captcha_solve_result"]
+
+    data: Optional[Data] = None
+
+    truncated: Optional[bool] = None
+    """True if the data field was truncated due to size limits."""

src/kernel/types/browsers/browser_cdp_connect_event.py

@@ -0,0 +1,29 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+from typing_extensions import Literal
+
+from ..._models import BaseModel
+from .browser_event_source import BrowserEventSource
+
+__all__ = ["BrowserCdpConnectEvent"]
+
+
+class BrowserCdpConnectEvent(BaseModel):
+    """An external client (e.g.
+
+    customer SDK, Playwright, Puppeteer) connected to the CDP WebSocket proxy on this VM.
+    """
+
+    category: Literal["connection"]
+
+    source: BrowserEventSource
+    """Provenance metadata identifying which producer emitted the event."""
+
+    ts: int
+    """Event timestamp in Unix microseconds."""
+
+    type: Literal["cdp_connect"]
+
+    truncated: Optional[bool] = None
+    """True if the data field was truncated due to size limits."""

src/kernel/types/browsers/browser_cdp_disconnect_event.py

@@ -0,0 +1,49 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+from typing_extensions import Literal
+
+from ..._models import BaseModel
+from .browser_event_source import BrowserEventSource
+
+__all__ = ["BrowserCdpDisconnectEvent", "Data"]
+
+
+class Data(BaseModel):
+    duration_ms: float
+    """Wall-clock duration of the connection in milliseconds."""
+
+    message_count: int
+    """Number of CDP messages relayed across the connection in either direction."""
+
+    reason: Literal["client_close", "upstream_changed", "upstream_error", "context_cancelled"]
+    """Why the connection ended.
+
+    client_close: the client initiated the close. upstream_changed: Chromium
+    restarted mid-session and the proxy tore down so the client could reconnect
+    against the new upstream. upstream_error: upstream dial or message pump errored.
+    context_cancelled: the request context was cancelled (typically server
+    shutdown).
+    """
+
+
+class BrowserCdpDisconnectEvent(BaseModel):
+    """An external client disconnected from the CDP WebSocket proxy on this VM.
+
+    Pair with the immediately preceding cdp_connect on the same stream.
+    """
+
+    category: Literal["connection"]
+
+    source: BrowserEventSource
+    """Provenance metadata identifying which producer emitted the event."""
+
+    ts: int
+    """Event timestamp in Unix microseconds."""
+
+    type: Literal["cdp_disconnect"]
+
+    data: Optional[Data] = None
+
+    truncated: Optional[bool] = None
+    """True if the data field was truncated due to size limits."""

src/kernel/types/browsers/browser_live_view_connect_event.py

@@ -0,0 +1,40 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+from typing_extensions import Literal
+
+from ..._models import BaseModel
+from .browser_event_source import BrowserEventSource
+
+__all__ = ["BrowserLiveViewConnectEvent", "Data"]
+
+
+class Data(BaseModel):
+    session_id: str
+    """Live view session identifier.
+
+    Stable across reconnects, so a transient network blip can emit two events with
+    the same session_id.
+    """
+
+
+class BrowserLiveViewConnectEvent(BaseModel):
+    """A live view client connected to the headful browser's WebRTC server.
+
+    Headful only; not emitted for headless images.
+    """
+
+    category: Literal["connection"]
+
+    source: BrowserEventSource
+    """Provenance metadata identifying which producer emitted the event."""
+
+    ts: int
+    """Event timestamp in Unix microseconds."""
+
+    type: Literal["live_view_connect"]
+
+    data: Optional[Data] = None
+
+    truncated: Optional[bool] = None
+    """True if the data field was truncated due to size limits."""