@weaccelerateinc/agent-sdk 0.10.3 → 0.12.0

package/host-adapter.js

@@ -1,7 +1,7 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { createHash, randomUUID } from 'node:crypto';
 import { AccelerateError } from './index.js';
-import { validateCheckoutDiagnostics } from './checkout-diagnostics.js';
+import { validateCheckoutDiagnostics, validateCheckoutReconciliation } from './checkout-diagnostics.js';
 import { renderPrivateChatState, privateChatProgress } from './private-chat.js';
 
 const ID = /^mcs_[A-Za-z0-9_-]{43}$/;
@@ -9,9 +9,9 @@ const OWNER = /^[A-Za-z0-9_.:-]{1,500}$/;
 const MESSAGE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/;
 const RECOVER = new Set(['accelerate_checkout_status', 'accelerate_checkout_cancel', 'private_state', 'private_cancel']);
 const TERMINAL = new Set(['cancelled', 'expired', 'failed']);
-const STATUS_ORDER = new Map(['wallet_required', 'selection_ready', 'details_ready', 'approval_required', 'approved', 'ready_for_submit'].map((status, index) => [status, index]));
+const STATUS_ORDER = new Map(['wallet_required', 'selection_ready', 'details_ready', 'approval_required', 'approved', 'ready_for_submit', 'final_click_armed'].map((status, index) => [status, index]));
 const STAGES = new Set(['not_started', 'identity_required', 'otp_required', 'selection_required', 'preparing_checkout', 'approval_required', 'cvv_required', 'verified', 'review_delivery_required', 'review_delivered', 'approved_for_submit', 'closed']);
-const STATUSES = new Set(['wallet_required', 'selection_ready', 'details_ready', 'approval_required', 'approved', 'ready_for_submit', 'cancelled', 'expired', 'failed', 'submit_attempted', 'outcome_unknown']);
+const STATUSES = new Set(['wallet_required', 'selection_ready', 'details_ready', 'approval_required', 'approved', 'ready_for_submit', 'final_click_armed', 'cancelled', 'expired', 'failed', 'submit_attempted', 'outcome_unknown']);
 const object = value => value && typeof value === 'object' && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
 const check = (condition, code = 'invalid_input') => { if (!condition) throw new AccelerateError(code); };
 const clone = value => structuredClone(value);
@@ -50,7 +50,7 @@ function safeText(value, max = 10000) {
   return value;
 }
 function safeCheckout(value) {
-  exact(value, ['id', 'status', 'revision', 'expires_at', 'retry_safe', 'payment_confirmed'], ['purpose', 'submit_allowed', 'approval_policy', 'purchase_approved', 'fill_after_verification', 'card', 'address', 'quote', 'submit_expires_at', 'diagnostics'], 'invalid_response');
+  exact(value, ['id', 'status', 'revision', 'expires_at', 'retry_safe', 'payment_confirmed'], ['purpose', 'submit_allowed', 'approval_policy', 'purchase_approved', 'fill_after_verification', 'card', 'address', 'quote', 'submit_expires_at', 'diagnostics', 'reconciliation', 'final_click_actor', 'submit_actor'], 'invalid_response');
   check(ID.test(value.id) && STATUSES.has(value.status) && Number.isSafeInteger(value.revision) && value.revision >= 0 && value.retry_safe === false && value.payment_confirmed === false && validDate(value.expires_at), 'invalid_response');
   if (value.card !== undefined) {
     exact(value.card, ['brand', 'last4'], [], 'invalid_response');
@@ -71,8 +71,12 @@ function safeCheckout(value) {
   if (value.submit_expires_at !== undefined) check(validDate(value.submit_expires_at), 'invalid_response');
   if (value.submit_allowed !== undefined) check(typeof value.submit_allowed === 'boolean', 'invalid_response');
   if (value.fill_after_verification !== undefined) check(value.fill_after_verification === true && value.approval_policy === 'after_fill' && ['purchase', 'sandbox_fill_only'].includes(value.purpose), 'invalid_response');
+  if (value.final_click_actor !== undefined) check(value.final_click_actor === 'customer' && value.purpose === 'purchase', 'invalid_response');
+  if (value.submit_actor !== undefined) check(value.submit_actor === 'customer' && value.final_click_actor === 'customer' && ['submit_attempted', 'outcome_unknown'].includes(value.status), 'invalid_response');
+  if (value.status === 'submit_attempted' && value.purpose === 'purchase') check(value.submit_actor === 'customer', 'invalid_response');
   if (value.purchase_approved !== undefined) check(typeof value.purchase_approved === 'boolean', 'invalid_response');
   if (value.approval_policy !== undefined) check(value.approval_policy === 'after_fill' && typeof value.purchase_approved === 'boolean', 'invalid_response');
+  if (value.reconciliation !== undefined) { try { validateCheckoutReconciliation(value.reconciliation, value.status); } catch { check(false, 'invalid_response'); } }
   // The SDK owns detailed diagnostics validation. This projection keeps no URLs,
   // provider capabilities or data that could accidentally become an effect input.
   const result = clone(value);
@@ -212,7 +216,7 @@ export function createDurableCheckoutHost({ persistence, resolveContext } = {})
     }
     if (metadata.operation === 'accelerate_checkout_submit') {
       const checkout = active.record.attempt.checkout;
-      check(checkout?.purpose === 'purchase' && checkout.submit_allowed === true && checkout.status === 'ready_for_submit' && checkout.purchase_approved === true && active.record.attempt.private_stage === 'approved_for_submit' && validDate(checkout.submit_expires_at) && Date.parse(checkout.submit_expires_at) > Date.now() && metadata.revision === checkout.revision, 'submit_unavailable');
+      check(checkout?.purpose === 'purchase' && checkout.submit_allowed === true && checkout.final_click_actor === 'customer' && checkout.status === 'ready_for_submit' && checkout.purchase_approved === true && active.record.attempt.private_stage === 'approved_for_submit' && validDate(checkout.submit_expires_at) && Date.parse(checkout.submit_expires_at) > Date.now() && metadata.revision === checkout.revision, 'submit_unavailable');
     }
     const oneUse = ['accelerate_checkout_fill', 'accelerate_checkout_submit'].includes(metadata.operation);
     if (oneUse) {
@@ -296,6 +300,18 @@ export function createDurableCheckoutHost({ persistence, resolveContext } = {})
       check(MESSAGE.test(receipt.message_id) && validDate(receipt.sent_at) && Date.parse(receipt.sent_at) <= Date.now(), 'invalid_response');
       entry.receipt = clone(receipt); await commit(active); return Object.freeze(clone(receipt));
     }),
+    reconcilePrivateDelivery: (context, idempotencyKey, lookup) => locked(context, async (active, resolved) => {
+      check(/^accelerate-chat:[a-f0-9]{64}$/.test(idempotencyKey) && typeof lookup === 'function');
+      const entry = active.record.deliveries?.find(item => item.idempotency_key === idempotencyKey);
+      check(entry && active.record.attempt?.checkout_id, 'permission_denied');
+      if (entry.receipt) return Object.freeze(clone(entry.receipt));
+      // Only a trusted read-only journal lookup may be passed here. It must bind
+      // the exact owner, destination and prompt key; it must never send.
+      const receipt = await lookup(Object.freeze({ ...resolved }), idempotencyKey);
+      exact(receipt, ['message_id', 'sent_at'], [], 'invalid_response');
+      check(MESSAGE.test(receipt.message_id) && validDate(receipt.sent_at) && Date.parse(receipt.sent_at) <= Date.now(), 'invalid_response');
+      entry.receipt = clone(receipt); await commit(active); return Object.freeze(clone(receipt));
+    }),
     confirmBrowserCleanup: (context, checkoutId) => locked(context, async active => {
       check(active.record.attempt?.checkout_id === checkoutId && active.record.attempt.checkout?.diagnostics?.cleanup_status === 'confirmed', 'operation_conflict');
       active.record.attempt.cleanup_confirmed = true; await commit(active);

package/index.d.ts

@@ -1,13 +1,13 @@
 import type { BrowserOperation, BrowserResult } from './browser-operations.js';
-import type { CheckoutDiagnostics } from './checkout-diagnostics.js';
+import type { CheckoutDiagnostics, CheckoutReconciliation, CheckoutReconciliationState } from './checkout-diagnostics.js';
 export { checkoutDiagnosticsJsonSchema, validateCheckoutDiagnostics } from './checkout-diagnostics.js';
-export type { CheckoutDiagnostics, CheckoutDiagnosticStage, CheckoutDiagnosticAction, CheckoutCleanupStatus } from './checkout-diagnostics.js';
+export type { CheckoutDiagnostics, CheckoutDiagnosticStage, CheckoutDiagnosticAction, CheckoutCleanupStatus, CheckoutReconciliation, CheckoutReconciliationState } from './checkout-diagnostics.js';
 export type { BrowserOperation, BrowserResult, BrowserStep, BrowserCondition } from './browser-operations.js';
 
 export type CheckoutId = `mcs_${string}`;
 export type CheckoutPurpose = 'purchase' | 'sandbox_source_comparison' | 'sandbox_fill_only';
 export type CheckoutStatus = 'wallet_required' | 'selection_ready' | 'details_ready' | 'approval_required' |
-  'approved' | 'ready_for_submit' | 'cancelled' | 'expired' | 'failed' | 'submit_attempted' | 'outcome_unknown';
+  'approved' | 'ready_for_submit' | 'final_click_armed' | 'cancelled' | 'expired' | 'failed' | 'submit_attempted' | 'outcome_unknown';
 export interface RequestOptions { signal?: AbortSignal }
 export interface WaitForCheckout {
   /** Return on these states, or immediately on ready_for_submit or any terminal state. GET requests only. */
@@ -47,16 +47,40 @@ export interface Checkout {
   /** Explicit v2 policy acknowledged at creation; a later explicit quote arm lets private CVV continue
    * one fill under the backend lock. Does not authorize final submission. */
   fill_after_verification?: true;
+  /** Purchases only: the customer's own trusted backend/browser performs the physical final click. Accelerate never does. */
+  final_click_actor?: 'customer';
+  /** Present on submit_attempted (required for a purchase) and optionally on outcome_unknown, which cannot assert that a click happened. Never payment confirmation. */
+  submit_actor?: 'customer';
   card?: { last4: string | null; brand: string | null };
   address?: { label: string | null; city?: string | null; state?: string | null; postal_code_mask?: string | null };
   quote?: { checkout_origin: string; amount_cents: number; currency: 'USD' };
   submit_expires_at?: string;
+  /** Present once the client backend recorded the merchant's result. Absent on older services.
+   * This is the client's statement, not Accelerate's proof, so payment_confirmed stays false. */
+  reconciliation?: CheckoutReconciliation;
   retry_safe: false;
   payment_confirmed: false;
   /** Negotiated safe metadata; absent when connecting to an older service. */
   diagnostics?: CheckoutDiagnostics;
 }
 export interface CreatedCheckout extends Checkout { wallet_url?: string }
+export interface ReconciledCheckout extends Checkout { reconciliation: CheckoutReconciliation }
+/** Server only, after your backend checked the merchant's order system. Never model input.
+ * order_reference is stored only as a hash and is never returned. */
+export type CheckoutReconciliationRequest = {
+  state: 'confirmed';
+  order_reference: string;
+  /** Must equal the approved quote exactly. */
+  amount_cents: number;
+  currency: 'USD';
+  source: string;
+} | {
+  state: Exclude<CheckoutReconciliationState, 'confirmed'>;
+  order_reference?: string;
+  amount_cents?: number;
+  currency?: 'USD';
+  source: string;
+};
 /** Server-owned existing browser, resolved from the authenticated application's
  * durable browser record. Never accept this binding from model arguments.
  * The customer backend retains provider access; this is not private-from-creation custody. */
@@ -64,6 +88,16 @@ export interface BrowserUseBrowserBinding {
   provider: 'browser_use';
   browser_id: string;
   custody_mode: 'customer_backend_trusted';
+  /** Opt-in provider run binding from a durable authenticated owner mapping. Never model input. */
+  provenance?: BrowserUseRunProvenance;
+}
+export interface BrowserUseRunProvenance {
+  type: 'browser_use_run_v1';
+  run_id: string;
+  session_id: string;
+  provider_workspace_id: string | null;
+  /** SHA-256 of the host's immutable owner/run reservation, not raw shopper data. */
+  binding_sha256: string;
 }
 /** Registered server-side executor connector; IDs are resolved from owned backend records. */
 export interface RegisteredBrowserBinding {
@@ -125,6 +159,9 @@ export interface CreateCheckout {
   /** Explicit chat/after_fill attachment. Omit to retain Accelerate-created
    * private Kernel custody. Attachment never navigates or replaces the document. */
   browser?: CustomerBrowserBinding;
+  /** Required for purchase (the default purpose): the customer's backend, not Accelerate, performs the final click.
+   * Purchase also requires chat, after_fill and a customer_backend_trusted browser. */
+  final_click_actor?: 'customer';
   /** Your own provider read of `browser`, so Accelerate never needs your provider API key.
    * Send it on every create. It is held in memory for this checkout and never stored. */
   browser_resource?: ClientBrowserResource;
@@ -137,8 +174,12 @@ export interface ClientBrowserResource {
   startedAt: string;
   timeoutAt: string;
   recordingAvailable: false;
+  agentSessionId?: string;
+  agentRun?: { id: string; sessionId: string; workspaceId: string | null; status: 'completed' | 'cancelled' };
+  agentSession?: { sessionId: string; workspaceId: string | null; latestRunId: string; status: 'completed' | 'cancelled' };
+  agentQueue?: { queue: never[] };
   metadata: Record<string, string>;
-  extensions: [{ id: string; version: string; runtimeId: string }];
+  extensions: [{ id: string; version: string; runtimeId: string }, ...{ id: string; version: string; runtimeId: string }[]];
 }
 /** Hypothesis to inspect against the actual checkout; never a caller assertion of currency evidence. */
 export interface QuoteVerificationRequest {
@@ -165,6 +206,16 @@ export interface ApprovalRequest {
    * Successful private verification fills this exact revision without AI. */
   fill_after_verification?: true;
 }
+/** BACKEND ONLY. The target and arm_id must never appear in MCP arguments, results, history or outbox. */
+export interface ArmedFinalClick {
+  /** Opaque bounded string (20..16000 printable ASCII). Never display or log. */
+  arm_id: string;
+  /** Short window (service limit 15 seconds) in which the customer host may click once. */
+  armed_expires_at: string;
+  target: { checkout_url: string; submit_selector: string };
+  retry_safe: false;
+  payment_confirmed: false;
+}
 export interface AccelerateClientOptions {
   baseUrl: string;
   apiKey: string;
@@ -203,7 +254,14 @@ export class AccelerateClient {
     verifyQuote(id: CheckoutId, input: QuoteVerificationRequest, options?: RequestOptions): Promise<VerifiedCheckoutQuote>;
     requestApproval(id: CheckoutId, input: ApprovalRequest, options?: RequestOptions): Promise<Checkout>;
     fill(id: CheckoutId, input: { revision: number }, options?: RequestOptions): Promise<Checkout>;
-    submit(id: CheckoutId, input: { revision: number }, options?: RequestOptions): Promise<Checkout>;
+    /** Removed behavior: Accelerate never clicks. Always rejects with customer_click_required and sends no request. */
+    submit(id: CheckoutId, input: { revision: number }, options?: RequestOptions): Promise<never>;
+    /** Backend only: prepare one short-lived customer-owned final click. Accelerate sends no physical input. */
+    armFinalClick(id: CheckoutId, input: { revision: number }, options?: RequestOptions): Promise<ArmedFinalClick>;
+    /** Backend only: observe the customer's click once. Dispatch claims are not sent; never retry. */
+    completeFinalClick(id: CheckoutId, input: { revision: number; arm_id: string }, options?: RequestOptions): Promise<Checkout>;
     cancel(id: CheckoutId, options?: RequestOptions): Promise<Checkout>;
+    /** Records one merchant result after submit. Repeating the same input returns the same result; different input is refused. */
+    reconcile(id: CheckoutId, input: CheckoutReconciliationRequest, options?: RequestOptions): Promise<ReconciledCheckout>;
   };
 }

package/index.js

@@ -1,13 +1,14 @@
 import { env as processEnv, versions } from 'node:process';
 import { createHash } from 'node:crypto';
 import { normalizeBrowserOperation } from './browser-operations.js';
-import { validateCheckoutDiagnostics } from './checkout-diagnostics.js';
+import { browserUseRunProvenance } from './browser-provenance.js';
+import { validateCheckoutDiagnostics, validateCheckoutReconciliation } from './checkout-diagnostics.js';
 export { checkoutDiagnosticsJsonSchema, validateCheckoutDiagnostics } from './checkout-diagnostics.js';
 
 const ID = /^mcs_[A-Za-z0-9_-]{43}$/;
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const STATUSES = new Set(['wallet_required', 'selection_ready', 'details_ready', 'approval_required', 'approved',
-  'ready_for_submit', 'cancelled', 'expired', 'failed', 'submit_attempted', 'outcome_unknown']);
+  'ready_for_submit', 'final_click_armed', 'cancelled', 'expired', 'failed', 'submit_attempted', 'outcome_unknown']);
 const WAIT_STOPS = new Set(['ready_for_submit', 'cancelled', 'expired', 'failed', 'submit_attempted', 'outcome_unknown']);
 const HOSTED_SERVICE = 'https://accelerate-agent-sdk.vercel.app';
 const ERROR_CODES = new Set(['invalid_input', 'unauthorized', 'permission_denied', 'not_found', 'conflict',
@@ -15,12 +16,13 @@ const ERROR_CODES = new Set(['invalid_input', 'unauthorized', 'permission_denied
   'operation_in_progress', 'fill_continuation_required', 'review_unavailable', 'capability_disabled', 'checkout_unsupported', 'integration_unavailable', 'outcome_unknown',
   'authentication_required', 'checkout_closed', 'checkout_frozen', 'upstream_unavailable', 'wallet_required',
   'revision_conflict', 'address_changed', 'details_required', 'quote_changed', 'submit_unavailable',
-  'approval_unavailable', 'authentication_completed', 'verification_required', 'verification_failed',
+  'approval_unavailable', 'authentication_completed', 'verification_required', 'verification_failed', 'verification_pending',
   'verification_consumed', 'handoff_consumed', 'wallet_refreshing', 'consent_required',
   'idempotency_conflict', 'operation_conflict', 'checkout_not_found', 'tenant_unauthorized',
   'checkout_busy', 'store_unavailable', 'store_integrity_error', 'selection_rejected', 'upstream_invalid',
   'upstream_request_invalid', 'upstream_response_invalid', 'configuration_error', 'configuration_invalid',
-  'route_not_found', 'method_not_allowed', 'json_required', 'invalid_json', 'request_too_large', 'checkout_event_unconfirmed']);
+  'route_not_found', 'method_not_allowed', 'json_required', 'invalid_json', 'request_too_large', 'checkout_event_unconfirmed',
+  'reconciliation_unavailable', 'reconciliation_mismatch', 'reconciliation_conflict', 'customer_click_required', 'final_click_in_progress']);
 const MESSAGES = {
   invalid_input: 'Invalid Accelerate client request.',
   invalid_response: 'Accelerate returned an unrecognized private response.',
@@ -41,6 +43,8 @@ for (const [codes, message, nextAction] of [
     'Check the server API key, merchant ID and enabled Accelerate capabilities.', 'check_configuration'],
   [['invalid_input', 'invalid_json', 'json_required', 'request_too_large', 'method_not_allowed', 'route_not_found', 'upstream_request_invalid'],
     'Check the checkout request against the SDK contract.', 'check_request'],
+  [['verification_pending'],
+    'A private verification for this shopper, card, total and site is still open. Wait for it to expire, up to five minutes, then start a new checkout.', 'stop'],
   [['operation_in_progress', 'operation_conflict', 'checkout_busy', 'rate_limited', 'wallet_refreshing', 'conflict'],
     'Read checkout status before continuing. Do not repeat an uncertain payment action.', 'check_status'],
   [['wallet_required', 'authentication_required', 'authentication_completed', 'selection_rejected'],
@@ -62,6 +66,16 @@ for (const [codes, message, nextAction] of [
     'Reconcile checkout status and the merchant order. Do not repeat the payment action.', 'reconcile_order'],
   [['checkout_event_unconfirmed'],
     'Private chat progress delivery could not be confirmed. Check this existing checkout; do not create a replacement.', 'check_status'],
+  [['final_click_in_progress'],
+    'A customer-owned final click is armed and not yet observed. Read the checkout status; do not cancel, re-arm or click again.', 'check_status'],
+  [['customer_click_required'],
+    'Accelerate never performs the final payment click. Use the customer-owned browser host: arm, click once in the customer browser, then complete.', 'check_request'],
+  [['reconciliation_unavailable'],
+    'This checkout has no submit outcome to reconcile. Nothing was recorded. Read its status.', 'check_status'],
+  [['reconciliation_mismatch'],
+    'The order does not match the approved quote. Nothing was recorded. Check the merchant order.', 'reconcile_order'],
+  [['reconciliation_conflict'],
+    'A different result is already recorded for this checkout. It cannot be replaced.', 'check_status'],
 ]) for (const code of codes) GUIDANCE[code] = Object.freeze({ message, nextAction });
 
 /** Safe diagnostics only: no response body, URL, credentials, cause or provider stack. */
@@ -115,6 +129,16 @@ function preparationText(value, max = 2000, code = 'invalid_input') {
     !/\b(?:cvv|cvc|security\s*code|card\s*(?:number|expiry|expiration))\b.{0,30}\d/iu.test(value), code);
   return value;
 }
+function reconciliationInput(input) {
+  keys(input, ['state', 'order_reference', 'amount_cents', 'currency', 'source'], ['state', 'source']);
+  check(['confirmed', 'declined', 'not_found'].includes(input.state) && typeof input.source === 'string' &&
+    /^[a-z][a-z0-9_.-]{0,39}$/u.test(input.source) && !/(?:\d[ -]?){13,19}/u.test(input.source));
+  if (input.order_reference !== undefined) string(input.order_reference, 200);
+  if (input.amount_cents !== undefined) integer(input.amount_cents, 1, 2147483647);
+  check(input.currency === undefined || input.currency === 'USD');
+  check(input.state !== 'confirmed' || [input.order_reference, input.amount_cents, input.currency].every(value => value !== undefined));
+  return { ...input };
+}
 function browserInput(input) {
   keys(input, ['operation', 'arguments']);
   try { return { operation: input.operation, arguments: normalizeBrowserOperation(input.operation, input.arguments) }; }
@@ -144,7 +168,7 @@ function safeText(value, max = 1000, multiline = false) {
 }
 function statusResponse(value, expectedId, { create, origin, loopback }) {
   keys(value, ['id', 'status', 'revision', 'expires_at', 'card', 'address', 'quote', 'submit_expires_at', 'purpose', 'submit_allowed', 'approval_policy', 'purchase_approved', 'diagnostics',
-    'fill_after_verification', 'retry_safe', 'payment_confirmed', ...(create ? ['wallet_url'] : [])],
+    'fill_after_verification', 'reconciliation', 'final_click_actor', 'submit_actor', 'retry_safe', 'payment_confirmed', ...(create ? ['wallet_url'] : [])],
   ['id', 'status', 'revision', 'expires_at', 'retry_safe', 'payment_confirmed'], 'invalid_response');
   check(typeof value.id === 'string' && ID.test(value.id) && (!expectedId || value.id === expectedId) && STATUSES.has(value.status) &&
     value.retry_safe === false && value.payment_confirmed === false, 'invalid_response');
@@ -152,10 +176,19 @@ function statusResponse(value, expectedId, { create, origin, loopback }) {
   if (value.purpose !== undefined || value.submit_allowed !== undefined) check(
     ['purchase', 'sandbox_source_comparison', 'sandbox_fill_only'].includes(value.purpose) &&
     value.submit_allowed === (value.purpose === 'purchase'), 'invalid_response');
-  if (value.approval_policy !== undefined || value.purchase_approved !== undefined) check(value.approval_policy === 'after_fill' && typeof value.purchase_approved === 'boolean' && (!value.purchase_approved || value.status === 'ready_for_submit' && value.purpose === 'purchase'), 'invalid_response');
+  if (value.approval_policy !== undefined || value.purchase_approved !== undefined) check(value.approval_policy === 'after_fill' && typeof value.purchase_approved === 'boolean' && (!value.purchase_approved || ['ready_for_submit', 'final_click_armed'].includes(value.status) && value.purpose === 'purchase'), 'invalid_response');
   if (value.fill_after_verification !== undefined) check(value.fill_after_verification === true && value.approval_policy === 'after_fill' &&
     ['purchase', 'sandbox_fill_only'].includes(value.purpose), 'invalid_response');
   if (value.submit_expires_at !== undefined) timestamp(value.submit_expires_at);
+  // Only the customer's own backend/browser may ever perform the final click.
+  if (value.final_click_actor !== undefined) check(value.final_click_actor === 'customer' && value.purpose === 'purchase', 'invalid_response');
+  if (value.submit_actor !== undefined) check(value.submit_actor === 'customer' && value.final_click_actor === 'customer' &&
+    ['submit_attempted', 'outcome_unknown'].includes(value.status), 'invalid_response');
+  // An attested attempt names the customer; an unknown outcome cannot assert that a click happened.
+  if (value.status === 'submit_attempted' && value.purpose === 'purchase') check(value.submit_actor === 'customer', 'invalid_response');
+  if (value.reconciliation !== undefined) {
+    try { validateCheckoutReconciliation(value.reconciliation, value.status); } catch { fail('invalid_response'); }
+  }
   if (value.diagnostics !== undefined) {
     try { validateCheckoutDiagnostics(value.diagnostics, value); } catch { fail('invalid_response'); }
   }
@@ -210,7 +243,10 @@ function creationInspectionInput(input) {
   for (const name of ['customer_id', 'workspace_id', 'conversation_id'])
     check(typeof input[name] === 'string' && /^[A-Za-z0-9_.:-]{1,500}$/u.test(input[name]));
   string(input.idempotency_key, 200);
-  keys(input.browser, ['provider', 'browser_id', 'custody_mode']);
+  keys(input.browser, ['provider', 'browser_id', 'custody_mode', 'provenance'], ['provider', 'browser_id', 'custody_mode']);
+  if (Object.hasOwn(input.browser, 'provenance')) {
+    try { browserUseRunProvenance(input.browser.provenance); } catch { check(false); }
+  }
   check(input.browser.provider === 'browser_use' && typeof input.browser.browser_id === 'string' &&
     UUID.test(input.browser.browser_id) && input.browser.browser_id === input.browser.browser_id.toLowerCase() &&
     input.browser.custody_mode === 'customer_backend_trusted');
@@ -246,6 +282,16 @@ function retirementInspectionResponse(value, id, input) {
     value.retirement.recording_disabled === true, 'invalid_response');
   return value;
 }
+const ARM_ID = /^[\x21-\x7e]{20,16000}$/u;
+function armId(value, code = 'invalid_input') { check(typeof value === 'string' && ARM_ID.test(value), code); return value; }
+function finalClickArmResponse(value, input) {
+  keys(value, ['arm_id', 'armed_expires_at', 'target', 'retry_safe', 'payment_confirmed'], undefined, 'invalid_response');
+  armId(value.arm_id, 'invalid_response'); timestamp(value.armed_expires_at);
+  check(value.retry_safe === false && value.payment_confirmed === false, 'invalid_response');
+  keys(value.target, ['checkout_url', 'submit_selector'], undefined, 'invalid_response');
+  try { merchantUrl(value.target.checkout_url); string(value.target.submit_selector, 200); } catch { fail('invalid_response'); }
+  return value;
+}
 function connectionResponse(value, merchantId) {
   keys(value, ['status', 'api_version', 'merchant_id', 'interaction_modes', 'currencies'], undefined, 'invalid_response');
   check(value.status === 'connected' && value.api_version === 'v1' && value.merchant_id === merchantId &&
@@ -340,8 +386,24 @@ export class AccelerateClient {
         return result;
       },
       fill: async (id, input, options) => this.#request('POST', checkoutId(id), '/fill', revisionInput(input), options),
-      submit: async (id, input, options) => this.#request('POST', checkoutId(id), '/submit', revisionInput(input), options),
+      // The old executor-click endpoint is permanently closed: Accelerate never sends the final click.
+      submit: async () => fail('customer_click_required'),
+      /** Backend only. The returned target is never model/MCP output. */
+      armFinalClick: async (id, input, options) => this.#request('POST', checkoutId(id), '/final-click/arm', revisionInput(input), options),
+      completeFinalClick: async (id, input, options) => {
+        keys(input, ['revision', 'arm_id']); integer(input.revision, 1, 2147483647); armId(input.arm_id);
+        const result = await this.#request('POST', checkoutId(id), '/final-click/complete', { revision: input.revision, arm_id: input.arm_id }, options);
+        check(['submit_attempted', 'outcome_unknown'].includes(result.status) && result.purpose === 'purchase' &&
+          result.final_click_actor === 'customer' && (result.status === 'outcome_unknown' || result.submit_actor === 'customer'), 'invalid_response');
+        return result;
+      },
       cancel: async (id, options) => this.#request('POST', checkoutId(id), '/cancel', {}, options),
+      reconcile: async (id, input, options) => {
+        const body = reconciliationInput(input);
+        const result = await this.#request('POST', checkoutId(id), '/reconcile', body, options);
+        check(result.reconciliation?.state === body.state && result.reconciliation.source === body.source, 'invalid_response');
+        return result;
+      },
     });
   }
   async #waitFor(id, input, options = {}) {
@@ -373,7 +435,7 @@ export class AccelerateClient {
     } finally { clearTimeout(timer); }
   }
   #create(input, options) {
-    keys(input, ['customer_id', 'workspace_id', 'phone_number', 'start_url', 'idempotency_key', 'interaction_mode', 'conversation_id', 'purpose', 'approval_policy', 'browser', 'browser_resource', 'fill_after_verification'],
+    keys(input, ['customer_id', 'workspace_id', 'phone_number', 'start_url', 'idempotency_key', 'interaction_mode', 'conversation_id', 'purpose', 'approval_policy', 'browser', 'browser_resource', 'fill_after_verification', 'final_click_actor'],
       ['customer_id', 'workspace_id', 'phone_number', 'start_url', 'idempotency_key']);
     check(typeof input.customer_id === 'string' && /^[A-Za-z0-9_.:-]{1,500}$/u.test(input.customer_id));
     check(typeof input.workspace_id === 'string' && /^[A-Za-z0-9_.:-]{1,500}$/u.test(input.workspace_id));
@@ -386,9 +448,17 @@ export class AccelerateClient {
     check(input.approval_policy !== 'after_fill' || input.interaction_mode === 'chat' && input.purpose !== 'sandbox_source_comparison');
     check(input.fill_after_verification === undefined || input.fill_after_verification === true && input.interaction_mode === 'chat' && input.approval_policy === 'after_fill' && ['purchase', 'sandbox_fill_only'].includes(input.purpose ?? 'purchase'));
     check(input.purpose !== 'sandbox_fill_only' || input.interaction_mode === 'chat');
+    // Purchases are never clicked by Accelerate. They require the customer's own trusted browser and final-click actor.
+    check(input.final_click_actor === undefined || input.final_click_actor === 'customer' && (input.purpose ?? 'purchase') === 'purchase');
+    if ((input.purpose ?? 'purchase') === 'purchase') check(input.final_click_actor === 'customer' && input.interaction_mode === 'chat' &&
+      input.approval_policy === 'after_fill' && input.browser?.custody_mode === 'customer_backend_trusted');
     check(input.interaction_mode === 'chat' ? typeof input.conversation_id === 'string' && /^[A-Za-z0-9_.:-]{1,500}$/u.test(input.conversation_id) : input.conversation_id === undefined);
     if (input.browser !== undefined) {
-      keys(input.browser, ['provider', 'browser_id', 'custody_mode', ...(input.browser?.provider === 'connector' ? ['connector_id'] : [])]);
+      keys(input.browser, ['provider', 'browser_id', 'custody_mode', ...(input.browser?.provider === 'connector' ? ['connector_id'] : ['provenance'])],
+        ['provider', 'browser_id', 'custody_mode', ...(input.browser?.provider === 'connector' ? ['connector_id'] : [])]);
+      if (Object.hasOwn(input.browser, 'provenance')) {
+        try { browserUseRunProvenance(input.browser.provenance); } catch { check(false); }
+      }
       const supportedBinding = input.browser.provider === 'browser_use'
         ? typeof input.browser.browser_id === 'string' && UUID.test(input.browser.browser_id) && input.browser.browser_id === input.browser.browser_id.toLowerCase()
         : input.browser.provider === 'connector' && typeof input.browser.connector_id === 'string' && /^[a-z][a-z0-9_-]{0,63}$/u.test(input.browser.connector_id) &&
@@ -401,7 +471,8 @@ export class AccelerateClient {
       check(input.purpose !== 'sandbox_fill_only' || result.purpose === 'sandbox_fill_only' && result.submit_allowed === false, 'invalid_response');
       check(input.approval_policy !== 'after_fill' || result.approval_policy === 'after_fill' && result.purchase_approved === false, 'invalid_response');
       check(input.interaction_mode !== 'chat' || result.wallet_url === undefined, 'invalid_response');
-      check(input.fill_after_verification !== true || result.fill_after_verification === true, 'invalid_response'); return result;
+      check(input.fill_after_verification !== true || result.fill_after_verification === true, 'invalid_response');
+      check(input.final_click_actor !== 'customer' || result.final_click_actor === 'customer' && result.purpose === 'purchase', 'invalid_response'); return result;
     });
   }
   async #request(method, id, suffix, body, options = {}, connection = false) {
@@ -409,7 +480,7 @@ export class AccelerateClient {
     check(options.signal === undefined || options.signal instanceof AbortSignal);
     const controller = new AbortController();
     const milliseconds = connection ? 45000 : ['/inspect-creation', '/inspect-retirement'].includes(suffix) ? 60000 : id === null ? 245000 : ({ '/fill': 235000, '/details': 125000, '/verify-quote': 125000, '/approval': 125000,
-      '/submit': 125000, '/browser': 85000, '/cancel': 45000, '': 45000 })[suffix];
+      '/final-click/arm': 20000, '/final-click/complete': 125000, '/browser': 85000, '/cancel': 45000, '/reconcile': 45000, '': 45000 })[suffix];
     const timer = setTimeout(() => controller.abort(), milliseconds); timer.unref?.();
     const signal = AbortSignal.any([controller.signal, ...(options.signal ? [options.signal] : [])]);
     const url = connection ? `${this.#origin}/v1/connection` :
@@ -429,7 +500,7 @@ export class AccelerateClient {
       if (!response.ok) throw new AccelerateError(ERROR_CODES.has(value?.error?.code) ? value.error.code : 'request_failed', response.status,
         response.headers.get('x-accelerate-support-reference'));
       return connection ? connectionResponse(value, this.#merchantId) : suffix === '/browser' ? browserResponse(value) :
-        suffix === '/verify-quote' ? verifiedQuoteResponse(value, id, body) : suffix === '/inspect-creation' ? creationInspectionResponse(value, body) : suffix === '/inspect-retirement' ? retirementInspectionResponse(value, id, body) : statusResponse(value, id, {
+        suffix === '/verify-quote' ? verifiedQuoteResponse(value, id, body) : suffix === '/final-click/arm' ? finalClickArmResponse(value, body) : suffix === '/inspect-creation' ? creationInspectionResponse(value, body) : suffix === '/inspect-retirement' ? retirementInspectionResponse(value, id, body) : statusResponse(value, id, {
         create: id === null, origin: this.#origin, loopback: this.#loopback });
     } catch (error) {
       Promise.resolve(response?.body?.cancel()).catch(() => {});

package/managed-mcp.d.ts

@@ -1,4 +1,4 @@
-import type { AccelerateClient, AccelerateNextAction, Checkout, CheckoutId, CustomerBrowserBinding } from './index.js';
+import type { AccelerateClient, AccelerateNextAction, Checkout, CheckoutId, ClientBrowserResource, CustomerBrowserBinding } from './index.js';
 import type { BrowserResult } from './browser-operations.js';
 import type { BrowserConnector } from './browser-connector.js';
 
@@ -17,6 +17,8 @@ export interface ManagedCheckoutCreation {
   /** Optional existing browser from the host's owned workflow, never MCP input.
    * Only permitted with browserMode:'customer_backend_trusted'. */
   browser?: CustomerBrowserBinding;
+  /** Your own provider read of `browser`, so Accelerate never needs your provider API key. */
+  browser_resource?: ClientBrowserResource;
   /** Resolve only after durable storage. Retain an uncertainty fence if acknowledgement is lost. */
   persistCreated(binding: Readonly<ManagedCheckoutBinding>): Promise<void>;
 }
@@ -108,9 +110,13 @@ export interface ManagedCheckoutToolsOptions<Extra = unknown> {
    * checkout ID/revision; the existing owner record and uncertainty fence remain.
    */
   dispatchCheckoutEvent(context: Readonly<ManagedCheckoutContext>, event: Readonly<ManagedCheckoutEvent>): Promise<void>;
-  /** Immutable for newly created checkouts. Default sandbox_fill_only. */
+  /** Immutable for newly created checkouts. Default sandbox_fill_only. Purchase requires browserMode
+   * customer_backend_trusted and a browserConnector whose host implements performFinalClick: Accelerate
+   * never sends the final click, and Accelerate-managed private browsers cannot purchase. */
   purpose?: 'sandbox_fill_only' | 'purchase';
-  /** Default false. Registers final-submit tool only when true and purpose is purchase. */
+  /** Default false. Registers the final-submit tool only when true and purpose is purchase. That tool
+   * arms one short click, calls browserConnector.performFinalClick once in the customer's browser, then
+   * completes once to observe. Its result is a safe Checkout; the arm token and target never leave the backend. */
   enableSubmit?: boolean;
   /** Default managed_review_v1: verification at payment and approval after fill.
    * Legacy before-fill behavior requires this explicit profile or approvalPolicy:'before_fill'. */