feat: Fence browser allowlist updates with revision checks

Stainless-Generated-From: 98e3c1efbf1a574ca1fd596e616e5a0dd857b703

Author: kernel-internal[bot]

api.md

@@ -117,6 +117,7 @@ Types:
 
 ```python
 from kernel.types import (
+    BrowserAllowlistState,
     BrowserMemory,
     BrowserMemoryRequest,
     BrowserNetworkConfig,

src/kernel/types/__init__.py

@@ -98,6 +98,7 @@
 from .invocation_state_event import InvocationStateEvent as InvocationStateEvent
 from .recommendation_summary import RecommendationSummary as RecommendationSummary
 from .api_key_retrieve_params import APIKeyRetrieveParams as APIKeyRetrieveParams
+from .browser_allowlist_state import BrowserAllowlistState as BrowserAllowlistState
 from .browser_create_response import BrowserCreateResponse as BrowserCreateResponse
 from .browser_retrieve_params import BrowserRetrieveParams as BrowserRetrieveParams
 from .browser_update_response import BrowserUpdateResponse as BrowserUpdateResponse
@@ -138,6 +139,7 @@
 from .deployment_retrieve_response import DeploymentRetrieveResponse as DeploymentRetrieveResponse
 from .invocation_retrieve_response import InvocationRetrieveResponse as InvocationRetrieveResponse
 from .audit_log_export_chunk_params import AuditLogExportChunkParams as AuditLogExportChunkParams
+from .browser_allowlist_state_param import BrowserAllowlistStateParam as BrowserAllowlistStateParam
 from .browser_pool_acquire_response import BrowserPoolAcquireResponse as BrowserPoolAcquireResponse
 from .config_registry_lookup_params import ConfigRegistryLookupParams as ConfigRegistryLookupParams
 from .credential_totp_code_response import CredentialTotpCodeResponse as CredentialTotpCodeResponse

src/kernel/types/browser_allowlist_state.py

@@ -0,0 +1,21 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+
+from .._models import BaseModel
+
+__all__ = ["BrowserAllowlistState"]
+
+
+class BrowserAllowlistState(BaseModel):
+    revision: str
+    """Opaque revision to pass as network.expected_allowlist_revision on an update."""
+
+    base_revision: Optional[str] = None
+    """
+    Revision against which that mutation was accepted; reuse it when retrying the
+    mutation.
+    """
+
+    mutation_id: Optional[str] = None
+    """ID of the last conditional allowlist update saved on this browser."""

src/kernel/types/browser_allowlist_state_param.py

@@ -0,0 +1,21 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import Required, TypedDict
+
+__all__ = ["BrowserAllowlistStateParam"]
+
+
+class BrowserAllowlistStateParam(TypedDict, total=False):
+    revision: Required[str]
+    """Opaque revision to pass as network.expected_allowlist_revision on an update."""
+
+    base_revision: str
+    """
+    Revision against which that mutation was accepted; reuse it when retrying the
+    mutation.
+    """
+
+    mutation_id: str
+    """ID of the last conditional allowlist update saved on this browser."""

src/kernel/types/browser_network_config.py

@@ -3,6 +3,7 @@
 from typing import List, Optional
 
 from .._models import BaseModel
+from .browser_allowlist_state import BrowserAllowlistState
 
 __all__ = ["BrowserNetworkConfig", "ProxyRoute", "ProxyRouteProxy"]
 
@@ -58,6 +59,14 @@ class BrowserNetworkConfig(BaseModel):
     replaced on release rather than given an allowlist again. Requires proxy v3.
     """
 
+    allowlist_state: Optional[BrowserAllowlistState] = None
+    """Concurrency metadata for a browser's saved allowlist configuration.
+
+    Browser pools omit it. This remains present after removal so an uncertain
+    removal can be retried. It does not prove proxy or VM application completed. Do
+    not include it in creation or pool updates.
+    """
+
     private_hosts: Optional[List[str]] = None
     """
     Destinations the browser reaches directly through the session's own network

src/kernel/types/browser_network_update_param.py

@@ -34,3 +34,22 @@ class BrowserNetworkUpdateParam(TypedDict, total=False):
     safely restored. If the request fails, retry it: the new list may already apply
     to some requests.
     """
+
+    expected_allowlist_revision: str
+    """The network.allowlist_state.revision from the browser's last saved snapshot.
+
+    Supply together with mutation_id to opt into conditional allowlist updates. The
+    revision is checked atomically with the configuration write. A stale request
+    returns 409 stale_network without changing the allowlist. A GET alone does not
+    fence an earlier unfinished PATCH.
+    """
+
+    mutation_id: str
+    """
+    A unique ID for this allowlist update, supplied together with
+    expected_allowlist_revision. Reuse both values and the identical allowed_hosts
+    payload when retrying an uncertain update. If it is still the current mutation,
+    the retry finishes proxy and VM application without creating another revision. A
+    superseded mutation returns 409 stale_network. These fields guard only
+    network.allowed_hosts, not other browser update fields.
+    """

tests/api_resources/test_browsers.py

@@ -211,7 +211,11 @@ def test_method_update_with_all_params(self, client: Kernel) -> None:
             id_or_name="htzv5orfit78e1m2biiifpbv",
             disable_default_proxy=True,
             name="checkout-flow-1",
-            network={"allowed_hosts": ["example.com", "*.example.com"]},
+            network={
+                "allowed_hosts": ["example.com", "*.example.com"],
+                "expected_allowlist_revision": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+                "mutation_id": "mutation_id",
+            },
             profile={
                 "id": "id",
                 "name": "name",
@@ -758,7 +762,11 @@ async def test_method_update_with_all_params(self, async_client: AsyncKernel) ->
             id_or_name="htzv5orfit78e1m2biiifpbv",
             disable_default_proxy=True,
             name="checkout-flow-1",
-            network={"allowed_hosts": ["example.com", "*.example.com"]},
+            network={
+                "allowed_hosts": ["example.com", "*.example.com"],
+                "expected_allowlist_revision": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+                "mutation_id": "mutation_id",
+            },
             profile={
                 "id": "id",
                 "name": "name",