feat: Add Kernel wallets backed by VGS agentic network tokens, with hosted card capture

Stainless-Generated-From: 1b0aa5849d3ee8fe7ca69bec3d598286918fc571

Author: kernel-internal[bot]

api.md

@@ -572,9 +572,13 @@ from kernel.types.vaults import (
     CredentialVaultItemUpdateRequest,
     FillVaultItemOperationRequest,
     FillVaultItemOperationResult,
+    KernelCardState,
+    KernelCardVaultItemSpec,
     KernelCredentialVaultItemSpec,
     KernelCredentialVaultItemSpecInput,
     KernelCredentialVaultItemState,
+    KernelWalletState,
+    KernelWalletVaultItemSpec,
     OnePasswordCredentialAccountSpec,
     OnePasswordCredentialAccountState,
     OnePasswordCredentialVaultItemSpec,

src/kernel/resources/vaults/items.py

@@ -309,10 +309,13 @@ def delete(
     ) -> None:
         """
         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.
+        child cards of a wallet. Deleting a connected Kernel wallet first blocks new
+        payments on it, then removes its enrolled card. If that fails, the wallet is
+        kept and keeps refusing payments; retry the deletion. 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
@@ -1483,10 +1486,13 @@ async def delete(
     ) -> None:
         """
         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.
+        child cards of a wallet. Deleting a connected Kernel wallet first blocks new
+        payments on it, then removes its enrolled card. If that fails, the wallet is
+        kept and keeps refusing payments; retry the deletion. 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

src/kernel/resources/vaults/vaults.py

@@ -147,9 +147,11 @@ def delete(
     ) -> None:
         """Unresolved payment operations block deletion.
 
-        Reconcile the original attempt
-        with the provider or support first; deleting or recreating an item is not proof
-        that a payment did not occur.
+        Deleting a connected Kernel wallet
+        first blocks new payments on it, then removes its enrolled card. If that fails,
+        the wallet is kept and keeps refusing payments; retry the deletion. Reconcile
+        the original attempt with the provider or support first; deleting or recreating
+        an item is not proof that a payment did not occur.
 
         Args:
           extra_headers: Send extra headers
@@ -325,9 +327,11 @@ async def delete(
     ) -> None:
         """Unresolved payment operations block deletion.
 
-        Reconcile the original attempt
-        with the provider or support first; deleting or recreating an item is not proof
-        that a payment did not occur.
+        Deleting a connected Kernel wallet
+        first blocks new payments on it, then removes its enrolled card. If that fails,
+        the wallet is kept and keeps refusing payments; retry the deletion. Reconcile
+        the original attempt with the provider or support first; deleting or recreating
+        an item is not proof that a payment did not occur.
 
         Args:
           extra_headers: Send extra headers

src/kernel/types/vaults/__init__.py

@@ -4,12 +4,14 @@
 
 from .vault_item import VaultItem as VaultItem
 from .vault_item_event import VaultItemEvent as VaultItemEvent
+from .kernel_card_state import KernelCardState as KernelCardState
 from .vault_item_action import VaultItemAction as VaultItemAction
 from .item_events_params import ItemEventsParams as ItemEventsParams
 from .item_list_response import ItemListResponse as ItemListResponse
 from .item_update_params import ItemUpdateParams as ItemUpdateParams
 from .item_upsert_params import ItemUpsertParams as ItemUpsertParams
 from .vault_card_aliases import VaultCardAliases as VaultCardAliases
+from .kernel_wallet_state import KernelWalletState as KernelWalletState
 from .card_vault_item_spec import CardVaultItemSpec as CardVaultItemSpec
 from .item_events_response import ItemEventsResponse as ItemEventsResponse
 from .item_retrieve_params import ItemRetrieveParams as ItemRetrieveParams
@@ -26,22 +28,26 @@
 from .vault_webmcp_binding_param import VaultWebmcpBindingParam as VaultWebmcpBindingParam
 from .credential_vault_field_type import CredentialVaultFieldType as CredentialVaultFieldType
 from .credential_vault_item_state import CredentialVaultItemState as CredentialVaultItemState
+from .kernel_card_vault_item_spec import KernelCardVaultItemSpec as KernelCardVaultItemSpec
 from .agentcard_prepared_processor import AgentcardPreparedProcessor as AgentcardPreparedProcessor
 from .credential_collection_action import CredentialCollectionAction as CredentialCollectionAction
 from .credential_vault_field_state import CredentialVaultFieldState as CredentialVaultFieldState
 from .vault_checkout_context_param import VaultCheckoutContextParam as VaultCheckoutContextParam
 from .credential_account_vault_item import CredentialAccountVaultItem as CredentialAccountVaultItem
 from .item_perform_operation_params import ItemPerformOperationParams as ItemPerformOperationParams
+from .kernel_wallet_vault_item_spec import KernelWalletVaultItemSpec as KernelWalletVaultItemSpec
 from .vault_item_operation_response import VaultItemOperationResponse as VaultItemOperationResponse
 from .agentcard_checkout_preparation import AgentcardCheckoutPreparation as AgentcardCheckoutPreparation
 from .agentcard_checkout_authorization import AgentcardCheckoutAuthorization as AgentcardCheckoutAuthorization
 from .fill_vault_item_operation_result import FillVaultItemOperationResult as FillVaultItemOperationResult
 from .credential_vault_field_definition import CredentialVaultFieldDefinition as CredentialVaultFieldDefinition
+from .kernel_card_vault_item_spec_param import KernelCardVaultItemSpecParam as KernelCardVaultItemSpecParam
 from .kernel_credential_vault_item_spec import KernelCredentialVaultItemSpec as KernelCredentialVaultItemSpec
 from .credential_vault_field_input_param import CredentialVaultFieldInputParam as CredentialVaultFieldInputParam
 from .kernel_credential_vault_item_state import KernelCredentialVaultItemState as KernelCredentialVaultItemState
 from .credential_vault_field_update_param import CredentialVaultFieldUpdateParam as CredentialVaultFieldUpdateParam
 from .credential_vault_item_request_param import CredentialVaultItemRequestParam as CredentialVaultItemRequestParam
+from .kernel_wallet_vault_item_spec_param import KernelWalletVaultItemSpecParam as KernelWalletVaultItemSpecParam
 from .one_password_credential_account_spec import OnePasswordCredentialAccountSpec as OnePasswordCredentialAccountSpec
 from .one_password_credential_account_state import (
     OnePasswordCredentialAccountState as OnePasswordCredentialAccountState,

src/kernel/types/vaults/authorize_vault_item_operation_request_param.py

@@ -8,7 +8,7 @@
 
 
 class AuthorizeVaultItemOperationRequestParam(TypedDict, total=False):
-    """Authorize a Link card using its existing purchase specification.
+    """Authorize a Link or Kernel card using its existing purchase specification.
 
     Use only after explicit user approval and when the item advertises authorize. Do not automatically retry provider failures or indeterminate outcomes. Checkout context is not accepted.
     """

src/kernel/types/vaults/card_vault_item_spec.py

@@ -5,6 +5,7 @@
 
 from ..._utils import PropertyInfo
 from ..._models import BaseModel
+from .kernel_card_vault_item_spec import KernelCardVaultItemSpec
 
 __all__ = [
     "CardVaultItemSpec",
@@ -133,5 +134,6 @@ class AgentCardCardVaultItemSpec(BaseModel):
 
 
 CardVaultItemSpec: TypeAlias = Annotated[
-    Union[LinkCardVaultItemSpec, AgentCardCardVaultItemSpec], PropertyInfo(discriminator="provider")
+    Union[LinkCardVaultItemSpec, AgentCardCardVaultItemSpec, KernelCardVaultItemSpec],
+    PropertyInfo(discriminator="provider"),
 ]

src/kernel/types/vaults/card_vault_item_spec_param.py

@@ -5,6 +5,8 @@
 from typing import Dict, Union, Iterable
 from typing_extensions import Literal, Required, TypeAlias, TypedDict
 
+from .kernel_card_vault_item_spec_param import KernelCardVaultItemSpecParam
+
 __all__ = [
     "CardVaultItemSpecParam",
     "LinkCardVaultItemSpec",
@@ -131,4 +133,6 @@ class AgentCardCardVaultItemSpec(TypedDict, total=False):
     """
 
 
-CardVaultItemSpecParam: TypeAlias = Union[LinkCardVaultItemSpec, AgentCardCardVaultItemSpec]
+CardVaultItemSpecParam: TypeAlias = Union[
+    LinkCardVaultItemSpec, AgentCardCardVaultItemSpec, KernelCardVaultItemSpecParam
+]

src/kernel/types/vaults/card_vault_item_state.py

@@ -7,6 +7,7 @@
 
 from ..._utils import PropertyInfo
 from ..._models import BaseModel
+from .kernel_card_state import KernelCardState
 from .vault_card_aliases import VaultCardAliases
 from .agentcard_checkout_preparation import AgentcardCheckoutPreparation
 from .agentcard_checkout_authorization import AgentcardCheckoutAuthorization
@@ -19,6 +20,9 @@ class LinkCardStateMasks(BaseModel):
 
     last4: Optional[str] = None
 
+    token_last4: Optional[str] = None
+    """Last four digits of the network token presented to the merchant."""
+
     if TYPE_CHECKING:
         # Some versions of Pydantic <2.8.0 have a bug and don’t allow assigning a
         # value to this field, so for compatibility we avoid doing it at runtime.
@@ -64,6 +68,9 @@ class AgentCardCardStateMasks(BaseModel):
 
     last4: Optional[str] = None
 
+    token_last4: Optional[str] = None
+    """Last four digits of the network token presented to the merchant."""
+
     if TYPE_CHECKING:
         # Some versions of Pydantic <2.8.0 have a bug and don’t allow assigning a
         # value to this field, so for compatibility we avoid doing it at runtime.
@@ -127,5 +134,5 @@ class AgentCardCardState(BaseModel):
 
 
 CardVaultItemState: TypeAlias = Annotated[
-    Union[LinkCardState, AgentCardCardState], PropertyInfo(discriminator="provider")
+    Union[LinkCardState, AgentCardCardState, KernelCardState], PropertyInfo(discriminator="provider")
 ]

src/kernel/types/vaults/fill_vault_item_operation_request_param.py

@@ -12,8 +12,8 @@
 
 class FillVaultItemOperationRequestParam(TypedDict, total=False):
     """
-    Fill selected fields from one ready credential or ready, unexpired Link card
-    into a browser linked to its vault.
+    Fill selected fields from one ready credential or ready, unexpired Link or
+    Kernel card into a browser linked to its vault.
     Only invoke when the item advertises `fill`. Browser and vault must belong
     to the same project. Kernel checks access and allowed destinations before
     filling; providing a page URL does not authorize a destination.
@@ -34,7 +34,7 @@ class FillVaultItemOperationRequestParam(TypedDict, total=False):
     Fill in request order and stop on the first failure. This operation is
     not atomic: previously filled fields are not rolled back. Never submit
     the form or click buttons, though input/change events may trigger site
-    behavior. Link cards use fill for browser checkout and do not expose
+    behavior. Link and Kernel cards use fill for browser checkout and do not expose
     aliases or support egress substitution. Do not automatically retry a
     failed or indeterminate operation.
 

src/kernel/types/vaults/item_upsert_params.py

@@ -6,6 +6,7 @@
 from typing_extensions import Literal, Required, TypeAlias, TypedDict
 
 from .card_vault_item_spec_param import CardVaultItemSpecParam
+from .kernel_wallet_vault_item_spec_param import KernelWalletVaultItemSpecParam
 from .credential_vault_item_spec_input_param import CredentialVaultItemSpecInputParam
 from .one_password_credential_account_spec_param import OnePasswordCredentialAccountSpecParam
 
@@ -176,7 +177,9 @@ class WalletVaultItemRequestSpecAgentCardWalletVaultItemSpec(TypedDict, total=Fa
 
 
 WalletVaultItemRequestSpec: TypeAlias = Union[
-    WalletVaultItemRequestSpecLinkWalletVaultItemRequestSpec, WalletVaultItemRequestSpecAgentCardWalletVaultItemSpec
+    WalletVaultItemRequestSpecLinkWalletVaultItemRequestSpec,
+    WalletVaultItemRequestSpecAgentCardWalletVaultItemSpec,
+    KernelWalletVaultItemSpecParam,
 ]