Merge remote-tracking branch 'origin/main' into stlc/promote-next

Author: kernel-internal[bot]

src/kernel/types/vaults/card_vault_item_spec.py

@@ -96,7 +96,7 @@ class LinkCardVaultItemSpec(BaseModel):
 class AgentCardCardVaultItemSpec(BaseModel):
     """AgentCard reusable live payment card.
 
-    Test-mode card creation is not supported. Each checkout creates an approval-gated authorization for spec.merchant / spec.amount. The card stays ready after each authorization.
+    Test-mode card creation is not supported. Each checkout creates an authorization for spec.merchant / spec.amount that the cardholder approves, unless AgentCard runs it under one of the cardholder's autopilot rules. The card stays ready after each authorization.
     """
 
     amount: int
@@ -119,6 +119,18 @@ class AgentCardCardVaultItemSpec(BaseModel):
     cardholder picks on the approval screen.
     """
 
+    checkout_origin: Optional[str] = None
+    """
+    Origin of the top-level checkout page, such as https://shop.example.com: https,
+    a lowercase host, a port only when it is not 443, and no path. http is accepted
+    only for localhost test pages. Checkouts without a preparation send it to
+    AgentCard, which uses it to match the cardholder's autopilot rules; prepared
+    checkouts send the preparation's merchant_origin instead. Kernel sends the
+    declared value and does not compare it with the page the browser has open.
+    Omitted, those checkouts ask the cardholder to approve. Card updates replace the
+    whole spec, so an update that omits it removes it.
+    """
+
 
 CardVaultItemSpec: TypeAlias = Annotated[
     Union[LinkCardVaultItemSpec, AgentCardCardVaultItemSpec], PropertyInfo(discriminator="provider")

src/kernel/types/vaults/card_vault_item_spec_param.py

@@ -95,7 +95,7 @@ class LinkCardVaultItemSpec(TypedDict, total=False):
 class AgentCardCardVaultItemSpec(TypedDict, total=False):
     """AgentCard reusable live payment card.
 
-    Test-mode card creation is not supported. Each checkout creates an approval-gated authorization for spec.merchant / spec.amount. The card stays ready after each authorization.
+    Test-mode card creation is not supported. Each checkout creates an authorization for spec.merchant / spec.amount that the cardholder approves, unless AgentCard runs it under one of the cardholder's autopilot rules. The card stays ready after each authorization.
     """
 
     amount: Required[int]
@@ -118,5 +118,17 @@ class AgentCardCardVaultItemSpec(TypedDict, total=False):
     cardholder picks on the approval screen.
     """
 
+    checkout_origin: str
+    """
+    Origin of the top-level checkout page, such as https://shop.example.com: https,
+    a lowercase host, a port only when it is not 443, and no path. http is accepted
+    only for localhost test pages. Checkouts without a preparation send it to
+    AgentCard, which uses it to match the cardholder's autopilot rules; prepared
+    checkouts send the preparation's merchant_origin instead. Kernel sends the
+    declared value and does not compare it with the page the browser has open.
+    Omitted, those checkouts ask the cardholder to approve. Card updates replace the
+    whole spec, so an update that omits it removes it.
+    """
+
 
 CardVaultItemSpecParam: TypeAlias = Union[LinkCardVaultItemSpec, AgentCardCardVaultItemSpec]