release: 0.126.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.125.0"
+  ".": "0.126.0"
 }

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.126.0](https://github.com/kernel/kernel-python-sdk/compare/v0.125.0...v0.126.0) (2026-10-14)
+
+
+### Features
+
+* support Link Pay Tokens when authorizing Link cards at checkout ([f081364](https://github.com/kernel/kernel-python-sdk/commit/f08136407428a84fd709d491d38694db026f70c8))
+
 ## [0.125.0](https://github.com/kernel/kernel-python-sdk/compare/v0.124.0...v0.125.0) (2026-10-13)
 
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kernel"
-version = "0.125.0"
+version = "0.126.0"
 description = "The official Python library for the kernel API"
 dynamic = ["readme"]
 license = "Apache-2.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.125.0"  # x-release-please-version
+__version__ = "0.126.0"  # x-release-please-version

src/kernel/types/vaults/authorize_vault_item_operation_request_param.py

@@ -10,7 +10,16 @@
 class AuthorizeVaultItemOperationRequestParam(TypedDict, total=False):
     """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.
+    Use only after explicit user approval and when the item advertises authorize; follow the advertised operation's description. For a Link card, pass browser_id and page_url together while the browser is on the final checkout page: Kernel inspects that checkout, chooses how the credential is delivered, and limits fill to that checkout's origin in any browser with this vault attached. Omitting both issues a virtual card that fills any page on the merchant origin. Once approval has been requested, browser_id and page_url are ignored and authorize only re-checks the request. Browser and checkout inspection errors occur before any provider request and can be retried once the browser is on the checkout page. Kernel cards do not accept browser_id or page_url.
     """
 
     type: Required[Literal["authorize"]]
+
+    browser_id: str
+    """Browser session ID, not a reusable browser name.
+
+    The browser must have this vault attached.
+    """
+
+    page_url: str
+    """Exact current top-level URL of the final checkout page open in browser_id."""

src/kernel/types/vaults/card_vault_item_spec.py

@@ -57,12 +57,17 @@ class LinkCardVaultItemSpecTotal(BaseModel):
 
 
 class LinkCardVaultItemSpec(BaseModel):
-    """Live payment card. Test-mode card creation is not supported."""
+    """Live Link card request.
+
+    Test-mode card creation is not supported. The spec can be changed with PATCH until the card is authorized at a checkout. Authorize it with the browser at final checkout: Kernel inspects the checkout through WebMCP and internally chooses a merchant-bound Link Pay Token when supported or a virtual card otherwise. Callers never receive or choose how the credential is delivered.
+    """
 
     amount: int
     """Integer amount in minor currency units.
 
-    Link permits at most 50000 per spend request.
+    Link Pay Token execution permits at most 500000; virtual-card execution permits
+    at most 50000. Authorization rejects a larger amount when the checkout requires
+    a virtual card.
     """
 
     context: str
@@ -83,7 +88,7 @@ class LinkCardVaultItemSpec(BaseModel):
     provider: Literal["link"]
 
     wallet: str
-    """Wallet item key used to mint this card."""
+    """Connected Link wallet item key."""
 
     expires_at: Optional[int] = None
 

src/kernel/types/vaults/card_vault_item_spec_param.py

@@ -57,12 +57,17 @@ class LinkCardVaultItemSpecTotal(TypedDict, total=False):
 
 
 class LinkCardVaultItemSpec(TypedDict, total=False):
-    """Live payment card. Test-mode card creation is not supported."""
+    """Live Link card request.
+
+    Test-mode card creation is not supported. The spec can be changed with PATCH until the card is authorized at a checkout. Authorize it with the browser at final checkout: Kernel inspects the checkout through WebMCP and internally chooses a merchant-bound Link Pay Token when supported or a virtual card otherwise. Callers never receive or choose how the credential is delivered.
+    """
 
     amount: Required[int]
     """Integer amount in minor currency units.
 
-    Link permits at most 50000 per spend request.
+    Link Pay Token execution permits at most 500000; virtual-card execution permits
+    at most 50000. Authorization rejects a larger amount when the checkout requires
+    a virtual card.
     """
 
     context: Required[str]
@@ -83,7 +88,7 @@ class LinkCardVaultItemSpec(TypedDict, total=False):
     provider: Required[Literal["link"]]
 
     wallet: Required[str]
-    """Wallet item key used to mint this card."""
+    """Connected Link wallet item key."""
 
     expires_at: int
 

src/kernel/types/vaults/fill_vault_item_operation_request_param.py

@@ -12,33 +12,18 @@
 
 class FillVaultItemOperationRequestParam(TypedDict, total=False):
     """
-    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.
-
-    Find exactly one open page matching `page_url`. Credential items may omit
-    `page_url` to require exactly one open page; cards require an HTTPS page URL.
-    Credentials have no destination allowlist. TOTP fields generate a current
-    code immediately before writing; their seeds never enter the browser. For each selector, search
-    the main frame and all descendant frames for editable inputs or selects
-    matched directly or contained within matching elements. Each selector must
-    resolve to one unique editable element across all frames; zero or multiple
-    candidates fail. Count each element once, even if multiple matching
-    containers contain it. Validate all bindings before filling.
-    Select elements match an option by its value, not its label.
-    If the page navigates or a target disappears during filling, stop rather
-    than selecting a different page or element.
-
-    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 and Kernel cards use fill for browser checkout and do not expose
-    aliases or support egress substitution. Fill does not consume the item, so
-    a failed or indeterminate fill is safe to retry; a retry rewrites the same
-    fields. A retry right after an indeterminate fill may wait up to 15 seconds
-    for the earlier attempt's browser lock to expire.
+    Use a vault item in a browser session, for example to fill a login or
+    payment form. Only invoke when the item advertises `fill`; the advertised
+    operation describes the inputs that item needs. Requires `browser_id` and
+    usually `page_url`; some items also require `fields`. 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.
+
+    Fill never submits forms or clicks buttons, though input and change events
+    may trigger site behavior. It is not atomic: completed steps are not rolled
+    back. Fill does not consume the item, so a failed or indeterminate fill is
+    safe to retry. A retry right after an indeterminate fill may wait up to 15
+    seconds for the earlier attempt's browser lock to expire.
 
     Secret values are never returned or included in operation logs, traces,
     audit events, or error details. This does not prevent an agent with
@@ -49,18 +34,26 @@ class FillVaultItemOperationRequestParam(TypedDict, total=False):
     browser_id: Required[str]
     """Browser session ID, not a reusable browser name."""
 
-    fields: Required[Iterable[VaultFillFieldParam]]
-    """Field bindings for this step. No two bindings may resolve to the same element."""
-
     type: Required[Literal["fill"]]
 
+    fields: Iterable[VaultFillFieldParam]
+    """
+    Field bindings, when the item's advertised fill operation requires them. Each
+    selector is searched in the main frame and all descendant frames and must
+    resolve to exactly one editable input or select, matched directly or through a
+    containing element; zero or multiple candidates fail, and no two bindings may
+    resolve to the same element. Select elements match an option by value, not
+    label. All bindings are validated before any write, then filled in request
+    order, stopping at the first failure. If the page navigates or a target
+    disappears, fill stops rather than choosing another page or element.
+    """
+
     page_url: str
     """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. Required for cards, which must use HTTPS without
-    embedded credentials. Optional for credentials, where omission requires exactly
-    one open page.
+    No prefix or glob matching. When an item allows omitting it, the browser must
+    have exactly one open page.
     """
 
     timeout_ms: int

src/kernel/types/vaults/fill_vault_item_operation_result.py

@@ -11,17 +11,18 @@
 
 class FillVaultItemOperationResult(BaseModel):
     fields: List[VaultFillFieldResult]
-    """Exactly one result per request binding, in request order.
-
-    After the first failed or unknown field, all remaining fields are not_attempted.
+    """
+    One result per request binding, in request order; empty when the fill used no
+    bindings. After the first failed or unknown field, all remaining fields are
+    not_attempted.
     """
 
     status: Literal["completed", "failed", "unknown"]
-    """Completed only when all fields were filled.
+    """Completed when the fill finished.
 
-    Failed when execution stopped with known outcomes. Unknown when any field's
-    outcome cannot be determined. None of these statuses confirms payment or
-    merchant acceptance.
+    Failed when execution stopped with known outcomes. Unknown when an outcome
+    cannot be determined. Completed means values were supplied to the page, not that
+    the site accepted or submitted them.
     """
 
     type: Literal["fill"]

src/kernel/types/vaults/item_perform_operation_params.py

@@ -34,6 +34,15 @@ class AuthorizeVaultItemOperationRequest(TypedDict, total=False):
 
     type: Required[Literal["authorize"]]
 
+    browser_id: str
+    """Browser session ID, not a reusable browser name.
+
+    The browser must have this vault attached.
+    """
+
+    page_url: str
+    """Exact current top-level URL of the final checkout page open in browser_id."""
+
 
 class RestartVerificationVaultItemOperationRequest(TypedDict, total=False):
     id_or_name: Required[str]
@@ -89,18 +98,26 @@ class FillVaultItemOperationRequest(TypedDict, total=False):
     browser_id: Required[str]
     """Browser session ID, not a reusable browser name."""
 
-    fields: Required[Iterable[VaultFillFieldParam]]
-    """Field bindings for this step. No two bindings may resolve to the same element."""
-
     type: Required[Literal["fill"]]
 
+    fields: Iterable[VaultFillFieldParam]
+    """
+    Field bindings, when the item's advertised fill operation requires them. Each
+    selector is searched in the main frame and all descendant frames and must
+    resolve to exactly one editable input or select, matched directly or through a
+    containing element; zero or multiple candidates fail, and no two bindings may
+    resolve to the same element. Select elements match an option by value, not
+    label. All bindings are validated before any write, then filled in request
+    order, stopping at the first failure. If the page navigates or a target
+    disappears, fill stops rather than choosing another page or element.
+    """
+
     page_url: str
     """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. Required for cards, which must use HTTPS without
-    embedded credentials. Optional for credentials, where omission requires exactly
-    one open page.
+    No prefix or glob matching. When an item allows omitting it, the browser must
+    have exactly one open page.
     """
 
     timeout_ms: int

src/kernel/types/vaults/item_update_params.py

@@ -15,7 +15,14 @@ class CardVaultItemUpdateRequest(TypedDict, total=False):
     id_or_name: Required[str]
 
     spec: Required[CardVaultItemSpecParam]
-    """Live payment card. Test-mode card creation is not supported."""
+    """Live Link card request.
+
+    Test-mode card creation is not supported. The spec can be changed with PATCH
+    until the card is authorized at a checkout. Authorize it with the browser at
+    final checkout: Kernel inspects the checkout through WebMCP and internally
+    chooses a merchant-bound Link Pay Token when supported or a virtual card
+    otherwise. Callers never receive or choose how the credential is delivered.
+    """
 
     type: Literal["card"]
 

src/kernel/types/vaults/item_upsert_params.py

@@ -187,7 +187,14 @@ class CardVaultItemRequest(TypedDict, total=False):
     id_or_name: Required[str]
 
     spec: Required[CardVaultItemSpecParam]
-    """Live payment card. Test-mode card creation is not supported."""
+    """Live Link card request.
+
+    Test-mode card creation is not supported. The spec can be changed with PATCH
+    until the card is authorized at a checkout. Authorize it with the browser at
+    final checkout: Kernel inspects the checkout through WebMCP and internally
+    chooses a merchant-bound Link Pay Token when supported or a virtual card
+    otherwise. Callers never receive or choose how the credential is delivered.
+    """
 
     type: Required[Literal["card"]]
 

src/kernel/types/vaults/vault_item.py

@@ -98,6 +98,9 @@ class WalletVaultItem(BaseModel):
 
     action: Optional[VaultItemAction] = None
 
+    description: Optional[str] = None
+    """Server-generated provider and lifecycle guidance for agents."""
+
     expanded: Optional[WalletVaultItemExpanded] = None
     """Live, non-persisted data requested through the item GET expand parameter."""
 
@@ -151,7 +154,14 @@ class CardVaultItem(BaseModel):
     """Immutable item key assigned when the item is created."""
 
     spec: CardVaultItemSpec
-    """Live payment card. Test-mode card creation is not supported."""
+    """Live Link card request.
+
+    Test-mode card creation is not supported. The spec can be changed with PATCH
+    until the card is authorized at a checkout. Authorize it with the browser at
+    final checkout: Kernel inspects the checkout through WebMCP and internally
+    chooses a merchant-bound Link Pay Token when supported or a virtual card
+    otherwise. Callers never receive or choose how the credential is delivered.
+    """
 
     state: CardVaultItemState
     """Issued Link cards retain encrypted card material for the fill operation.

src/kernel/types/vaults/vault_item_operation_response.py

@@ -100,6 +100,9 @@ class WalletVaultItem(BaseModel):
 
     action: Optional[VaultItemAction] = None
 
+    description: Optional[str] = None
+    """Server-generated provider and lifecycle guidance for agents."""
+
     expanded: Optional[WalletVaultItemExpanded] = None
     """Live, non-persisted data requested through the item GET expand parameter."""
 
@@ -153,7 +156,14 @@ class CardVaultItem(BaseModel):
     """Immutable item key assigned when the item is created."""
 
     spec: CardVaultItemSpec
-    """Live payment card. Test-mode card creation is not supported."""
+    """Live Link card request.
+
+    Test-mode card creation is not supported. The spec can be changed with PATCH
+    until the card is authorized at a checkout. Authorize it with the browser at
+    final checkout: Kernel inspects the checkout through WebMCP and internally
+    chooses a merchant-bound Link Pay Token when supported or a virtual card
+    otherwise. Callers never receive or choose how the credential is delivered.
+    """
 
     state: CardVaultItemState
     """Issued Link cards retain encrypted card material for the fill operation.