feat: Support existing-user AgentCard wallet imports

Stainless-Generated-From: 207cf9bd5926ddf327a2b6db9df5a97300e62a59

Author: kernel-internal[bot]

src/kernel/resources/vaults/items.py

@@ -1236,8 +1236,16 @@ def upsert(
               select a customer-owned configuration. Mode (sandbox vs live) is determined by
               the selected credential; there is no per-item test flag. Without user_id,
               creation returns a hosted enrollment action and Kernel polls until the user
-              connects. user_id may only reference a user already enrolled by a wallet in this
-              organization under the same configuration.
+              connects. With a customer-owned provider_config, user_id imports an existing
+              connection after verifying access with the selected credentials in their sandbox
+              or live mode; no hosted enrollment is needed, even if the connected user has no
+              stored cards. With Kernel-managed credentials, user_id may only reference a user
+              already enrolled by a wallet in this organization under the same configuration.
+              The user and configuration bindings cannot be changed after creation. Import
+              validation is read-only and runs before creation: a failed validation leaves no
+              wallet or reserved key, so the user_id can be corrected and retried. Concurrent
+              imports of the same key may both validate, but create at most one wallet and
+              connected event.
 
           extra_headers: Send extra headers
 
@@ -2609,8 +2617,16 @@ async def upsert(
               select a customer-owned configuration. Mode (sandbox vs live) is determined by
               the selected credential; there is no per-item test flag. Without user_id,
               creation returns a hosted enrollment action and Kernel polls until the user
-              connects. user_id may only reference a user already enrolled by a wallet in this
-              organization under the same configuration.
+              connects. With a customer-owned provider_config, user_id imports an existing
+              connection after verifying access with the selected credentials in their sandbox
+              or live mode; no hosted enrollment is needed, even if the connected user has no
+              stored cards. With Kernel-managed credentials, user_id may only reference a user
+              already enrolled by a wallet in this organization under the same configuration.
+              The user and configuration bindings cannot be changed after creation. Import
+              validation is read-only and runs before creation: a failed validation leaves no
+              wallet or reserved key, so the user_id can be corrected and retried. Concurrent
+              imports of the same key may both validate, but create at most one wallet and
+              connected event.
 
           extra_headers: Send extra headers
 

src/kernel/types/vaults/item_upsert_params.py

@@ -40,8 +40,16 @@ class WalletVaultItemRequest(TypedDict, total=False):
     customer-owned configuration. Mode (sandbox vs live) is determined by the
     selected credential; there is no per-item test flag. Without user_id, creation
     returns a hosted enrollment action and Kernel polls until the user connects.
-    user_id may only reference a user already enrolled by a wallet in this
-    organization under the same configuration.
+    With a customer-owned provider_config, user_id imports an existing connection
+    after verifying access with the selected credentials in their sandbox or live
+    mode; no hosted enrollment is needed, even if the connected user has no stored
+    cards. With Kernel-managed credentials, user_id may only reference a user
+    already enrolled by a wallet in this organization under the same configuration.
+    The user and configuration bindings cannot be changed after creation. Import
+    validation is read-only and runs before creation: a failed validation leaves no
+    wallet or reserved key, so the user_id can be corrected and retried. Concurrent
+    imports of the same key may both validate, but create at most one wallet and
+    connected event.
     """
 
     type: Required[Literal["wallet"]]
@@ -162,7 +170,7 @@ class WalletVaultItemRequestSpecAgentCardWalletVaultItemSpecProviderConfig(Typed
 class WalletVaultItemRequestSpecAgentCardWalletVaultItemSpec(TypedDict, total=False):
     """AgentCard wallet.
 
-    Omit provider_config to use Kernel-managed credentials, or select a customer-owned configuration. Mode (sandbox vs live) is determined by the selected credential; there is no per-item test flag. Without user_id, creation returns a hosted enrollment action and Kernel polls until the user connects. user_id may only reference a user already enrolled by a wallet in this organization under the same configuration.
+    Omit provider_config to use Kernel-managed credentials, or select a customer-owned configuration. Mode (sandbox vs live) is determined by the selected credential; there is no per-item test flag. Without user_id, creation returns a hosted enrollment action and Kernel polls until the user connects. With a customer-owned provider_config, user_id imports an existing connection after verifying access with the selected credentials in their sandbox or live mode; no hosted enrollment is needed, even if the connected user has no stored cards. With Kernel-managed credentials, user_id may only reference a user already enrolled by a wallet in this organization under the same configuration. The user and configuration bindings cannot be changed after creation. Import validation is read-only and runs before creation: a failed validation leaves no wallet or reserved key, so the user_id can be corrected and retried. Concurrent imports of the same key may both validate, but create at most one wallet and connected event.
     """
 
     provider: Required[Literal["agentcard"]]

src/kernel/types/vaults/vault_item.py

@@ -86,8 +86,16 @@ class WalletVaultItem(BaseModel):
     customer-owned configuration. Mode (sandbox vs live) is determined by the
     selected credential; there is no per-item test flag. Without user_id, creation
     returns a hosted enrollment action and Kernel polls until the user connects.
-    user_id may only reference a user already enrolled by a wallet in this
-    organization under the same configuration.
+    With a customer-owned provider_config, user_id imports an existing connection
+    after verifying access with the selected credentials in their sandbox or live
+    mode; no hosted enrollment is needed, even if the connected user has no stored
+    cards. With Kernel-managed credentials, user_id may only reference a user
+    already enrolled by a wallet in this organization under the same configuration.
+    The user and configuration bindings cannot be changed after creation. Import
+    validation is read-only and runs before creation: a failed validation leaves no
+    wallet or reserved key, so the user_id can be corrected and retried. Concurrent
+    imports of the same key may both validate, but create at most one wallet and
+    connected event.
     """
 
     state: WalletVaultItemState

src/kernel/types/vaults/vault_item_operation_response.py

@@ -88,8 +88,16 @@ class WalletVaultItem(BaseModel):
     customer-owned configuration. Mode (sandbox vs live) is determined by the
     selected credential; there is no per-item test flag. Without user_id, creation
     returns a hosted enrollment action and Kernel polls until the user connects.
-    user_id may only reference a user already enrolled by a wallet in this
-    organization under the same configuration.
+    With a customer-owned provider_config, user_id imports an existing connection
+    after verifying access with the selected credentials in their sandbox or live
+    mode; no hosted enrollment is needed, even if the connected user has no stored
+    cards. With Kernel-managed credentials, user_id may only reference a user
+    already enrolled by a wallet in this organization under the same configuration.
+    The user and configuration bindings cannot be changed after creation. Import
+    validation is read-only and runs before creation: a failed validation leaves no
+    wallet or reserved key, so the user_id can be corrected and retried. Concurrent
+    imports of the same key may both validate, but create at most one wallet and
+    connected event.
     """
 
     state: WalletVaultItemState

src/kernel/types/vaults/wallet_vault_item_spec.py

@@ -81,7 +81,7 @@ class AgentCardWalletVaultItemSpecProviderConfig(BaseModel):
 class AgentCardWalletVaultItemSpec(BaseModel):
     """AgentCard wallet.
 
-    Omit provider_config to use Kernel-managed credentials, or select a customer-owned configuration. Mode (sandbox vs live) is determined by the selected credential; there is no per-item test flag. Without user_id, creation returns a hosted enrollment action and Kernel polls until the user connects. user_id may only reference a user already enrolled by a wallet in this organization under the same configuration.
+    Omit provider_config to use Kernel-managed credentials, or select a customer-owned configuration. Mode (sandbox vs live) is determined by the selected credential; there is no per-item test flag. Without user_id, creation returns a hosted enrollment action and Kernel polls until the user connects. With a customer-owned provider_config, user_id imports an existing connection after verifying access with the selected credentials in their sandbox or live mode; no hosted enrollment is needed, even if the connected user has no stored cards. With Kernel-managed credentials, user_id may only reference a user already enrolled by a wallet in this organization under the same configuration. The user and configuration bindings cannot be changed after creation. Import validation is read-only and runs before creation: a failed validation leaves no wallet or reserved key, so the user_id can be corrected and retried. Concurrent imports of the same key may both validate, but create at most one wallet and connected event.
     """
 
     provider: Literal["agentcard"]