kernel 0.101.0__tar.gz → 0.102.0__tar.gz

kernel-0.102.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.102.0"
+}

{kernel-0.101.0 → kernel-0.102.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.102.0](https://github.com/kernel/kernel-python-sdk/compare/v0.101.0...v0.102.0) (2026-09-14)
+
+
+### Features
+
+* Accept a workload intent and use it to widen vendor coverage ([39ffff8](https://github.com/kernel/kernel-python-sdk/commit/39ffff82be3987e2220d8d5057d8d2505991a3eb))
+* Add guarded vault card fill operations ([3927c96](https://github.com/kernel/kernel-python-sdk/commit/3927c961789b4427a72c979ee5bb3dbcae1b8c74))
+* Add single-use AgentCard prepare_checkout for Square ([c439359](https://github.com/kernel/kernel-python-sdk/commit/c43935913b8a471421ef8d96c9066c442ec95171))
+* Allow replacing AgentCard cards after unknown creates ([22a8731](https://github.com/kernel/kernel-python-sdk/commit/22a87318e6ac2f1318a295b9d22de5b2306e66b2))
+* Document punctuation key sequences ([e7850fd](https://github.com/kernel/kernel-python-sdk/commit/e7850fd5757934c731373c5cb09b4444a29d7e84))
+* Honor managed auth browser regions ([0fa2fa3](https://github.com/kernel/kernel-python-sdk/commit/0fa2fa34cd72d04a12c6f9afd61d87098d43799b))
+* Reapply vendor guidance recommendations ([dfcc7ec](https://github.com/kernel/kernel-python-sdk/commit/dfcc7ecbaa087a07d11a5b0eb4738b41b8fadd8b))
+* Report proxy-restricted targets from config registry lookup ([c276ebc](https://github.com/kernel/kernel-python-sdk/commit/c276ebc6fd266924894b300b13ff02f30d0c8527))
+
 ## [0.101.0](https://github.com/kernel/kernel-python-sdk/compare/v0.100.0...v0.101.0) (2026-09-11)
 
 

{kernel-0.101.0 → kernel-0.102.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: kernel
-Version: 0.101.0
+Version: 0.102.0
 Summary: The official Python library for the kernel API
 Project-URL: Homepage, https://github.com/kernel/kernel-python-sdk
 Project-URL: Repository, https://github.com/kernel/kernel-python-sdk

{kernel-0.101.0 → kernel-0.102.0}/api.md

@@ -525,12 +525,21 @@ Types:
 ```python
 from kernel.types.vaults import (
     AgentcardCheckoutAuthorization,
+    AgentcardCheckoutPreparation,
+    AuthorizeVaultItemOperationRequest,
     CardVaultItemSpec,
     CardVaultItemState,
+    FillVaultItemOperationRequest,
+    FillVaultItemOperationResult,
+    PrepareCheckoutVaultItemOperationRequest,
     VaultCardAliases,
+    VaultCardFillField,
+    VaultCheckoutContext,
+    VaultFillFieldResult,
     VaultItem,
     VaultItemAction,
     VaultItemEvent,
+    VaultItemOperationResponse,
     VaultPaymentMethod,
     WalletVaultItemSpec,
     WalletVaultItemState,
@@ -546,7 +555,7 @@ Methods:
 - <code title="get /vaults/{id_or_name}/items">client.vaults.items.<a href="./src/kernel/resources/vaults/items.py">list</a>(id_or_name) -> <a href="./src/kernel/types/vaults/item_list_response.py">ItemListResponse</a></code>
 - <code title="delete /vaults/{id_or_name}/items/{key}">client.vaults.items.<a href="./src/kernel/resources/vaults/items.py">delete</a>(key, \*, id_or_name) -> None</code>
 - <code title="get /vaults/{id_or_name}/items/{key}/events">client.vaults.items.<a href="./src/kernel/resources/vaults/items.py">events</a>(key, \*, id_or_name, \*\*<a href="src/kernel/types/vaults/item_events_params.py">params</a>) -> <a href="./src/kernel/types/vaults/item_events_response.py">ItemEventsResponse</a></code>
-- <code title="post /vaults/{id_or_name}/items/{key}/operations">client.vaults.items.<a href="./src/kernel/resources/vaults/items.py">perform_operation</a>(key, \*, id_or_name, \*\*<a href="src/kernel/types/vaults/item_perform_operation_params.py">params</a>) -> <a href="./src/kernel/types/vaults/vault_item.py">VaultItem</a></code>
+- <code title="post /vaults/{id_or_name}/items/{key}/operations">client.vaults.items.<a href="./src/kernel/resources/vaults/items.py">perform_operation</a>(key, \*, id_or_name, \*\*<a href="src/kernel/types/vaults/item_perform_operation_params.py">params</a>) -> <a href="./src/kernel/types/vaults/vault_item_operation_response.py">VaultItemOperationResponse</a></code>
 - <code title="put /vaults/{id_or_name}/items/{key}">client.vaults.items.<a href="./src/kernel/resources/vaults/items.py">upsert</a>(key, \*, id_or_name, \*\*<a href="src/kernel/types/vaults/item_upsert_params.py">params</a>) -> <a href="./src/kernel/types/vaults/vault_item.py">VaultItem</a></code>
 
 # Credentials

{kernel-0.101.0 → kernel-0.102.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kernel"
-version = "0.101.0"
+version = "0.102.0"
 description = "The official Python library for the kernel API"
 dynamic = ["readme"]
 license = "Apache-2.0"

{kernel-0.101.0 → kernel-0.102.0}/src/kernel/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "kernel"
-__version__ = "0.101.0"  # x-release-please-version
+__version__ = "0.102.0"  # x-release-please-version

{kernel-0.101.0 → kernel-0.102.0}/src/kernel/resources/browsers/computer.py

@@ -397,7 +397,9 @@ class ComputerResource(SyncAPIResource):
           keys: List of key symbols to press. Each item should be a key symbol supported by
               xdotool (see X11 keysym definitions). Examples include "Return", "Shift",
               "Ctrl", "Alt", "F5". Items in this list could also be combinations, e.g.
-              "Ctrl+t" or "Ctrl+Shift+Tab".
+              "Ctrl+t" or "Ctrl+Shift+Tab". Use X11 names for punctuation in combinations,
+              such as "Ctrl+minus" or "Ctrl+plus". A literal hyphen is also accepted as an
+              alias, so "Ctrl+-" is normalized to "Ctrl+minus".
 
           duration: Duration to hold the keys down in milliseconds. If omitted or 0, keys are
               tapped.
@@ -1002,7 +1004,9 @@ class AsyncComputerResource(AsyncAPIResource):
           keys: List of key symbols to press. Each item should be a key symbol supported by
               xdotool (see X11 keysym definitions). Examples include "Return", "Shift",
               "Ctrl", "Alt", "F5". Items in this list could also be combinations, e.g.
-              "Ctrl+t" or "Ctrl+Shift+Tab".
+              "Ctrl+t" or "Ctrl+Shift+Tab". Use X11 names for punctuation in combinations,
+              such as "Ctrl+minus" or "Ctrl+plus". A literal hyphen is also accepted as an
+              alias, so "Ctrl+-" is normalized to "Ctrl+minus".
 
           duration: Duration to hold the keys down in milliseconds. If omitted or 0, keys are
               tapped.

{kernel-0.101.0 → kernel-0.102.0}/src/kernel/resources/config_registry/config_registry.py

@@ -165,6 +165,7 @@ class ConfigRegistryResource(SyncAPIResource):
         *,
         url: str,
         allowed_proxy_countries: SequenceNotStr[str] | Omit = omit,
+        intent: str | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -184,6 +185,14 @@ class ConfigRegistryResource(SyncAPIResource):
               configuration. Kernel may test a subset of allowed countries. When omitted,
               Kernel uses its default country selection.
 
+          intent: Plain-language description of the workload you intend to run against this
+              target, in a sentence or two. Requires an https target, because the pass treats
+              any non-HTTPS destination as off-site and will not drive an http one. Kernel
+              uses it to drive the browser further into the site, where it can observe
+              protections that only appear once a session interacts. When this target already
+              has a verified configuration, the run confirms that one instead of re-deriving
+              the whole matrix, so supplying an intent narrows what can be recommended.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -198,6 +207,7 @@ class ConfigRegistryResource(SyncAPIResource):
                 {
                     "url": url,
                     "allowed_proxy_countries": allowed_proxy_countries,
+                    "intent": intent,
                 },
                 config_registry_resolve_params.ConfigRegistryResolveParams,
             ),
@@ -339,6 +349,7 @@ class AsyncConfigRegistryResource(AsyncAPIResource):
         *,
         url: str,
         allowed_proxy_countries: SequenceNotStr[str] | Omit = omit,
+        intent: str | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -358,6 +369,14 @@ class AsyncConfigRegistryResource(AsyncAPIResource):
               configuration. Kernel may test a subset of allowed countries. When omitted,
               Kernel uses its default country selection.
 
+          intent: Plain-language description of the workload you intend to run against this
+              target, in a sentence or two. Requires an https target, because the pass treats
+              any non-HTTPS destination as off-site and will not drive an http one. Kernel
+              uses it to drive the browser further into the site, where it can observe
+              protections that only appear once a session interacts. When this target already
+              has a verified configuration, the run confirms that one instead of re-deriving
+              the whole matrix, so supplying an intent narrows what can be recommended.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -372,6 +391,7 @@ class AsyncConfigRegistryResource(AsyncAPIResource):
                 {
                     "url": url,
                     "allowed_proxy_countries": allowed_proxy_countries,
+                    "intent": intent,
                 },
                 config_registry_resolve_params.ConfigRegistryResolveParams,
             ),

{kernel-0.101.0 → kernel-0.102.0}/src/kernel/resources/vaults/items.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Any, List, cast
+from typing import Any, List, Iterable, cast
 from typing_extensions import Literal, overload
 
 import httpx
@@ -29,6 +29,9 @@ from ...types.vaults.vault_item import VaultItem
 from ...types.vaults.item_list_response import ItemListResponse
 from ...types.vaults.item_events_response import ItemEventsResponse
 from ...types.vaults.card_vault_item_spec_param import CardVaultItemSpecParam
+from ...types.vaults.vault_card_fill_field_param import VaultCardFillFieldParam
+from ...types.vaults.vault_checkout_context_param import VaultCheckoutContextParam
+from ...types.vaults.vault_item_operation_response import VaultItemOperationResponse
 
 __all__ = ["ItemsResource", "AsyncItemsResource"]
 
@@ -209,9 +212,11 @@ class ItemsResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> None:
         """
-        Unresolved payment operations block deletion, including operations on child
-        cards of a wallet. Reconcile the original attempt with the provider or support
-        first; deleting or recreating an item is not proof that a payment did not occur.
+        Unresolved payment operations normally block deletion, including operations on
+        child cards of a wallet. An AgentCard card in recovery_required whose checkout
+        create response returned no authorization ID may be explicitly abandoned by
+        deleting that card directly; deleting its wallet or vault remains blocked.
+        Deleting or recreating an item is not proof that a payment did not occur.
 
         Args:
           extra_headers: Send extra headers
@@ -287,6 +292,7 @@ class ItemsResource(SyncAPIResource):
             cast_to=ItemEventsResponse,
         )
 
+    @overload
     def perform_operation(
         self,
         key: str,
@@ -299,17 +305,80 @@ class ItemsResource(SyncAPIResource):
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
-    ) -> VaultItem:
+    ) -> VaultItemOperationResponse:
+        """
+        Retrieve the item first and invoke only an operation listed in
+        `available_operations`, following its natural-language description. Availability
+        is rechecked at execution time; unavailable operations return 409. Authorization
+        and preparation may call an external provider and return updated state. Link
+        cards advertise authorize without checkout context. Eligible unused AgentCard
+        cards advertise prepare_checkout, which requires checkout context and obtains
+        device approval before native Square Pay. Keep the returned approval page open,
+        poll until ready_to_submit, then submit before preparation.expires_at. Unused
+        preparations expire automatically and cannot be reused. If spend-request
+        creation is rate limited, returns HTTP 429 with code
+        `spend_request_rate_limited`; stop and back off before retrying.
+
+        Fill returns a value-free execution result. Validation failures before writing
+        return 400 (invalid request or targets), 403 (access or destination denied), 404
+        (resource not found), or 409 (item or browser not ready). Once writing starts,
+        known partial failures and indeterminate field outcomes return 200 with status
+        `failed` or `unknown`, not an automatic-retry signal. A transport error may
+        leave the outcome unknown; do not automatically retry.
+
+        Args:
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        ...
+
+    @overload
+    def perform_operation(
+        self,
+        key: str,
+        *,
+        id_or_name: str,
+        checkout: VaultCheckoutContextParam,
+        type: Literal["prepare_checkout"],
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> VaultItemOperationResponse:
         """
         Retrieve the item first and invoke only an operation listed in
-        `available_operations`, following its natural-language description. Operations
-        may call an external provider and return updated state. Link cards advertise
-        authorize. AgentCard cards are created with PUT and request approval when their
-        aliases are used at checkout; they do not expose this operation. If
-        spend-request creation is rate limited, returns HTTP 429 with code
+        `available_operations`, following its natural-language description. Availability
+        is rechecked at execution time; unavailable operations return 409. Authorization
+        and preparation may call an external provider and return updated state. Link
+        cards advertise authorize without checkout context. Eligible unused AgentCard
+        cards advertise prepare_checkout, which requires checkout context and obtains
+        device approval before native Square Pay. Keep the returned approval page open,
+        poll until ready_to_submit, then submit before preparation.expires_at. Unused
+        preparations expire automatically and cannot be reused. If spend-request
+        creation is rate limited, returns HTTP 429 with code
         `spend_request_rate_limited`; stop and back off before retrying.
 
+        Fill returns a value-free execution result. Validation failures before writing
+        return 400 (invalid request or targets), 403 (access or destination denied), 404
+        (resource not found), or 409 (item or browser not ready). Once writing starts,
+        known partial failures and indeterminate field outcomes return 200 with status
+        `failed` or `unknown`, not an automatic-retry signal. A transport error may
+        leave the outcome unknown; do not automatically retry.
+
         Args:
+          checkout: Required when preparing an unused AgentCard card for Square. Consent is bound to
+              this browser and declared merchant origin, not a tab. Wait for the item's
+              ready_to_submit status before native Pay and submit within its readiness
+              deadline. Unused preparations expire automatically; every preparation is
+              single-use, including after failure or expiry.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -318,19 +387,115 @@ class ItemsResource(SyncAPIResource):
 
           timeout: Override the client-level default timeout for this request, in seconds
         """
+        ...
+
+    @overload
+    def perform_operation(
+        self,
+        key: str,
+        *,
+        id_or_name: str,
+        browser_id: str,
+        fields: Iterable[VaultCardFillFieldParam],
+        page_url: str,
+        type: Literal["fill"],
+        timeout_ms: int | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> VaultItemOperationResponse:
+        """
+        Retrieve the item first and invoke only an operation listed in
+        `available_operations`, following its natural-language description. Availability
+        is rechecked at execution time; unavailable operations return 409. Authorization
+        and preparation may call an external provider and return updated state. Link
+        cards advertise authorize without checkout context. Eligible unused AgentCard
+        cards advertise prepare_checkout, which requires checkout context and obtains
+        device approval before native Square Pay. Keep the returned approval page open,
+        poll until ready_to_submit, then submit before preparation.expires_at. Unused
+        preparations expire automatically and cannot be reused. If spend-request
+        creation is rate limited, returns HTTP 429 with code
+        `spend_request_rate_limited`; stop and back off before retrying.
+
+        Fill returns a value-free execution result. Validation failures before writing
+        return 400 (invalid request or targets), 403 (access or destination denied), 404
+        (resource not found), or 409 (item or browser not ready). Once writing starts,
+        known partial failures and indeterminate field outcomes return 200 with status
+        `failed` or `unknown`, not an automatic-retry signal. A transport error may
+        leave the outcome unknown; do not automatically retry.
+
+        Args:
+          browser_id: Browser session ID, not a reusable browser name.
+
+          fields: Field bindings for this step. No two bindings may resolve to the same element.
+
+          page_url: Exact current top-level page URL, including path, query, and fragment. Must
+              match exactly one open page in the browser; zero or multiple matches fail. No
+              prefix or glob matching. Must use HTTPS without embedded credentials.
+
+          timeout_ms: Total operation deadline in milliseconds, not a per-field timeout.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        ...
+
+    @required_args(
+        ["id_or_name", "type"],
+        ["id_or_name", "checkout", "type"],
+        ["id_or_name", "browser_id", "fields", "page_url", "type"],
+    )
+    def perform_operation(
+        self,
+        key: str,
+        *,
+        id_or_name: str,
+        type: Literal["authorize"] | Literal["prepare_checkout"] | Literal["fill"],
+        checkout: VaultCheckoutContextParam | Omit = omit,
+        browser_id: str | Omit = omit,
+        fields: Iterable[VaultCardFillFieldParam] | Omit = omit,
+        page_url: str | Omit = omit,
+        timeout_ms: int | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> VaultItemOperationResponse:
         if not id_or_name:
             raise ValueError(f"Expected a non-empty value for `id_or_name` but received {id_or_name!r}")
         if not key:
             raise ValueError(f"Expected a non-empty value for `key` but received {key!r}")
         return cast(
-            VaultItem,
+            VaultItemOperationResponse,
             self._post(
                 path_template("/vaults/{id_or_name}/items/{key}/operations", id_or_name=id_or_name, key=key),
-                body=maybe_transform({"type": type}, item_perform_operation_params.ItemPerformOperationParams),
+                body=maybe_transform(
+                    {
+                        "type": type,
+                        "checkout": checkout,
+                        "browser_id": browser_id,
+                        "fields": fields,
+                        "page_url": page_url,
+                        "timeout_ms": timeout_ms,
+                    },
+                    item_perform_operation_params.ItemPerformOperationParams,
+                ),
                 options=make_request_options(
                     extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
                 ),
-                cast_to=cast(Any, VaultItem),  # Union types cannot be passed in as arguments in the type system
+                cast_to=cast(
+                    Any, VaultItemOperationResponse
+                ),  # Union types cannot be passed in as arguments in the type system
             ),
         )
 
@@ -625,9 +790,11 @@ class AsyncItemsResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> None:
         """
-        Unresolved payment operations block deletion, including operations on child
-        cards of a wallet. Reconcile the original attempt with the provider or support
-        first; deleting or recreating an item is not proof that a payment did not occur.
+        Unresolved payment operations normally block deletion, including operations on
+        child cards of a wallet. An AgentCard card in recovery_required whose checkout
+        create response returned no authorization ID may be explicitly abandoned by
+        deleting that card directly; deleting its wallet or vault remains blocked.
+        Deleting or recreating an item is not proof that a payment did not occur.
 
         Args:
           extra_headers: Send extra headers
@@ -703,6 +870,7 @@ class AsyncItemsResource(AsyncAPIResource):
             cast_to=ItemEventsResponse,
         )
 
+    @overload
     async def perform_operation(
         self,
         key: str,
@@ -715,17 +883,80 @@ class AsyncItemsResource(AsyncAPIResource):
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
-    ) -> VaultItem:
+    ) -> VaultItemOperationResponse:
+        """
+        Retrieve the item first and invoke only an operation listed in
+        `available_operations`, following its natural-language description. Availability
+        is rechecked at execution time; unavailable operations return 409. Authorization
+        and preparation may call an external provider and return updated state. Link
+        cards advertise authorize without checkout context. Eligible unused AgentCard
+        cards advertise prepare_checkout, which requires checkout context and obtains
+        device approval before native Square Pay. Keep the returned approval page open,
+        poll until ready_to_submit, then submit before preparation.expires_at. Unused
+        preparations expire automatically and cannot be reused. If spend-request
+        creation is rate limited, returns HTTP 429 with code
+        `spend_request_rate_limited`; stop and back off before retrying.
+
+        Fill returns a value-free execution result. Validation failures before writing
+        return 400 (invalid request or targets), 403 (access or destination denied), 404
+        (resource not found), or 409 (item or browser not ready). Once writing starts,
+        known partial failures and indeterminate field outcomes return 200 with status
+        `failed` or `unknown`, not an automatic-retry signal. A transport error may
+        leave the outcome unknown; do not automatically retry.
+
+        Args:
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        ...
+
+    @overload
+    async def perform_operation(
+        self,
+        key: str,
+        *,
+        id_or_name: str,
+        checkout: VaultCheckoutContextParam,
+        type: Literal["prepare_checkout"],
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> VaultItemOperationResponse:
         """
         Retrieve the item first and invoke only an operation listed in
-        `available_operations`, following its natural-language description. Operations
-        may call an external provider and return updated state. Link cards advertise
-        authorize. AgentCard cards are created with PUT and request approval when their
-        aliases are used at checkout; they do not expose this operation. If
-        spend-request creation is rate limited, returns HTTP 429 with code
+        `available_operations`, following its natural-language description. Availability
+        is rechecked at execution time; unavailable operations return 409. Authorization
+        and preparation may call an external provider and return updated state. Link
+        cards advertise authorize without checkout context. Eligible unused AgentCard
+        cards advertise prepare_checkout, which requires checkout context and obtains
+        device approval before native Square Pay. Keep the returned approval page open,
+        poll until ready_to_submit, then submit before preparation.expires_at. Unused
+        preparations expire automatically and cannot be reused. If spend-request
+        creation is rate limited, returns HTTP 429 with code
         `spend_request_rate_limited`; stop and back off before retrying.
 
+        Fill returns a value-free execution result. Validation failures before writing
+        return 400 (invalid request or targets), 403 (access or destination denied), 404
+        (resource not found), or 409 (item or browser not ready). Once writing starts,
+        known partial failures and indeterminate field outcomes return 200 with status
+        `failed` or `unknown`, not an automatic-retry signal. A transport error may
+        leave the outcome unknown; do not automatically retry.
+
         Args:
+          checkout: Required when preparing an unused AgentCard card for Square. Consent is bound to
+              this browser and declared merchant origin, not a tab. Wait for the item's
+              ready_to_submit status before native Pay and submit within its readiness
+              deadline. Unused preparations expire automatically; every preparation is
+              single-use, including after failure or expiry.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -734,21 +965,115 @@ class AsyncItemsResource(AsyncAPIResource):
 
           timeout: Override the client-level default timeout for this request, in seconds
         """
+        ...
+
+    @overload
+    async def perform_operation(
+        self,
+        key: str,
+        *,
+        id_or_name: str,
+        browser_id: str,
+        fields: Iterable[VaultCardFillFieldParam],
+        page_url: str,
+        type: Literal["fill"],
+        timeout_ms: int | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> VaultItemOperationResponse:
+        """
+        Retrieve the item first and invoke only an operation listed in
+        `available_operations`, following its natural-language description. Availability
+        is rechecked at execution time; unavailable operations return 409. Authorization
+        and preparation may call an external provider and return updated state. Link
+        cards advertise authorize without checkout context. Eligible unused AgentCard
+        cards advertise prepare_checkout, which requires checkout context and obtains
+        device approval before native Square Pay. Keep the returned approval page open,
+        poll until ready_to_submit, then submit before preparation.expires_at. Unused
+        preparations expire automatically and cannot be reused. If spend-request
+        creation is rate limited, returns HTTP 429 with code
+        `spend_request_rate_limited`; stop and back off before retrying.
+
+        Fill returns a value-free execution result. Validation failures before writing
+        return 400 (invalid request or targets), 403 (access or destination denied), 404
+        (resource not found), or 409 (item or browser not ready). Once writing starts,
+        known partial failures and indeterminate field outcomes return 200 with status
+        `failed` or `unknown`, not an automatic-retry signal. A transport error may
+        leave the outcome unknown; do not automatically retry.
+
+        Args:
+          browser_id: Browser session ID, not a reusable browser name.
+
+          fields: Field bindings for this step. No two bindings may resolve to the same element.
+
+          page_url: Exact current top-level page URL, including path, query, and fragment. Must
+              match exactly one open page in the browser; zero or multiple matches fail. No
+              prefix or glob matching. Must use HTTPS without embedded credentials.
+
+          timeout_ms: Total operation deadline in milliseconds, not a per-field timeout.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        ...
+
+    @required_args(
+        ["id_or_name", "type"],
+        ["id_or_name", "checkout", "type"],
+        ["id_or_name", "browser_id", "fields", "page_url", "type"],
+    )
+    async def perform_operation(
+        self,
+        key: str,
+        *,
+        id_or_name: str,
+        type: Literal["authorize"] | Literal["prepare_checkout"] | Literal["fill"],
+        checkout: VaultCheckoutContextParam | Omit = omit,
+        browser_id: str | Omit = omit,
+        fields: Iterable[VaultCardFillFieldParam] | Omit = omit,
+        page_url: str | Omit = omit,
+        timeout_ms: int | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> VaultItemOperationResponse:
         if not id_or_name:
             raise ValueError(f"Expected a non-empty value for `id_or_name` but received {id_or_name!r}")
         if not key:
             raise ValueError(f"Expected a non-empty value for `key` but received {key!r}")
         return cast(
-            VaultItem,
+            VaultItemOperationResponse,
             await self._post(
                 path_template("/vaults/{id_or_name}/items/{key}/operations", id_or_name=id_or_name, key=key),
                 body=await async_maybe_transform(
-                    {"type": type}, item_perform_operation_params.ItemPerformOperationParams
+                    {
+                        "type": type,
+                        "checkout": checkout,
+                        "browser_id": browser_id,
+                        "fields": fields,
+                        "page_url": page_url,
+                        "timeout_ms": timeout_ms,
+                    },
+                    item_perform_operation_params.ItemPerformOperationParams,
                 ),
                 options=make_request_options(
                     extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
                 ),
-                cast_to=cast(Any, VaultItem),  # Union types cannot be passed in as arguments in the type system
+                cast_to=cast(
+                    Any, VaultItemOperationResponse
+                ),  # Union types cannot be passed in as arguments in the type system
             ),
         )