From a008dfbe12ab150df7154f28127175e4ceee3816 Mon Sep 17 00:00:00 2001 From: "kernel-internal[bot]" <260533166+kernel-internal[bot]@users.noreply.github.com> Date: Fri, 11 Sep 2026 14:49:49 +0000 Subject: [PATCH 1/9] feat: Document punctuation key sequences Stainless-Generated-From: 33f6b77e4ee242cca4c48f8813036f180bafa75e --- src/resources/browsers/computer.ts | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/resources/browsers/computer.ts b/src/resources/browsers/computer.ts index a51d618..b647d79 100644 --- a/src/resources/browsers/computer.ts +++ b/src/resources/browsers/computer.ts @@ -439,7 +439,9 @@ export namespace ComputerBatchParams { * List of key symbols to press. Each item should be a key symbol supported by * xdotool (see X11 keysym definitions). Examples include "Return", "Shift", * "Ctrl", "Alt", "F5". Items in this list could also be combinations, e.g. - * "Ctrl+t" or "Ctrl+Shift+Tab". + * "Ctrl+t" or "Ctrl+Shift+Tab". Use X11 names for punctuation in combinations, + * such as "Ctrl+minus" or "Ctrl+plus". A literal hyphen is also accepted as an + * alias, so "Ctrl+-" is normalized to "Ctrl+minus". */ keys: Array; @@ -654,7 +656,9 @@ export interface ComputerPressKeyParams { * List of key symbols to press. Each item should be a key symbol supported by * xdotool (see X11 keysym definitions). Examples include "Return", "Shift", * "Ctrl", "Alt", "F5". Items in this list could also be combinations, e.g. - * "Ctrl+t" or "Ctrl+Shift+Tab". + * "Ctrl+t" or "Ctrl+Shift+Tab". Use X11 names for punctuation in combinations, + * such as "Ctrl+minus" or "Ctrl+plus". A literal hyphen is also accepted as an + * alias, so "Ctrl+-" is normalized to "Ctrl+minus". */ keys: Array; From 0fdcce80cec36d682f295d278ae88b5e4877560b Mon Sep 17 00:00:00 2001 From: "kernel-internal[bot]" <260533166+kernel-internal[bot]@users.noreply.github.com> Date: Fri, 11 Sep 2026 18:07:23 +0000 Subject: [PATCH 2/9] feat: Reapply vendor guidance recommendations Stainless-Generated-From: c7e2428f6249bde3aa911cce83b16b4d617022ba --- src/resources/config-registry/config-registry.ts | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/resources/config-registry/config-registry.ts b/src/resources/config-registry/config-registry.ts index 67f94a0..6a4d917 100644 --- a/src/resources/config-registry/config-registry.ts +++ b/src/resources/config-registry/config-registry.ts @@ -152,6 +152,14 @@ export interface ConfigRegistryResponse { recommendation: RecommendationResult | null; target: Target; + + /** + * Short advisory markdown to facilitate navigating this target. Returned even when + * no configuration reached the target, since knowing what prevented success is + * useful without a configuration. Not verified against this target. Null when + * nothing applicable was observed or no notes exist. + */ + guidance?: string | null; } export interface Evidence { @@ -204,6 +212,14 @@ export interface LookupResponse { recommendation: Recommendation | null; target: Target; + + /** + * Short advisory markdown to facilitate navigating this target. Returned even when + * no configuration reached the target, since knowing what prevented success is + * useful without a configuration. Not verified against this target. Null when + * nothing applicable was observed or no notes exist. + */ + guidance?: string | null; } export interface NoRecommendation { From 848944b1ce0eb21f58700d41ed82b5121201a3ee Mon Sep 17 00:00:00 2001 From: "kernel-internal[bot]" <260533166+kernel-internal[bot]@users.noreply.github.com> Date: Fri, 11 Sep 2026 18:49:06 +0000 Subject: [PATCH 3/9] feat: Allow replacing AgentCard cards after unknown creates Stainless-Generated-From: 8e72f2abb75350a74a3559de1369e3eb6a96d63c --- src/resources/vaults/items.ts | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/src/resources/vaults/items.ts b/src/resources/vaults/items.ts index 1441fe7..67fc610 100644 --- a/src/resources/vaults/items.ts +++ b/src/resources/vaults/items.ts @@ -74,9 +74,11 @@ export class Items extends APIResource { } /** - * Unresolved payment operations block deletion, including operations on child - * cards of a wallet. Reconcile the original attempt with the provider or support - * first; deleting or recreating an item is not proof that a payment did not occur. + * Unresolved payment operations normally block deletion, including operations on + * child cards of a wallet. An AgentCard checkout whose 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. * * @example * ```ts @@ -398,10 +400,12 @@ export namespace CardVaultItemState { provider: 'agentcard'; /** - * recovery_required means the original checkout outcome is unresolved. Do not - * retry, delete, or replace it. Known authorization IDs may be reconciled through - * provider observations; otherwise contact the provider or support for manual - * reconciliation. It does not mean declined or expired. + * recovery_required means the original checkout outcome is unresolved. Automatic + * reuse is blocked. Known authorization IDs must be reconciled through provider + * observations or support. When no authorization ID was returned, an explicitly + * confirmed item deletion may abandon the unresolved attempt so the caller can + * create a replacement; deletion does not prove that the original attempt failed. + * It does not mean declined or expired. */ status: 'requested' | 'ready' | 'pending_approval' | 'degraded' | 'recovery_required'; From a57d992925092ebce6ba6e18fbb86844edfb67f5 Mon Sep 17 00:00:00 2001 From: "kernel-internal[bot]" <260533166+kernel-internal[bot]@users.noreply.github.com> Date: Fri, 11 Sep 2026 21:19:02 +0000 Subject: [PATCH 4/9] feat: Report proxy-restricted targets from config registry lookup Stainless-Generated-From: c33621d7ff6d8e7d97650e767c9620a55f921e17 --- src/resources/config-registry/config-registry.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/resources/config-registry/config-registry.ts b/src/resources/config-registry/config-registry.ts index 6a4d917..88cae73 100644 --- a/src/resources/config-registry/config-registry.ts +++ b/src/resources/config-registry/config-registry.ts @@ -209,7 +209,10 @@ export interface LookupRequest { } export interface LookupResponse { - recommendation: Recommendation | null; + /** + * A recommendation or a structured no-recommendation result. + */ + recommendation: RecommendationResult | null; target: Target; From d77b170936a96eb79327b189d05f2c8f1f0737c3 Mon Sep 17 00:00:00 2001 From: "kernel-internal[bot]" <260533166+kernel-internal[bot]@users.noreply.github.com> Date: Sun, 13 Sep 2026 22:46:33 +0000 Subject: [PATCH 5/9] feat: Add guarded vault card fill operations Stainless-Generated-From: de486b1aa3fe4aed5dcbf1a995eb6bc902d2682d --- api.md | 7 +- src/resources/vaults/index.ts | 5 + src/resources/vaults/items.ts | 375 +++++++++++++++++++++++++++++++-- src/resources/vaults/vaults.ts | 10 + 4 files changed, 378 insertions(+), 19 deletions(-) diff --git a/api.md b/api.md index 074a955..a9bc977 100644 --- a/api.md +++ b/api.md @@ -467,10 +467,15 @@ Types: - AgentcardCheckoutAuthorization - CardVaultItemSpec - CardVaultItemState +- FillVaultItemOperationRequest +- FillVaultItemOperationResult - VaultCardAliases +- VaultCardFillField +- VaultFillFieldResult - VaultItem - VaultItemAction - VaultItemEvent +- VaultItemOperationResponse - VaultPaymentMethod - WalletVaultItemSpec - WalletVaultItemState @@ -484,7 +489,7 @@ Methods: - client.vaults.items.list(idOrName) -> ItemListResponse - client.vaults.items.delete(key, { ...params }) -> void - client.vaults.items.events(key, { ...params }) -> ItemEventsResponse -- client.vaults.items.performOperation(key, { ...params }) -> VaultItem +- client.vaults.items.performOperation(key, { ...params }) -> VaultItemOperationResponse - client.vaults.items.upsert(key, { ...params }) -> VaultItem # Credentials diff --git a/src/resources/vaults/index.ts b/src/resources/vaults/index.ts index 190af0e..5732322 100644 --- a/src/resources/vaults/index.ts +++ b/src/resources/vaults/index.ts @@ -5,10 +5,15 @@ export { type AgentcardCheckoutAuthorization, type CardVaultItemSpec, type CardVaultItemState, + type FillVaultItemOperationRequest, + type FillVaultItemOperationResult, type VaultCardAliases, + type VaultCardFillField, + type VaultFillFieldResult, type VaultItem, type VaultItemAction, type VaultItemEvent, + type VaultItemOperationResponse, type VaultPaymentMethod, type WalletVaultItemSpec, type WalletVaultItemState, diff --git a/src/resources/vaults/items.ts b/src/resources/vaults/items.ts index 67fc610..81145dd 100644 --- a/src/resources/vaults/items.ts +++ b/src/resources/vaults/items.ts @@ -113,16 +113,24 @@ export class Items extends APIResource { /** * Retrieve the item first and invoke only an operation listed in - * `available_operations`, following its natural-language description. Operations - * may call an external provider and return updated state. Link cards advertise - * authorize. AgentCard cards are created with PUT and request approval when their - * aliases are used at checkout; they do not expose this operation. If - * spend-request creation is rate limited, returns HTTP 429 with code + * `available_operations`, following its natural-language description. Availability + * is rechecked at execution time; unavailable operations return 409. Authorization + * may call an external provider and returns the updated item. Link cards advertise + * authorize when eligible. AgentCard cards are created with PUT and request + * approval when their aliases are used at checkout; they do not expose authorize. + * If spend-request creation is rate limited, returns HTTP 429 with code * `spend_request_rate_limited`; stop and back off before retrying. * + * 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, + * known partial failures and indeterminate field outcomes return 200 with status + * `failed` or `unknown`, not an automatic-retry signal. A transport error may + * leave the outcome unknown; do not automatically retry. + * * @example * ```ts - * const vaultItem = + * const vaultItemOperationResponse = * await client.vaults.items.performOperation('key', { * id_or_name: 'id_or_name', * type: 'authorize', @@ -133,7 +141,7 @@ export class Items extends APIResource { key: string, params: ItemPerformOperationParams, options?: RequestOptions, - ): APIPromise { + ): APIPromise { const { id_or_name, ...body } = params; return this._client.post(path`/vaults/${id_or_name}/items/${key}/operations`, { body, ...options }); } @@ -433,6 +441,77 @@ export namespace CardVaultItemState { } } +/** + * Fill selected fields from one ready, unexpired card into a browser linked to its + * vault. Only supported for card items created from Link wallets. 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`. 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. Fill is the + * preferred browser-checkout path. Aliases remain an alternative for explicitly + * chosen egress-substitution integrations. Do not automatically retry or fall back + * to aliases after a failed or indeterminate operation. + * + * Secret values are never returned or included in operation logs, traces, audit + * events, or error details. This does not prevent an agent with unrestricted + * browser access from reading values from the page or other browser observation + * surfaces. + */ +export interface FillVaultItemOperationRequest { + /** + * Browser session ID, not a reusable browser name. + */ + browser_id: string; + + /** + * Field bindings for this step. No two bindings may resolve to the same element. + */ + fields: Array; + + /** + * 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. Must use HTTPS without embedded credentials. + */ + page_url: string; + + type: 'fill'; + + /** + * Total operation deadline in milliseconds, not a per-field timeout. + */ + timeout_ms?: number; +} + +export interface FillVaultItemOperationResult { + /** + * Exactly one result per request binding, in request order. After the first failed + * or unknown field, all remaining fields are not_attempted. + */ + fields: Array; + + /** + * Completed only when all fields were filled. 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. + */ + status: 'completed' | 'failed' | 'unknown'; + + type: 'fill'; +} + export interface VaultCardAliases { cvc: string; @@ -443,6 +522,87 @@ export interface VaultCardAliases { number: string; } +/** + * Combined expiration derived from the stored month and year; not a separate + * stored secret. + */ +export type VaultCardFillField = + | VaultCardFillField.VaultCardStoredFillField + | VaultCardFillField.VaultCardExpirationFillField; + +export namespace VaultCardFillField { + export interface VaultCardStoredFillField { + /** + * Field in the decrypted card, not an alias. Number and CVC preserve leading + * zeros; month uses two digits and year uses four digits. Billing fields use the + * provider's stored billing address (name, line1, line2, city, state, postal_code, + * country) without reformatting. Request only needed billing fields. An absent or + * empty requested billing field returns 400 field_unavailable before any browser + * writes; it does not make other card fields unavailable. + */ + field: + | 'number' + | 'exp_month' + | 'exp_year' + | 'cvc' + | 'billing_name' + | 'billing_line1' + | 'billing_line2' + | 'billing_city' + | 'billing_state' + | 'billing_postal_code' + | 'billing_country'; + + /** + * CSS selector for an editable input or select, or a containing element. Must + * resolve to one unique editable element across all page frames. + */ + selector: string; + } + + /** + * Combined expiration derived from the stored month and year; not a separate + * stored secret. + */ + export interface VaultCardExpirationFillField { + field: 'expiration'; + + format: 'MM/YY' | 'MM/YYYY'; + + /** + * CSS selector for an editable input or select, or a containing element. Must + * resolve to one unique editable element across all page frames. + */ + selector: string; + } +} + +export interface VaultFillFieldResult { + /** + * Zero-based index into the request fields array. + */ + index: number; + + /** + * Filled means the fill action completed, not that the website retained or + * accepted the value. + */ + status: 'filled' | 'failed' | 'not_attempted' | 'unknown'; + + /** + * Present only for failed or unknown fields. Never includes secret values, DOM + * content, or raw browser errors. + */ + error_code?: + | 'target_changed' + | 'element_not_found' + | 'ambiguous_selector' + | 'element_not_editable' + | 'option_not_found' + | 'timeout' + | 'execution_failed'; +} + export type VaultItem = VaultItem.WalletVaultItem | VaultItem.CardVaultItem; export namespace VaultItem { @@ -504,7 +664,7 @@ export namespace VaultItem { export interface AvailableOperation { description: string; - type: 'authorize'; + type: 'authorize' | 'fill'; } /** @@ -563,7 +723,7 @@ export namespace VaultItem { export interface AvailableOperation { description: string; - type: 'authorize'; + type: 'authorize' | 'fill'; } } } @@ -628,6 +788,138 @@ export interface VaultItemEvent { data?: { [key: string]: unknown }; } +/** + * Authorization returns the existing item shape. Fill returns a value-free + * execution result; it does not persist transient field outcomes on the item. + */ +export type VaultItemOperationResponse = + | VaultItemOperationResponse.WalletVaultItem + | VaultItemOperationResponse.CardVaultItem + | FillVaultItemOperationResult; + +export namespace VaultItemOperationResponse { + export interface WalletVaultItem { + id: string; + + available_expansions: Array; + + available_operations: Array; + + created_at: string; + + /** + * Immutable item key assigned when the item is created. + */ + key: string; + + /** + * 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. + */ + spec: ItemsAPI.WalletVaultItemSpec; + + state: ItemsAPI.WalletVaultItemState; + + type: 'wallet'; + + updated_at: string; + + action?: ItemsAPI.VaultItemAction; + + /** + * Live, non-persisted data requested through the item GET expand parameter. + */ + expanded?: WalletVaultItem.Expanded; + + expires_at?: string; + } + + export namespace WalletVaultItem { + /** + * Live data that can currently be requested by passing its type to the item GET + * expand parameter. + */ + export interface AvailableExpansion { + description: string; + + type: 'payment_methods'; + } + + /** + * An operation that is currently valid for this item. Read the description before + * invoking it through the item operations endpoint. + */ + export interface AvailableOperation { + description: string; + + type: 'authorize' | 'fill'; + } + + /** + * Live, non-persisted data requested through the item GET expand parameter. + */ + export interface Expanded { + payment_methods?: Array; + } + } + + export interface CardVaultItem { + id: string; + + available_expansions: Array; + + available_operations: Array; + + created_at: string; + + /** + * Immutable item key assigned when the item is created. + */ + key: string; + + /** + * Live payment card. Test-mode card creation is not supported. + */ + spec: ItemsAPI.CardVaultItemSpec; + + state: ItemsAPI.CardVaultItemState; + + type: 'card'; + + updated_at: string; + + action?: ItemsAPI.VaultItemAction; + + expires_at?: string; + } + + export namespace CardVaultItem { + /** + * Live data that can currently be requested by passing its type to the item GET + * expand parameter. + */ + export interface AvailableExpansion { + description: string; + + type: 'payment_methods'; + } + + /** + * An operation that is currently valid for this item. Read the description before + * invoking it through the item operations endpoint. + */ + export interface AvailableOperation { + description: string; + + type: 'authorize' | 'fill'; + } + } +} + export interface VaultPaymentMethod { id: string; @@ -851,16 +1143,58 @@ export interface ItemEventsParams { wait?: number; } -export interface ItemPerformOperationParams { - /** - * Path param - */ - id_or_name: string; +export type ItemPerformOperationParams = + | ItemPerformOperationParams.AuthorizeVaultItemOperationRequest + | ItemPerformOperationParams.FillVaultItemOperationRequest; - /** - * Body param - */ - type: 'authorize'; +export declare namespace ItemPerformOperationParams { + export interface AuthorizeVaultItemOperationRequest { + /** + * Path param + */ + id_or_name: string; + + /** + * Body param + */ + type: 'authorize'; + } + + export interface FillVaultItemOperationRequest { + /** + * Path param + */ + id_or_name: string; + + /** + * Body param: Browser session ID, not a reusable browser name. + */ + browser_id: string; + + /** + * Body param: Field bindings for this step. No two bindings may resolve to the + * same element. + */ + fields: Array; + + /** + * Body param: 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. Must use HTTPS without embedded + * credentials. + */ + page_url: string; + + /** + * Body param + */ + type: 'fill'; + + /** + * Body param: Total operation deadline in milliseconds, not a per-field timeout. + */ + timeout_ms?: number; + } } export type ItemUpsertParams = @@ -1059,10 +1393,15 @@ export declare namespace Items { type AgentcardCheckoutAuthorization as AgentcardCheckoutAuthorization, type CardVaultItemSpec as CardVaultItemSpec, type CardVaultItemState as CardVaultItemState, + type FillVaultItemOperationRequest as FillVaultItemOperationRequest, + type FillVaultItemOperationResult as FillVaultItemOperationResult, type VaultCardAliases as VaultCardAliases, + type VaultCardFillField as VaultCardFillField, + type VaultFillFieldResult as VaultFillFieldResult, type VaultItem as VaultItem, type VaultItemAction as VaultItemAction, type VaultItemEvent as VaultItemEvent, + type VaultItemOperationResponse as VaultItemOperationResponse, type VaultPaymentMethod as VaultPaymentMethod, type WalletVaultItemSpec as WalletVaultItemSpec, type WalletVaultItemState as WalletVaultItemState, diff --git a/src/resources/vaults/vaults.ts b/src/resources/vaults/vaults.ts index 3558f3d..b3b8b75 100644 --- a/src/resources/vaults/vaults.ts +++ b/src/resources/vaults/vaults.ts @@ -6,6 +6,8 @@ import { AgentcardCheckoutAuthorization, CardVaultItemSpec, CardVaultItemState, + FillVaultItemOperationRequest, + FillVaultItemOperationResult, ItemDeleteParams, ItemEventsParams, ItemEventsResponse, @@ -16,9 +18,12 @@ import { ItemUpsertParams, Items, VaultCardAliases, + VaultCardFillField, + VaultFillFieldResult, VaultItem, VaultItemAction, VaultItemEvent, + VaultItemOperationResponse, VaultPaymentMethod, WalletVaultItemSpec, WalletVaultItemState, @@ -135,10 +140,15 @@ export declare namespace Vaults { type AgentcardCheckoutAuthorization as AgentcardCheckoutAuthorization, type CardVaultItemSpec as CardVaultItemSpec, type CardVaultItemState as CardVaultItemState, + type FillVaultItemOperationRequest as FillVaultItemOperationRequest, + type FillVaultItemOperationResult as FillVaultItemOperationResult, type VaultCardAliases as VaultCardAliases, + type VaultCardFillField as VaultCardFillField, + type VaultFillFieldResult as VaultFillFieldResult, type VaultItem as VaultItem, type VaultItemAction as VaultItemAction, type VaultItemEvent as VaultItemEvent, + type VaultItemOperationResponse as VaultItemOperationResponse, type VaultPaymentMethod as VaultPaymentMethod, type WalletVaultItemSpec as WalletVaultItemSpec, type WalletVaultItemState as WalletVaultItemState, From f6718d4fb93818147fb51b53545fc1327294d5d2 Mon Sep 17 00:00:00 2001 From: "kernel-internal[bot]" <260533166+kernel-internal[bot]@users.noreply.github.com> Date: Mon, 14 Sep 2026 17:06:09 +0000 Subject: [PATCH 6/9] feat: Add single-use AgentCard prepare_checkout for Square Stainless-Generated-From: 6aa71ac773e2d94ade986e0da43f0dbb2221748b --- api.md | 4 + src/resources/vaults/index.ts | 4 + src/resources/vaults/items.ts | 182 +++++++++++++++++++++++++++++---- src/resources/vaults/vaults.ts | 8 ++ 4 files changed, 177 insertions(+), 21 deletions(-) diff --git a/api.md b/api.md index a9bc977..62f3a3a 100644 --- a/api.md +++ b/api.md @@ -465,12 +465,16 @@ Methods: Types: - AgentcardCheckoutAuthorization +- AgentcardCheckoutPreparation +- AuthorizeVaultItemOperationRequest - CardVaultItemSpec - CardVaultItemState - FillVaultItemOperationRequest - FillVaultItemOperationResult +- PrepareCheckoutVaultItemOperationRequest - VaultCardAliases - VaultCardFillField +- VaultCheckoutContext - VaultFillFieldResult - VaultItem - VaultItemAction diff --git a/src/resources/vaults/index.ts b/src/resources/vaults/index.ts index 5732322..63e8c51 100644 --- a/src/resources/vaults/index.ts +++ b/src/resources/vaults/index.ts @@ -3,12 +3,16 @@ export { Items, type AgentcardCheckoutAuthorization, + type AgentcardCheckoutPreparation, + type AuthorizeVaultItemOperationRequest, type CardVaultItemSpec, type CardVaultItemState, type FillVaultItemOperationRequest, type FillVaultItemOperationResult, + type PrepareCheckoutVaultItemOperationRequest, type VaultCardAliases, type VaultCardFillField, + type VaultCheckoutContext, type VaultFillFieldResult, type VaultItem, type VaultItemAction, diff --git a/src/resources/vaults/items.ts b/src/resources/vaults/items.ts index 81145dd..f3d5656 100644 --- a/src/resources/vaults/items.ts +++ b/src/resources/vaults/items.ts @@ -75,10 +75,10 @@ export class Items extends APIResource { /** * Unresolved payment operations normally block deletion, including operations on - * child cards of a wallet. An AgentCard checkout whose 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. 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. * * @example * ```ts @@ -115,10 +115,13 @@ export class Items extends APIResource { * Retrieve the item first and invoke only an operation listed in * `available_operations`, following its natural-language description. Availability * is rechecked at execution time; unavailable operations return 409. Authorization - * may call an external provider and returns the updated item. Link cards advertise - * authorize when eligible. AgentCard cards are created with PUT and request - * approval when their aliases are used at checkout; they do not expose authorize. - * If spend-request creation is rate limited, returns HTTP 429 with code + * and preparation may call an external provider and return updated state. Link + * cards advertise authorize without checkout context. Eligible unused AgentCard + * cards advertise prepare_checkout, which requires checkout context and obtains + * device approval before native Square Pay. Keep the returned approval page open, + * poll until ready_to_submit, then submit before preparation.expires_at. Unused + * preparations expire automatically and cannot be reused. If spend-request + * creation is rate limited, returns HTTP 429 with code * `spend_request_rate_limited`; stop and back off before retrying. * * Fill returns a value-free execution result. Validation failures before writing @@ -233,6 +236,50 @@ export interface AgentcardCheckoutAuthorization { replay_status?: number; } +/** + * One-use Square checkout preparation. Keep the approval page open through token + * handoff. The amount is display-only and does not constrain the merchant's + * eventual charge. + */ +export interface AgentcardCheckoutPreparation { + browser_id: string; + + created_at: string; + + environment: 'production' | 'sandbox'; + + merchant_origin: string; + + /** + * Preparation consumed means egress claimed the preparation and it cannot be + * reused. It does not mean the attempt settled. Use the enclosing item's status as + * the lifecycle indicator; item consumed means the attempt settled, not that an + * order or charge succeeded. + */ + status: 'creating' | 'awaiting_approval' | 'ready' | 'consumed' | 'cancelled' | 'expired' | 'unknown'; + + id?: string; + + approval_url?: string; + + /** + * When ready, the absolute deadline to submit the first native request; no later + * than provider readiness expiry or 30 seconds after Kernel first observes + * readiness. Polling never extends this deadline. + */ + expires_at?: string; +} + +/** + * Authorize a Link 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. + */ +export interface AuthorizeVaultItemOperationRequest { + type: 'authorize'; +} + /** * Live payment card. Test-mode card creation is not supported. */ @@ -408,14 +455,27 @@ export namespace CardVaultItemState { provider: 'agentcard'; /** - * recovery_required means the original checkout outcome is unresolved. Automatic - * reuse is blocked. Known authorization IDs must be reconciled through provider - * observations or support. When no authorization ID was returned, an explicitly - * confirmed item deletion may abandon the unresolved attempt so the caller can - * create a replacement; deletion does not prove that the original attempt failed. - * It does not mean declined or expired. + * ready_to_submit is device readiness for at most 30 seconds. consumed means the + * prepared attempt has settled, not that an order succeeded. stopped cannot be + * reused. outcome_unknown requires merchant reconciliation and blocks new + * requests. recovery_required means the original checkout outcome is unresolved. + * Automatic reuse is blocked. Known authorization IDs must be reconciled through + * provider observations or support. When no authorization ID was returned, an + * explicitly confirmed item deletion may abandon the unresolved attempt so the + * caller can create a replacement; deletion does not prove that the original + * attempt failed. It does not mean declined or expired. */ - status: 'requested' | 'ready' | 'pending_approval' | 'degraded' | 'recovery_required'; + status: + | 'requested' + | 'ready' + | 'preparing' + | 'ready_to_submit' + | 'pending_approval' + | 'consumed' + | 'stopped' + | 'outcome_unknown' + | 'degraded' + | 'recovery_required'; aliases?: ItemsAPI.VaultCardAliases; @@ -427,6 +487,13 @@ export namespace CardVaultItemState { masks?: AgentCardCardState.Masks; + /** + * One-use Square checkout preparation. Keep the approval page open through token + * handoff. The amount is display-only and does not constrain the merchant's + * eventual charge. + */ + preparation?: ItemsAPI.AgentcardCheckoutPreparation; + status_reason?: string; } @@ -512,6 +579,27 @@ export interface FillVaultItemOperationResult { type: 'fill'; } +/** + * Prepare an unused AgentCard card for Square checkout. Deliver the returned + * approval URL and keep the approval page open. Poll the item until + * ready_to_submit, then submit native Pay before preparation.expires_at. Readiness + * lasts at most 30 seconds. Unused preparations expire automatically. Preparations + * are single-use even after failure or expiry; do not automatically retry and + * reconcile uncertain outcomes with the merchant. + */ +export interface PrepareCheckoutVaultItemOperationRequest { + /** + * Required when preparing an unused AgentCard card for Square. Consent is bound to + * this browser and declared merchant origin, not a tab. Wait for the item's + * ready_to_submit status before native Pay and submit within its readiness + * deadline. Unused preparations expire automatically; every preparation is + * single-use, including after failure or expiry. + */ + checkout: VaultCheckoutContext; + + type: 'prepare_checkout'; +} + export interface VaultCardAliases { cvc: string; @@ -577,6 +665,31 @@ export namespace VaultCardFillField { } } +/** + * Required when preparing an unused AgentCard card for Square. Consent is bound to + * this browser and declared merchant origin, not a tab. Wait for the item's + * ready_to_submit status before native Pay and submit within its readiness + * deadline. Unused preparations expire automatically; every preparation is + * single-use, including after failure or expiry. + */ +export interface VaultCheckoutContext { + /** + * Active browser session with this vault bound to it. + */ + browser_id: string; + + /** + * Square environment, independent of the AgentCard credential mode. + */ + environment: 'production' | 'sandbox'; + + /** + * Canonical HTTPS origin of the top-level merchant document, not the Square + * iframe. HTTP localhost is accepted for tests. + */ + merchant_origin: string; +} + export interface VaultFillFieldResult { /** * Zero-based index into the request fields array. @@ -664,7 +777,7 @@ export namespace VaultItem { export interface AvailableOperation { description: string; - type: 'authorize' | 'fill'; + type: 'authorize' | 'prepare_checkout' | 'fill'; } /** @@ -723,7 +836,7 @@ export namespace VaultItem { export interface AvailableOperation { description: string; - type: 'authorize' | 'fill'; + type: 'authorize' | 'prepare_checkout' | 'fill'; } } } @@ -789,8 +902,9 @@ export interface VaultItemEvent { } /** - * Authorization returns the existing item shape. Fill returns a value-free - * execution result; it does not persist transient field outcomes on the item. + * Authorization and preparation return the existing item shape. Fill returns a + * value-free execution result; it does not persist transient field outcomes on the + * item. */ export type VaultItemOperationResponse = | VaultItemOperationResponse.WalletVaultItem @@ -856,7 +970,7 @@ export namespace VaultItemOperationResponse { export interface AvailableOperation { description: string; - type: 'authorize' | 'fill'; + type: 'authorize' | 'prepare_checkout' | 'fill'; } /** @@ -915,7 +1029,7 @@ export namespace VaultItemOperationResponse { export interface AvailableOperation { description: string; - type: 'authorize' | 'fill'; + type: 'authorize' | 'prepare_checkout' | 'fill'; } } } @@ -1145,6 +1259,7 @@ export interface ItemEventsParams { export type ItemPerformOperationParams = | ItemPerformOperationParams.AuthorizeVaultItemOperationRequest + | ItemPerformOperationParams.PrepareCheckoutVaultItemOperationRequest | ItemPerformOperationParams.FillVaultItemOperationRequest; export declare namespace ItemPerformOperationParams { @@ -1160,6 +1275,27 @@ export declare namespace ItemPerformOperationParams { type: 'authorize'; } + export interface PrepareCheckoutVaultItemOperationRequest { + /** + * Path param + */ + id_or_name: string; + + /** + * Body param: Required when preparing an unused AgentCard card for Square. Consent + * is bound to this browser and declared merchant origin, not a tab. Wait for the + * item's ready_to_submit status before native Pay and submit within its readiness + * deadline. Unused preparations expire automatically; every preparation is + * single-use, including after failure or expiry. + */ + checkout: VaultCheckoutContext; + + /** + * Body param + */ + type: 'prepare_checkout'; + } + export interface FillVaultItemOperationRequest { /** * Path param @@ -1391,12 +1527,16 @@ export declare namespace ItemUpsertParams { export declare namespace Items { export { type AgentcardCheckoutAuthorization as AgentcardCheckoutAuthorization, + type AgentcardCheckoutPreparation as AgentcardCheckoutPreparation, + type AuthorizeVaultItemOperationRequest as AuthorizeVaultItemOperationRequest, type CardVaultItemSpec as CardVaultItemSpec, type CardVaultItemState as CardVaultItemState, type FillVaultItemOperationRequest as FillVaultItemOperationRequest, type FillVaultItemOperationResult as FillVaultItemOperationResult, + type PrepareCheckoutVaultItemOperationRequest as PrepareCheckoutVaultItemOperationRequest, type VaultCardAliases as VaultCardAliases, type VaultCardFillField as VaultCardFillField, + type VaultCheckoutContext as VaultCheckoutContext, type VaultFillFieldResult as VaultFillFieldResult, type VaultItem as VaultItem, type VaultItemAction as VaultItemAction, diff --git a/src/resources/vaults/vaults.ts b/src/resources/vaults/vaults.ts index b3b8b75..450c9a1 100644 --- a/src/resources/vaults/vaults.ts +++ b/src/resources/vaults/vaults.ts @@ -4,6 +4,8 @@ import { APIResource } from '../../core/resource'; import * as ItemsAPI from './items'; import { AgentcardCheckoutAuthorization, + AgentcardCheckoutPreparation, + AuthorizeVaultItemOperationRequest, CardVaultItemSpec, CardVaultItemState, FillVaultItemOperationRequest, @@ -17,8 +19,10 @@ import { ItemUpdateParams, ItemUpsertParams, Items, + PrepareCheckoutVaultItemOperationRequest, VaultCardAliases, VaultCardFillField, + VaultCheckoutContext, VaultFillFieldResult, VaultItem, VaultItemAction, @@ -138,12 +142,16 @@ export declare namespace Vaults { export { Items as Items, type AgentcardCheckoutAuthorization as AgentcardCheckoutAuthorization, + type AgentcardCheckoutPreparation as AgentcardCheckoutPreparation, + type AuthorizeVaultItemOperationRequest as AuthorizeVaultItemOperationRequest, type CardVaultItemSpec as CardVaultItemSpec, type CardVaultItemState as CardVaultItemState, type FillVaultItemOperationRequest as FillVaultItemOperationRequest, type FillVaultItemOperationResult as FillVaultItemOperationResult, + type PrepareCheckoutVaultItemOperationRequest as PrepareCheckoutVaultItemOperationRequest, type VaultCardAliases as VaultCardAliases, type VaultCardFillField as VaultCardFillField, + type VaultCheckoutContext as VaultCheckoutContext, type VaultFillFieldResult as VaultFillFieldResult, type VaultItem as VaultItem, type VaultItemAction as VaultItemAction, From 3c6a789765fef9a92606e261273b4ae58c96e314 Mon Sep 17 00:00:00 2001 From: "kernel-internal[bot]" <260533166+kernel-internal[bot]@users.noreply.github.com> Date: Mon, 14 Sep 2026 20:28:29 +0000 Subject: [PATCH 7/9] feat: Accept a workload intent and use it to widen vendor coverage Stainless-Generated-From: 3a0e3c8c63bea644588e45a9e890602643d2e50b --- .../config-registry/config-registry.ts | 36 +++++++++++++++++++ .../config-registry/config-registry.test.ts | 1 + 2 files changed, 37 insertions(+) diff --git a/src/resources/config-registry/config-registry.ts b/src/resources/config-registry/config-registry.ts index 88cae73..11a2933 100644 --- a/src/resources/config-registry/config-registry.ts +++ b/src/resources/config-registry/config-registry.ts @@ -160,6 +160,20 @@ export interface ConfigRegistryResponse { * nothing applicable was observed or no notes exist. */ guidance?: string | null; + + /** + * How far the workload pass got, when an intent was supplied and a pass ran. A run + * outcome rather than advice, so it is reported whether or not any guidance could + * be assembled. Null when no intent was supplied or no pass ran. + */ + workload_outcome?: + | 'completed' + | 'turn_limit' + | 'auth_required' + | 'payment_required' + | 'blocked' + | 'error' + | null; } export interface Evidence { @@ -509,6 +523,17 @@ export interface ResolveRequest { * Kernel uses its default country selection. */ allowed_proxy_countries?: Array; + + /** + * Plain-language description of the workload you intend to run against this + * target, in a sentence or two. Requires an https target, because the pass treats + * any non-HTTPS destination as off-site and will not drive an http one. Kernel + * uses it to drive the browser further into the site, where it can observe + * protections that only appear once a session interacts. When this target already + * has a verified configuration, the run confirms that one instead of re-deriving + * the whole matrix, so supplying an intent narrows what can be recommended. + */ + intent?: string; } export interface Target { @@ -565,6 +590,17 @@ export interface ConfigRegistryResolveParams { * Kernel uses its default country selection. */ allowed_proxy_countries?: Array; + + /** + * Plain-language description of the workload you intend to run against this + * target, in a sentence or two. Requires an https target, because the pass treats + * any non-HTTPS destination as off-site and will not drive an http one. Kernel + * uses it to drive the browser further into the site, where it can observe + * protections that only appear once a session interacts. When this target already + * has a verified configuration, the run confirms that one instead of re-deriving + * the whole matrix, so supplying an intent narrows what can be recommended. + */ + intent?: string; } ConfigRegistry.Analyses = Analyses; diff --git a/tests/api-resources/config-registry/config-registry.test.ts b/tests/api-resources/config-registry/config-registry.test.ts index abd719e..bac78bb 100644 --- a/tests/api-resources/config-registry/config-registry.test.ts +++ b/tests/api-resources/config-registry/config-registry.test.ts @@ -74,6 +74,7 @@ describe('resource configRegistry', () => { const response = await client.configRegistry.resolve({ url: 'https://example.com', allowed_proxy_countries: ['US'], + intent: 'search for a black hoodie and add it to the cart', }); }); }); From d2cf7fff8e38b84fee64733442cf8287c3ae9693 Mon Sep 17 00:00:00 2001 From: "kernel-internal[bot]" <260533166+kernel-internal[bot]@users.noreply.github.com> Date: Mon, 14 Sep 2026 22:17:32 +0000 Subject: [PATCH 8/9] feat: Honor managed auth browser regions Stainless-Generated-From: 195783bdc666c2eb3bf785fedea51c2a15e7fc02 --- src/resources/auth/connections.ts | 7 +++++++ tests/api-resources/auth/connections.test.ts | 2 ++ yarn.lock | 6 +++--- 3 files changed, 12 insertions(+), 3 deletions(-) diff --git a/src/resources/auth/connections.ts b/src/resources/auth/connections.ts index 78f603a..b34930a 100644 --- a/src/resources/auth/connections.ts +++ b/src/resources/auth/connections.ts @@ -904,6 +904,13 @@ export interface ManagedAuthBrowserConfig { */ proxy?: BrowsersAPI.BrowserProxyConfig; + /** + * Browser region. Omit on create to use us-east, on update to keep the current + * region, or on login to inherit it. Login overrides apply only to that login. + * Non-default regions require an eligible plan and organization access. + */ + region?: 'us-east' | 'eu-west' | 'ap-southeast'; + /** * Whether managed auth browser sessions use stealth mode. Defaults to true when * omitted. diff --git a/tests/api-resources/auth/connections.test.ts b/tests/api-resources/auth/connections.test.ts index af260de..23f871c 100644 --- a/tests/api-resources/auth/connections.test.ts +++ b/tests/api-resources/auth/connections.test.ts @@ -36,6 +36,7 @@ describe('resource connections', () => { mode: 'direct', name: 'x', }, + region: 'us-east', stealth: false, telemetry: { browser: { @@ -203,6 +204,7 @@ describe('resource connections', () => { mode: 'direct', name: 'x', }, + region: 'us-east', stealth: false, telemetry: { browser: { diff --git a/yarn.lock b/yarn.lock index 4e6679d..032986a 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1235,9 +1235,9 @@ baseline-browser-mapping@^2.9.0: integrity sha512-B0xUquLkiGLgHhpPBqvl7GWegWBUNuujQ6kXd/r1U38ElPT6Ok8KZ8e+FpUGEc2ZoRQUzq/aUnaKFc/svWUGSg== brace-expansion@^2.0.2: - version "2.1.4" - resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.1.4.tgz#589dab11c0018d0366be64cd8bf12c8dbecc8326" - integrity sha512-hGfVzPxthbf3+2yjg/RBs60cB0FhqBS/zvdV/4wn4/BmN0bNMMHPc4V/BbFieqf1TKAGGAHnY4eSjajCl0f2Xg== + version "2.1.7" + resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.1.7.tgz#14ea3836731823bb24740225ea43b941b436f9d1" + integrity sha512-uZbew1NqdmPDTMJ8ah1y+b+9QEJrfkXFk3RcTQw3X0jW/xRUvFKsg1CfQdSYGdTbXZWExtU3J3ccxtnfw1Fi0g== dependencies: balanced-match "^1.0.0" From 987466e65fc912f6c502151d0d4d83f9deac5804 Mon Sep 17 00:00:00 2001 From: "kernel-internal[bot]" <260533166+kernel-internal[bot]@users.noreply.github.com> Date: Mon, 14 Sep 2026 22:22:07 +0000 Subject: [PATCH 9/9] release: 0.102.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 14 ++++++++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 17 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 31cc64e..9cd82e3 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.101.0" + ".": "0.102.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 95eb213..2ae7eeb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,19 @@ # Changelog +## [0.102.0](https://github.com/kernel/kernel-node-sdk/compare/v0.101.0...v0.102.0) (2026-09-14) + + +### Features + +* Accept a workload intent and use it to widen vendor coverage ([3c6a789](https://github.com/kernel/kernel-node-sdk/commit/3c6a789765fef9a92606e261273b4ae58c96e314)) +* Add guarded vault card fill operations ([d77b170](https://github.com/kernel/kernel-node-sdk/commit/d77b170936a96eb79327b189d05f2c8f1f0737c3)) +* Add single-use AgentCard prepare_checkout for Square ([f6718d4](https://github.com/kernel/kernel-node-sdk/commit/f6718d4fb93818147fb51b53545fc1327294d5d2)) +* Allow replacing AgentCard cards after unknown creates ([848944b](https://github.com/kernel/kernel-node-sdk/commit/848944b1ce0eb21f58700d41ed82b5121201a3ee)) +* Document punctuation key sequences ([a008dfb](https://github.com/kernel/kernel-node-sdk/commit/a008dfbe12ab150df7154f28127175e4ceee3816)) +* Honor managed auth browser regions ([d2cf7ff](https://github.com/kernel/kernel-node-sdk/commit/d2cf7fff8e38b84fee64733442cf8287c3ae9693)) +* Reapply vendor guidance recommendations ([0fdcce8](https://github.com/kernel/kernel-node-sdk/commit/0fdcce80cec36d682f295d278ae88b5e4877560b)) +* Report proxy-restricted targets from config registry lookup ([a57d992](https://github.com/kernel/kernel-node-sdk/commit/a57d992925092ebce6ba6e18fbb86844edfb67f5)) + ## [0.101.0](https://github.com/kernel/kernel-node-sdk/compare/v0.100.0...v0.101.0) (2026-09-11) diff --git a/package.json b/package.json index 63ca6b1..e3efa4e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@onkernel/sdk", - "version": "0.101.0", + "version": "0.102.0", "description": "The official TypeScript library for the Kernel API", "author": "Kernel <>", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index bdc4cd8..17edf17 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '0.101.0'; // x-release-please-version +export const VERSION = '0.102.0'; // x-release-please-version