From ec63b0146054357d65e420f148a1eb980bd051b0 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:05:32 +0000 Subject: [PATCH 1/4] feat: Add single-use AgentCard prepare_checkout for Square Stainless-Generated-From: 346bb4636296ff00e56612fa322103def0305257 --- api.md | 4 + shared/constant/constants.go | 3 - vaultitem.go | 268 +++++++++++++++++++++++++++++------ vaultitem_test.go | 6 +- 4 files changed, 229 insertions(+), 52 deletions(-) diff --git a/api.md b/api.md index bfe76e2..44f641a 100644 --- a/api.md +++ b/api.md @@ -492,13 +492,17 @@ Methods: Params Types: +- kernel.AuthorizeVaultItemOperationRequestParam - kernel.CardVaultItemSpecUnionParam - kernel.FillVaultItemOperationRequestParam +- kernel.PrepareCheckoutVaultItemOperationRequestParam - kernel.VaultCardFillFieldUnionParam +- kernel.VaultCheckoutContextParam Response Types: - kernel.AgentcardCheckoutAuthorization +- kernel.AgentcardCheckoutPreparation - kernel.CardVaultItemSpecUnion - kernel.CardVaultItemStateUnion - kernel.FillVaultItemOperationResult diff --git a/shared/constant/constants.go b/shared/constant/constants.go index d6d6e59..adb4ad2 100644 --- a/shared/constant/constants.go +++ b/shared/constant/constants.go @@ -21,7 +21,6 @@ func ValueOf[T Constant[T]]() T { type Agentcard string // Always "agentcard" type APICall string // Always "api_call" type AppVersionSummary string // Always "app_version_summary" -type Authorize string // Always "authorize" type AutofillTrigger string // Always "Autofill.trigger" type AwsUsEast1a string // Always "aws.us-east-1a" type BrowserCancelDownload string // Always "Browser.cancelDownload" @@ -133,7 +132,6 @@ type Wallet string // Always "wallet" func (c Agentcard) Default() Agentcard { return "agentcard" } func (c APICall) Default() APICall { return "api_call" } func (c AppVersionSummary) Default() AppVersionSummary { return "app_version_summary" } -func (c Authorize) Default() Authorize { return "authorize" } func (c AutofillTrigger) Default() AutofillTrigger { return "Autofill.trigger" } func (c AwsUsEast1a) Default() AwsUsEast1a { return "aws.us-east-1a" } func (c BrowserCancelDownload) Default() BrowserCancelDownload { return "Browser.cancelDownload" } @@ -267,7 +265,6 @@ func (c Wallet) Default() Wallet { return "wallet" } func (c Agentcard) MarshalJSON() ([]byte, error) { return marshalString(c) } func (c APICall) MarshalJSON() ([]byte, error) { return marshalString(c) } func (c AppVersionSummary) MarshalJSON() ([]byte, error) { return marshalString(c) } -func (c Authorize) MarshalJSON() ([]byte, error) { return marshalString(c) } func (c AutofillTrigger) MarshalJSON() ([]byte, error) { return marshalString(c) } func (c AwsUsEast1a) MarshalJSON() ([]byte, error) { return marshalString(c) } func (c BrowserCancelDownload) MarshalJSON() ([]byte, error) { return marshalString(c) } diff --git a/vaultitem.go b/vaultitem.go index 8289577..5eb19aa 100644 --- a/vaultitem.go +++ b/vaultitem.go @@ -95,10 +95,10 @@ func (r *VaultItemService) List(ctx context.Context, idOrName string, opts ...op } // 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. func (r *VaultItemService) Delete(ctx context.Context, key string, body VaultItemDeleteParams, opts ...option.RequestOption) (err error) { opts = slices.Concat(r.Options, opts) opts = append([]option.RequestOption{option.WithHeader("Accept", "*/*")}, opts...) @@ -134,10 +134,13 @@ func (r *VaultItemService) Events(ctx context.Context, key string, params VaultI // 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 @@ -275,6 +278,99 @@ const ( AgentcardCheckoutAuthorizationChargedKindNone AgentcardCheckoutAuthorizationChargedKind = "none" ) +// 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. +type AgentcardCheckoutPreparation struct { + BrowserID string `json:"browser_id" api:"required"` + CreatedAt time.Time `json:"created_at" api:"required" format:"date-time"` + // Any of "production", "sandbox". + Environment AgentcardCheckoutPreparationEnvironment `json:"environment" api:"required"` + MerchantOrigin string `json:"merchant_origin" api:"required"` + // 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. + // + // Any of "creating", "awaiting_approval", "ready", "consumed", "cancelled", + // "expired", "unknown". + Status AgentcardCheckoutPreparationStatus `json:"status" api:"required"` + ID string `json:"id"` + ApprovalURL string `json:"approval_url" format:"uri"` + // 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. + ExpiresAt time.Time `json:"expires_at" format:"date-time"` + // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. + JSON struct { + BrowserID respjson.Field + CreatedAt respjson.Field + Environment respjson.Field + MerchantOrigin respjson.Field + Status respjson.Field + ID respjson.Field + ApprovalURL respjson.Field + ExpiresAt respjson.Field + ExtraFields map[string]respjson.Field + raw string + } `json:"-"` +} + +// Returns the unmodified JSON received from the API +func (r AgentcardCheckoutPreparation) RawJSON() string { return r.JSON.raw } +func (r *AgentcardCheckoutPreparation) UnmarshalJSON(data []byte) error { + return apijson.UnmarshalRoot(data, r) +} + +type AgentcardCheckoutPreparationEnvironment string + +const ( + AgentcardCheckoutPreparationEnvironmentProduction AgentcardCheckoutPreparationEnvironment = "production" + AgentcardCheckoutPreparationEnvironmentSandbox AgentcardCheckoutPreparationEnvironment = "sandbox" +) + +// 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. +type AgentcardCheckoutPreparationStatus string + +const ( + AgentcardCheckoutPreparationStatusCreating AgentcardCheckoutPreparationStatus = "creating" + AgentcardCheckoutPreparationStatusAwaitingApproval AgentcardCheckoutPreparationStatus = "awaiting_approval" + AgentcardCheckoutPreparationStatusReady AgentcardCheckoutPreparationStatus = "ready" + AgentcardCheckoutPreparationStatusConsumed AgentcardCheckoutPreparationStatus = "consumed" + AgentcardCheckoutPreparationStatusCancelled AgentcardCheckoutPreparationStatus = "cancelled" + AgentcardCheckoutPreparationStatusExpired AgentcardCheckoutPreparationStatus = "expired" + AgentcardCheckoutPreparationStatusUnknown AgentcardCheckoutPreparationStatus = "unknown" +) + +// 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. +// +// The property Type is required. +type AuthorizeVaultItemOperationRequestParam struct { + // Any of "authorize". + Type AuthorizeVaultItemOperationRequestType `json:"type,omitzero" api:"required"` + paramObj +} + +func (r AuthorizeVaultItemOperationRequestParam) MarshalJSON() (data []byte, err error) { + type shadow AuthorizeVaultItemOperationRequestParam + return param.MarshalObject(r, (*shadow)(&r)) +} +func (r *AuthorizeVaultItemOperationRequestParam) UnmarshalJSON(data []byte) error { + return apijson.UnmarshalRoot(data, r) +} + +type AuthorizeVaultItemOperationRequestType string + +const ( + AuthorizeVaultItemOperationRequestTypeAuthorize AuthorizeVaultItemOperationRequestType = "authorize" +) + // CardVaultItemSpecUnion contains all possible properties and values from // [CardVaultItemSpecLink], [CardVaultItemSpecAgentcard]. // @@ -825,7 +921,9 @@ type CardVaultItemStateUnion struct { StatusReason string `json:"status_reason"` // This field is from variant [CardVaultItemStateAgentcard]. Authorization AgentcardCheckoutAuthorization `json:"authorization"` - JSON struct { + // This field is from variant [CardVaultItemStateAgentcard]. + Preparation AgentcardCheckoutPreparation `json:"preparation"` + JSON struct { Provider respjson.Field Status respjson.Field Aliases respjson.Field @@ -833,6 +931,7 @@ type CardVaultItemStateUnion struct { Masks respjson.Field StatusReason respjson.Field Authorization respjson.Field + Preparation respjson.Field raw string } `json:"-"` } @@ -957,22 +1056,29 @@ func (r *CardVaultItemStateLinkMasks) UnmarshalJSON(data []byte) error { type CardVaultItemStateAgentcard struct { Provider constant.Agentcard `json:"provider" default:"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. // - // Any of "requested", "ready", "pending_approval", "degraded", - // "recovery_required". + // Any of "requested", "ready", "preparing", "ready_to_submit", "pending_approval", + // "consumed", "stopped", "outcome_unknown", "degraded", "recovery_required". Status string `json:"status" api:"required"` Aliases VaultCardAliases `json:"aliases"` // The in-flight or most recent checkout authorization. Present while a checkout is // pending approval and after it settles. Authorization AgentcardCheckoutAuthorization `json:"authorization"` Masks CardVaultItemStateAgentcardMasks `json:"masks"` - StatusReason string `json:"status_reason"` + // 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 AgentcardCheckoutPreparation `json:"preparation"` + StatusReason string `json:"status_reason"` // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. JSON struct { Provider respjson.Field @@ -980,6 +1086,7 @@ type CardVaultItemStateAgentcard struct { Aliases respjson.Field Authorization respjson.Field Masks respjson.Field + Preparation respjson.Field StatusReason respjson.Field ExtraFields map[string]respjson.Field raw string @@ -1114,6 +1221,40 @@ const ( FillVaultItemOperationResultTypeFill FillVaultItemOperationResultType = "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. +// +// The properties Checkout, Type are required. +type PrepareCheckoutVaultItemOperationRequestParam struct { + // 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 VaultCheckoutContextParam `json:"checkout,omitzero" api:"required"` + // Any of "prepare_checkout". + Type PrepareCheckoutVaultItemOperationRequestType `json:"type,omitzero" api:"required"` + paramObj +} + +func (r PrepareCheckoutVaultItemOperationRequestParam) MarshalJSON() (data []byte, err error) { + type shadow PrepareCheckoutVaultItemOperationRequestParam + return param.MarshalObject(r, (*shadow)(&r)) +} +func (r *PrepareCheckoutVaultItemOperationRequestParam) UnmarshalJSON(data []byte) error { + return apijson.UnmarshalRoot(data, r) +} + +type PrepareCheckoutVaultItemOperationRequestType string + +const ( + PrepareCheckoutVaultItemOperationRequestTypePrepareCheckout PrepareCheckoutVaultItemOperationRequestType = "prepare_checkout" +) + type VaultCardAliases struct { Cvc string `json:"cvc" api:"required"` ExpMonth string `json:"exp_month" api:"required"` @@ -1269,6 +1410,42 @@ func init() { ) } +// 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. +// +// The properties BrowserID, Environment, MerchantOrigin are required. +type VaultCheckoutContextParam struct { + // Active browser session with this vault bound to it. + BrowserID string `json:"browser_id" api:"required"` + // Square environment, independent of the AgentCard credential mode. + // + // Any of "production", "sandbox". + Environment VaultCheckoutContextEnvironment `json:"environment,omitzero" api:"required"` + // Canonical HTTPS origin of the top-level merchant document, not the Square + // iframe. HTTP localhost is accepted for tests. + MerchantOrigin string `json:"merchant_origin" api:"required"` + paramObj +} + +func (r VaultCheckoutContextParam) MarshalJSON() (data []byte, err error) { + type shadow VaultCheckoutContextParam + return param.MarshalObject(r, (*shadow)(&r)) +} +func (r *VaultCheckoutContextParam) UnmarshalJSON(data []byte) error { + return apijson.UnmarshalRoot(data, r) +} + +// Square environment, independent of the AgentCard credential mode. +type VaultCheckoutContextEnvironment string + +const ( + VaultCheckoutContextEnvironmentProduction VaultCheckoutContextEnvironment = "production" + VaultCheckoutContextEnvironmentSandbox VaultCheckoutContextEnvironment = "sandbox" +) + type VaultFillFieldResult struct { // Zero-based index into the request fields array. Index int64 `json:"index" api:"required"` @@ -1553,7 +1730,9 @@ type VaultItemUnionState struct { Masks VaultItemUnionStateMasks `json:"masks"` // This field is from variant [CardVaultItemStateUnion]. Authorization AgentcardCheckoutAuthorization `json:"authorization"` - JSON struct { + // This field is from variant [CardVaultItemStateUnion]. + Preparation AgentcardCheckoutPreparation `json:"preparation"` + JSON struct { Provider respjson.Field Status respjson.Field StatusReason respjson.Field @@ -1562,6 +1741,7 @@ type VaultItemUnionState struct { Domains respjson.Field Masks respjson.Field Authorization respjson.Field + Preparation respjson.Field raw string } `json:"-"` } @@ -1661,7 +1841,7 @@ func (r *VaultItemWalletAvailableExpansion) UnmarshalJSON(data []byte) error { // invoking it through the item operations endpoint. type VaultItemWalletAvailableOperation struct { Description string `json:"description" api:"required"` - // Any of "authorize", "fill". + // Any of "authorize", "prepare_checkout", "fill". Type string `json:"type" api:"required"` // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. JSON struct { @@ -1758,7 +1938,7 @@ func (r *VaultItemCardAvailableExpansion) UnmarshalJSON(data []byte) error { // invoking it through the item operations endpoint. type VaultItemCardAvailableOperation struct { Description string `json:"description" api:"required"` - // Any of "authorize", "fill". + // Any of "authorize", "prepare_checkout", "fill". Type string `json:"type" api:"required"` // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. JSON struct { @@ -2246,7 +2426,9 @@ type VaultItemOperationResponseUnionState struct { Masks VaultItemOperationResponseUnionStateMasks `json:"masks"` // This field is from variant [CardVaultItemStateUnion]. Authorization AgentcardCheckoutAuthorization `json:"authorization"` - JSON struct { + // This field is from variant [CardVaultItemStateUnion]. + Preparation AgentcardCheckoutPreparation `json:"preparation"` + JSON struct { Provider respjson.Field Status respjson.Field StatusReason respjson.Field @@ -2255,6 +2437,7 @@ type VaultItemOperationResponseUnionState struct { Domains respjson.Field Masks respjson.Field Authorization respjson.Field + Preparation respjson.Field raw string } `json:"-"` } @@ -2357,7 +2540,7 @@ func (r *VaultItemOperationResponseWalletVaultItemAvailableExpansion) UnmarshalJ // invoking it through the item operations endpoint. type VaultItemOperationResponseWalletVaultItemAvailableOperation struct { Description string `json:"description" api:"required"` - // Any of "authorize", "fill". + // Any of "authorize", "prepare_checkout", "fill". Type string `json:"type" api:"required"` // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. JSON struct { @@ -2459,7 +2642,7 @@ func (r *VaultItemOperationResponseCardVaultItemAvailableExpansion) UnmarshalJSO // invoking it through the item operations endpoint. type VaultItemOperationResponseCardVaultItemAvailableOperation struct { Description string `json:"description" api:"required"` - // Any of "authorize", "fill". + // Any of "authorize", "prepare_checkout", "fill". Type string `json:"type" api:"required"` // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. JSON struct { @@ -3026,7 +3209,19 @@ type VaultItemPerformOperationParams struct { // // This field is a request body variant, only one variant field can be set. - OfAuthorize *VaultItemPerformOperationParamsBodyAuthorize `json:",inline"` + // 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. + OfAuthorize *AuthorizeVaultItemOperationRequestParam `json:",inline"` + // This field is a request body variant, only one variant field can be set. 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. + OfPrepareCheckout *PrepareCheckoutVaultItemOperationRequestParam `json:",inline"` // This field is a request body variant, only one variant field can be set. 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 @@ -3060,33 +3255,12 @@ type VaultItemPerformOperationParams struct { } func (u VaultItemPerformOperationParams) MarshalJSON() ([]byte, error) { - return param.MarshalUnion(u, u.OfAuthorize, u.OfFill) + return param.MarshalUnion(u, u.OfAuthorize, u.OfPrepareCheckout, u.OfFill) } func (r *VaultItemPerformOperationParams) UnmarshalJSON(data []byte) error { return apijson.UnmarshalRoot(data, r) } -func NewVaultItemPerformOperationParamsBodyAuthorize() VaultItemPerformOperationParamsBodyAuthorize { - return VaultItemPerformOperationParamsBodyAuthorize{ - Type: "authorize", - } -} - -// This struct has a constant value, construct it with -// [NewVaultItemPerformOperationParamsBodyAuthorize]. -type VaultItemPerformOperationParamsBodyAuthorize struct { - Type constant.Authorize `json:"type" default:"authorize"` - paramObj -} - -func (r VaultItemPerformOperationParamsBodyAuthorize) MarshalJSON() (data []byte, err error) { - type shadow VaultItemPerformOperationParamsBodyAuthorize - return param.MarshalObject(r, (*shadow)(&r)) -} -func (r *VaultItemPerformOperationParamsBodyAuthorize) UnmarshalJSON(data []byte) error { - return apijson.UnmarshalRoot(data, r) -} - type VaultItemUpsertParams struct { IDOrName string `path:"id_or_name" api:"required" json:"-"` diff --git a/vaultitem_test.go b/vaultitem_test.go index f1a650c..74f9aa8 100644 --- a/vaultitem_test.go +++ b/vaultitem_test.go @@ -208,8 +208,10 @@ func TestVaultItemPerformOperationWithOptionalParams(t *testing.T) { context.TODO(), "key", kernel.VaultItemPerformOperationParams{ - IDOrName: "id_or_name", - OfAuthorize: &kernel.VaultItemPerformOperationParamsBodyAuthorize{}, + IDOrName: "id_or_name", + OfAuthorize: &kernel.AuthorizeVaultItemOperationRequestParam{ + Type: kernel.AuthorizeVaultItemOperationRequestTypeAuthorize, + }, }, ) if err != nil { From 7c60d81c9fa15cc9116c6838a9ba173e8e95405a 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:27:52 +0000 Subject: [PATCH 2/4] feat: Accept a workload intent and use it to widen vendor coverage Stainless-Generated-From: 30218917adecd9a2b68e4647450248d32128248f --- configregistry.go | 42 ++++++++++++++++++++++++++++++++++++------ configregistry_test.go | 1 + 2 files changed, 37 insertions(+), 6 deletions(-) diff --git a/configregistry.go b/configregistry.go index a13453e..06afb73 100644 --- a/configregistry.go +++ b/configregistry.go @@ -201,14 +201,22 @@ type ConfigRegistryResponse struct { // useful without a configuration. Not verified against this target. Null when // nothing applicable was observed or no notes exist. Guidance string `json:"guidance" api:"nullable"` + // 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. + // + // Any of "completed", "turn_limit", "auth_required", "payment_required", + // "blocked", "error". + WorkloadOutcome ConfigRegistryResponseWorkloadOutcome `json:"workload_outcome" api:"nullable"` // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. JSON struct { - Analysis respjson.Field - Recommendation respjson.Field - Target respjson.Field - Guidance respjson.Field - ExtraFields map[string]respjson.Field - raw string + Analysis respjson.Field + Recommendation respjson.Field + Target respjson.Field + Guidance respjson.Field + WorkloadOutcome respjson.Field + ExtraFields map[string]respjson.Field + raw string } `json:"-"` } @@ -218,6 +226,20 @@ func (r *ConfigRegistryResponse) UnmarshalJSON(data []byte) error { return apijson.UnmarshalRoot(data, r) } +// 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. +type ConfigRegistryResponseWorkloadOutcome string + +const ( + ConfigRegistryResponseWorkloadOutcomeCompleted ConfigRegistryResponseWorkloadOutcome = "completed" + ConfigRegistryResponseWorkloadOutcomeTurnLimit ConfigRegistryResponseWorkloadOutcome = "turn_limit" + ConfigRegistryResponseWorkloadOutcomeAuthRequired ConfigRegistryResponseWorkloadOutcome = "auth_required" + ConfigRegistryResponseWorkloadOutcomePaymentRequired ConfigRegistryResponseWorkloadOutcome = "payment_required" + ConfigRegistryResponseWorkloadOutcomeBlocked ConfigRegistryResponseWorkloadOutcome = "blocked" + ConfigRegistryResponseWorkloadOutcomeError ConfigRegistryResponseWorkloadOutcome = "error" +) + type Evidence struct { Accessed int64 `json:"accessed" api:"required"` Blocked int64 `json:"blocked" api:"required"` @@ -872,6 +894,14 @@ const ( type ResolveRequestParam struct { // Public HTTP(S) URL to refresh. URL string `json:"url" api:"required" format:"uri"` + // 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 param.Opt[string] `json:"intent,omitzero"` // ISO 3166 country codes Kernel may use when searching for or returning a proxy // configuration. Kernel may test a subset of allowed countries. When omitted, // Kernel uses its default country selection. diff --git a/configregistry_test.go b/configregistry_test.go index 768f3b8..dab9fd5 100644 --- a/configregistry_test.go +++ b/configregistry_test.go @@ -87,6 +87,7 @@ func TestConfigRegistryResolveWithOptionalParams(t *testing.T) { ResolveRequest: kernel.ResolveRequestParam{ URL: "https://example.com", AllowedProxyCountries: []string{"US"}, + Intent: kernel.String("search for a black hoodie and add it to the cart"), }, }) if err != nil { From 2e5c06117d8597f1808b3bd43a4df746a19fe8c7 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:16:52 +0000 Subject: [PATCH 3/4] feat: Honor managed auth browser regions Stainless-Generated-From: d8cab166d7ef7ee1463c88655022ce5e30362b67 --- authconnection.go | 24 ++++++++++++++++++++++++ authconnection_test.go | 3 +++ 2 files changed, 27 insertions(+) diff --git a/authconnection.go b/authconnection.go index 65af910..eece8c8 100644 --- a/authconnection.go +++ b/authconnection.go @@ -952,6 +952,12 @@ type ManagedAuthBrowserConfig struct { // the default from stealth, or on update and login to preserve or inherit the // connection default. Proxy BrowserProxyConfig `json:"proxy"` + // 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. + // + // Any of "us-east", "eu-west", "ap-southeast". + Region ManagedAuthBrowserConfigRegion `json:"region"` // Whether managed auth browser sessions use stealth mode. Defaults to true when // omitted. Stealth bool `json:"stealth"` @@ -960,6 +966,7 @@ type ManagedAuthBrowserConfig struct { // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. JSON struct { Proxy respjson.Field + Region respjson.Field Stealth respjson.Field Telemetry respjson.Field ExtraFields map[string]respjson.Field @@ -983,6 +990,17 @@ func (r ManagedAuthBrowserConfig) ToParam() ManagedAuthBrowserConfigParam { return param.Override[ManagedAuthBrowserConfigParam](json.RawMessage(r.RawJSON())) } +// 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. +type ManagedAuthBrowserConfigRegion string + +const ( + ManagedAuthBrowserConfigRegionUsEast ManagedAuthBrowserConfigRegion = "us-east" + ManagedAuthBrowserConfigRegionEuWest ManagedAuthBrowserConfigRegion = "eu-west" + ManagedAuthBrowserConfigRegionApSoutheast ManagedAuthBrowserConfigRegion = "ap-southeast" +) + // Browser telemetry configuration using the same semantics as browser create. type ManagedAuthBrowserConfigTelemetry struct { // Per-category capture flags. The operational categories (control, connection, @@ -1101,6 +1119,12 @@ type ManagedAuthBrowserConfigParam struct { // the default from stealth, or on update and login to preserve or inherit the // connection default. Proxy BrowserProxyConfigParam `json:"proxy,omitzero"` + // 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. + // + // Any of "us-east", "eu-west", "ap-southeast". + Region ManagedAuthBrowserConfigRegion `json:"region,omitzero"` paramObj } diff --git a/authconnection_test.go b/authconnection_test.go index 0017685..1e6fcff 100644 --- a/authconnection_test.go +++ b/authconnection_test.go @@ -38,6 +38,7 @@ func TestAuthConnectionNewWithOptionalParams(t *testing.T) { Mode: kernel.BrowserProxyModeDirect, Name: kernel.String("x"), }, + Region: kernel.ManagedAuthBrowserConfigRegionUsEast, Stealth: kernel.Bool(false), Telemetry: kernel.ManagedAuthBrowserConfigTelemetryParam{ Browser: kernel.BrowserTelemetryCategoriesConfigParam{ @@ -209,6 +210,7 @@ func TestAuthConnectionUpdateWithOptionalParams(t *testing.T) { Mode: kernel.BrowserProxyModeDirect, Name: kernel.String("x"), }, + Region: kernel.ManagedAuthBrowserConfigRegionUsEast, Stealth: kernel.Bool(false), Telemetry: kernel.ManagedAuthBrowserConfigTelemetryParam{ Browser: kernel.BrowserTelemetryCategoriesConfigParam{ @@ -407,6 +409,7 @@ func TestAuthConnectionLoginWithOptionalParams(t *testing.T) { Mode: kernel.BrowserProxyModeDirect, Name: kernel.String("x"), }, + Region: kernel.ManagedAuthBrowserConfigRegionUsEast, Stealth: kernel.Bool(false), Telemetry: kernel.ManagedAuthBrowserConfigTelemetryParam{ Browser: kernel.BrowserTelemetryCategoriesConfigParam{ From cfedfb8ef1fe3164d9739530de48c633ca5528f0 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:21:46 +0000 Subject: [PATCH 4/4] release: 0.103.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 9 +++++++++ README.md | 2 +- internal/version.go | 2 +- 4 files changed, 12 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index f70d997..508a708 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.102.0" + ".": "0.103.0" } \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 43e7895..c4ced4e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## [0.103.0](https://github.com/kernel/kernel-go-sdk/compare/v0.102.0...v0.103.0) (2026-09-14) + + +### Features + +* Accept a workload intent and use it to widen vendor coverage ([7c60d81](https://github.com/kernel/kernel-go-sdk/commit/7c60d81c9fa15cc9116c6838a9ba173e8e95405a)) +* Add single-use AgentCard prepare_checkout for Square ([ec63b01](https://github.com/kernel/kernel-go-sdk/commit/ec63b0146054357d65e420f148a1eb980bd051b0)) +* Honor managed auth browser regions ([2e5c061](https://github.com/kernel/kernel-go-sdk/commit/2e5c06117d8597f1808b3bd43a4df746a19fe8c7)) + ## [0.102.0](https://github.com/kernel/kernel-go-sdk/compare/v0.101.0...v0.102.0) (2026-09-13) diff --git a/README.md b/README.md index 71b80ce..659fd19 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Or to pin the version: ```sh -go get -u 'github.com/kernel/kernel-go-sdk@v0.102.0' +go get -u 'github.com/kernel/kernel-go-sdk@v0.103.0' ``` diff --git a/internal/version.go b/internal/version.go index bb1f767..279dc3e 100644 --- a/internal/version.go +++ b/internal/version.go @@ -2,4 +2,4 @@ package internal -const PackageVersion = "0.102.0" // x-release-please-version +const PackageVersion = "0.103.0" // x-release-please-version