feat: Deliver Kernel card details through fill

Stainless-Generated-From: 9e1188cd7d4ff2411cf480d9989938bb90840560

Author: kernel-internal[bot]

src/kernel/resources/vaults/items.py

@@ -434,6 +434,9 @@ def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -487,6 +490,9 @@ def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -542,6 +548,9 @@ def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -596,6 +605,9 @@ def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -645,6 +657,9 @@ def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -703,6 +718,9 @@ def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -772,6 +790,9 @@ def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -821,6 +842,9 @@ def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -873,6 +897,9 @@ def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -929,6 +956,9 @@ def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -979,6 +1009,9 @@ def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -1035,6 +1068,9 @@ def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -1770,6 +1806,9 @@ async def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -1823,6 +1862,9 @@ async def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -1878,6 +1920,9 @@ async def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -1932,6 +1977,9 @@ async def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -1981,6 +2029,9 @@ async def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -2039,6 +2090,9 @@ async def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -2108,6 +2162,9 @@ async def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -2157,6 +2214,9 @@ async def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -2209,6 +2269,9 @@ async def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -2265,6 +2328,9 @@ async def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -2315,6 +2381,9 @@ async def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,
@@ -2371,6 +2440,9 @@ async def perform_operation(
         return HTTP 429 and retain the card item; stop, back off, and retry the same
         authorize operation.
 
+        Ready Kernel cards advertise fill. Fill delivers card details for a few minutes;
+        submit checkout promptly after filling. A repeated fill is safe.
+
         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,

src/kernel/types/vaults/kernel_card_state.py

@@ -32,8 +32,9 @@ def __getattr__(self, attr: str) -> str: ...
 
 
 class KernelCardState(BaseModel):
-    """
-    A ready Kernel card retains its encrypted network token and one-time code for the fill operation until the item's expires_at. Fill and submit checkout before then. Visa purchases require a spend_approval action before the code is issued; Mastercard purchases need no hosted approval. masks.last4 is the enrolled card's last four digits; masks.token_last4 is the network token's last four digits shown to the merchant. Kernel cards do not expose aliases or support egress substitution. Kernel does not observe whether the merchant charged the card.
+    """A ready Kernel card supports authorize, fill, then submit checkout.
+
+    Card details are delivered for a few minutes after fill; submit promptly. Repeated fill is safe and never submits checkout. Visa purchases require a spend_approval action before details are issued; Mastercard purchases need no hosted approval. masks.last4 is the enrolled card's last four digits; masks.token_last4, when present, is the token's last four digits shown to the merchant. Kernel does not observe whether the merchant charged the card.
     """
 
     provider: Literal["kernel"]

src/kernel/types/vaults/kernel_card_vault_item_spec.py

@@ -11,7 +11,7 @@
 class KernelCardVaultItemSpec(BaseModel):
     """One live purchase with a Kernel-enrolled card.
 
-    Authorization obtains an agentic network token number, expiry and one-time 3-digit code. They are stored encrypted for the fill operation, which types them only on merchant_url's origin; the merchant's own checkout submits the payment. The one-time code is valid until the item's expires_at; fill and submit checkout before then. Mastercard purchases need no cardholder approval. A Visa purchase returns a spend_approval action: the cardholder approves it with a Visa passkey, and Kernel registers a Visa intent for one transaction up to the amount before issuing the code. Card updates are not supported; delete and create a new item instead.
+    Authorization obtains an agentic network token number, expiry and one-time 3-digit code. They are stored encrypted for the fill operation, which types them only on merchant_url's origin; the merchant's own checkout submits the payment. The one-time code is valid until the item's expires_at; fill and submit checkout before then. Mastercard purchases need no cardholder approval. A Visa purchase returns a spend_approval action: the cardholder approves it with a Visa passkey, and Kernel registers a Visa intent for one transaction up to the amount before issuing the code. For supported cards whose network cannot be enrolled for agentic tokens, authorize prepares checkout details without issuing a one-time code. The card can be filled into one checkout before its expires_at, one hour after authorization. Fill types those details on merchant_url's origin. The amount, merchant_url and merchant_country are recorded but do not restrict payment requests sent by the browser. Card updates are not supported; delete and create a new item instead.
     """
 
     amount: int

src/kernel/types/vaults/kernel_card_vault_item_spec_param.py

@@ -10,7 +10,7 @@
 class KernelCardVaultItemSpecParam(TypedDict, total=False):
     """One live purchase with a Kernel-enrolled card.
 
-    Authorization obtains an agentic network token number, expiry and one-time 3-digit code. They are stored encrypted for the fill operation, which types them only on merchant_url's origin; the merchant's own checkout submits the payment. The one-time code is valid until the item's expires_at; fill and submit checkout before then. Mastercard purchases need no cardholder approval. A Visa purchase returns a spend_approval action: the cardholder approves it with a Visa passkey, and Kernel registers a Visa intent for one transaction up to the amount before issuing the code. Card updates are not supported; delete and create a new item instead.
+    Authorization obtains an agentic network token number, expiry and one-time 3-digit code. They are stored encrypted for the fill operation, which types them only on merchant_url's origin; the merchant's own checkout submits the payment. The one-time code is valid until the item's expires_at; fill and submit checkout before then. Mastercard purchases need no cardholder approval. A Visa purchase returns a spend_approval action: the cardholder approves it with a Visa passkey, and Kernel registers a Visa intent for one transaction up to the amount before issuing the code. For supported cards whose network cannot be enrolled for agentic tokens, authorize prepares checkout details without issuing a one-time code. The card can be filled into one checkout before its expires_at, one hour after authorization. Fill types those details on merchant_url's origin. The amount, merchant_url and merchant_country are recorded but do not restrict payment requests sent by the browser. Card updates are not supported; delete and create a new item instead.
     """
 
     amount: Required[int]