@weaccelerateinc/agent-sdk 0.10.3 → 0.11.0

package/index.js

@@ -1,13 +1,13 @@
 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 { 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 +15,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 +42,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 +65,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 +128,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 +167,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 +175,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'); }
   }
@@ -246,6 +278,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 +382,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 +431,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,6 +444,10 @@ 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'] : [])]);
@@ -401,7 +463,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 +472,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 +492,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'. */

package/managed-mcp.js

@@ -1,6 +1,6 @@
 import { AccelerateClient, AccelerateError } from './index.js';
 import { browserOperationJsonSchema, parseBrowserOperation, normalizeBrowserOperation } from './browser-operations.js';
-import { checkoutDiagnosticsJsonSchema, validateCheckoutDiagnostics } from './checkout-diagnostics.js';
+import { checkoutDiagnosticsJsonSchema, validateCheckoutDiagnostics, validateCheckoutReconciliation } from './checkout-diagnostics.js';
 import { createHash } from 'node:crypto';
 
 const ID = /^mcs_[A-Za-z0-9_-]{43}$/;
@@ -8,9 +8,12 @@ const OWNER = /^[A-Za-z0-9_.:-]{1,500}$/;
 const PHONE = /^\+[1-9]\d{6,14}$/;
 const CONTEXT_KEYS = ['customer_id', 'workspace_id', 'conversation_id', 'phone_number'];
 const STATUSES = ['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 NEXT_ACTIONS = ['check_configuration', 'check_request', 'check_status', 'complete_wallet',
   'complete_verification', 'refresh_quote', 'refresh_revision', 'reconcile_order', 'stop'];
+// Errors that prove the final-click arm was not created. Everything else after an arm request is an unknown outcome.
+const PRE_ARM_REFUSALS = new Set(['approval_required', 'revision_conflict', 'checkout_expired', 'checkout_closed', 'customer_click_required',
+  'permission_denied', 'submit_unavailable', 'capability_disabled']);
 const object = value => value !== null && typeof value === 'object' && !Array.isArray(value) &&
   [Object.prototype, null].includes(Object.getPrototypeOf(value));
 const check = (value, code = 'invalid_input') => { if (!value) throw new AccelerateError(code); };
@@ -59,6 +62,7 @@ const checkoutSchema = schemaObject({
   expires_at: timestampSchema, purpose: { type: 'string', enum: ['purchase', 'sandbox_source_comparison', 'sandbox_fill_only'] },
   approval_policy: { const: 'after_fill' }, purchase_approved: { type: 'boolean' },
   fill_after_verification: { const: true },
+  final_click_actor: { const: 'customer' }, submit_actor: { const: 'customer' },
   submit_allowed: { type: 'boolean' }, retry_safe: { const: false }, payment_confirmed: { const: false },
   card: schemaObject({ last4: { anyOf: [{ type: 'string', pattern: '^\\d{4}$' }, { type: 'null' }] }, brand: nullableText(40) }),
   address: schemaObject({ label: nullableText(400), city: nullableText(128), state: nullableText(128), postal_code_mask: nullableText(128) }, ['label']),
@@ -107,7 +111,7 @@ export const managedCheckoutToolDefinitions = freeze([
     description: 'Cancel this exact owned checkout and request private browser cleanup. Cancellation does not reverse an attempted order or prove that no purchase occurred. Keep uncertain-payment fences until independently reconciled.',
     inputSchema: idInput, outputSchema: outputSchema('checkout'), destructive: true },
   { name: 'accelerate_checkout_submit', title: 'Explicitly submit approved purchase',
-    description: 'Explicit final purchase decision for this exact owned revision while its returned ready claim remains valid. Calls the one-use private final-submit operation once. Never automatically invoke after fill or retry after uncertainty. The default review profile requires the customer’s private post-fill approval first. submit_attempted is not order or payment confirmation. Available only when the server explicitly enables purchase submission.',
+    description: 'Explicit final purchase decision for this exact owned revision while its returned ready claim remains valid. Accelerate never clicks: this arms one short-lived click, your own backend performs the single physical final click in the customer’s existing browser, then Accelerate observes the outcome once. Never automatically invoke after fill or retry after uncertainty. The default review profile requires the customer’s private post-fill approval first. submit_attempted is not order or payment confirmation. Available only when the server explicitly enables purchase submission.',
     inputSchema: revisionInput, outputSchema: outputSchema('checkout'), destructive: true, submitOnly: true },
 ].map(value => ({ ...value, annotations: { readOnlyHint: value.readOnly === true, idempotentHint: value.readOnly === true,
   destructiveHint: value.destructive === true, openWorldHint: true } })));
@@ -126,7 +130,7 @@ function safeText(value, max = 1000, multiline = false) {
 function timestamp(value) { check(typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T[\d:.]+Z$/u.test(value) && Number.isFinite(Date.parse(value)), 'invalid_response'); return value; }
 function projectCheckout(value) {
   shape(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');
+    ['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(typeof value.id === 'string' && ID.test(value.id) && STATUSES.includes(value.status) && Number.isSafeInteger(value.revision) &&
     value.revision >= 0 && value.revision <= 2147483647 && value.retry_safe === false && value.payment_confirmed === false, 'invalid_response');
   const result = { id: value.id, status: value.status, revision: value.revision, expires_at: timestamp(value.expires_at), retry_safe: false, payment_confirmed: false };
@@ -135,7 +139,7 @@ function projectCheckout(value) {
     result.purpose = value.purpose; result.submit_allowed = value.submit_allowed;
   }
   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');
+    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');
     result.approval_policy = value.approval_policy; result.purchase_approved = value.purchase_approved;
   }
   if (value.fill_after_verification !== undefined) {
@@ -143,6 +147,17 @@ function projectCheckout(value) {
       ['purchase', 'sandbox_fill_only'].includes(value.purpose), 'invalid_response');
     result.fill_after_verification = true;
   }
+  // The customer's own backend/browser performs any final click; Accelerate never does.
+  if (value.final_click_actor !== undefined) {
+    check(value.final_click_actor === 'customer' && value.purpose === 'purchase', 'invalid_response');
+    result.final_click_actor = 'customer';
+  }
+  if (value.submit_actor !== undefined) {
+    check(value.submit_actor === 'customer' && value.final_click_actor === 'customer' && ['submit_attempted', 'outcome_unknown'].includes(value.status), 'invalid_response');
+    result.submit_actor = 'customer';
+  }
+  // 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.card !== undefined) {
     shape(value.card, ['last4', 'brand'], [], 'invalid_response');
     check(value.card.last4 === null || typeof value.card.last4 === 'string' && /^\d{4}$/u.test(value.card.last4), 'invalid_response');
@@ -164,6 +179,8 @@ function projectCheckout(value) {
     result.quote = { checkout_origin: value.quote.checkout_origin, amount_cents: value.quote.amount_cents, currency: 'USD' };
   }
   if (value.submit_expires_at !== undefined) result.submit_expires_at = timestamp(value.submit_expires_at);
+  // A backend record: checked here so a reconciled checkout stays readable, and never projected to the agent.
+  if (value.reconciliation !== undefined) { try { validateCheckoutReconciliation(value.reconciliation, value.status); } catch { check(false, 'invalid_response'); } }
   if (value.diagnostics !== undefined) result.diagnostics = JSON.parse(JSON.stringify(validateCheckoutDiagnostics(value.diagnostics, result)));
   return result;
 }
@@ -243,6 +260,9 @@ export function registerManagedCheckoutTools(server, { client = AccelerateClient
   const { verificationTiming, approvalPolicy, fillAfterVerification = false } = flowProfile({ profile, verificationTiming: requestedTiming, approvalPolicy: requestedApproval });
   check(server && typeof server.registerTool === 'function' && client?.checkouts &&
     ['create', 'get', 'browser', 'applyDetails', 'requestApproval', 'fill', 'submit', 'cancel'].every(key => typeof client.checkouts[key] === 'function') &&
+    (!enableSubmit || ['armFinalClick', 'completeFinalClick'].every(key => typeof client.checkouts[key] === 'function')) &&
+    // Purchases are never clicked by Accelerate or by Accelerate's private Kernel browser: only the customer's own browser host can click.
+    (purpose !== 'purchase' || browserMode === 'customer_backend_trusted' && ['prepareFinalClick', 'performFinalClick'].every(key => typeof browserConnector?.[key] === 'function')) &&
     [resolveContext, withOwnedCheckout, withCheckoutCreation, dispatchCheckoutEvent].every(value => typeof value === 'function') &&
     ['purchase', 'sandbox_fill_only'].includes(purpose) && typeof enableSubmit === 'boolean' && (!enableSubmit || purpose === 'purchase') &&
     ['on_start', 'on_payment'].includes(verificationTiming) && ['before_fill', 'after_fill'].includes(approvalPolicy) &&
@@ -251,6 +271,7 @@ export function registerManagedCheckoutTools(server, { client = AccelerateClient
     (browserConnector === undefined || browserMode === 'customer_backend_trusted' && browserConnector?.contract === 'accelerate_existing_browser_v1' &&
       ['prepareAttachment', 'commitAttachment', 'assertPaymentReady', 'confirmCleanup'].every(key => typeof browserConnector[key] === 'function')));
   const requirePolicy = checkout => {
+    check(purpose !== 'purchase' || checkout.final_click_actor === 'customer', 'invalid_response');
     check(approvalPolicy === 'after_fill' ? checkout.approval_policy === 'after_fill' && typeof checkout.purchase_approved === 'boolean'
       : checkout.approval_policy === undefined && checkout.purchase_approved === undefined, 'invalid_response');
     return checkout;
@@ -322,6 +343,7 @@ export function registerManagedCheckoutTools(server, { client = AccelerateClient
             creationStarted = true;
             const created = await client.checkouts.create({ ...context, start_url: input.start_url,
               idempotency_key: scope.idempotency_key, interaction_mode: 'chat', purpose,
+              ...(purpose === 'purchase' ? { final_click_actor: 'customer' } : {}),
               ...(browserMode === 'customer_backend_trusted' ? { browser: { ...browser } } : {}),
               ...(attachment?.browser_resource ?? scope.browser_resource ? { browser_resource: attachment?.browser_resource ?? scope.browser_resource } : {}),
               ...(approvalPolicy === 'after_fill' ? { approval_policy: approvalPolicy } : {}),
@@ -350,7 +372,30 @@ export function registerManagedCheckoutTools(server, { client = AccelerateClient
               value = await client.checkouts.requestApproval(id, { ...approval, ...(fillAfterVerification ? { fill_after_verification: true } : {}) }, options);
               check(!fillAfterVerification || value.fill_after_verification === true, 'invalid_response');
             } else if (definition.name === 'accelerate_checkout_fill') value = await client.checkouts.fill(id, { revision: input.revision }, options);
-            else if (definition.name === 'accelerate_checkout_submit') { check(enableSubmit && purpose === 'purchase', 'permission_denied'); value = await client.checkouts.submit(id, { revision: input.revision }, options); }
+            else if (definition.name === 'accelerate_checkout_submit') {
+              check(enableSubmit && purpose === 'purchase' && typeof browserConnector?.performFinalClick === 'function' && typeof browserConnector.prepareFinalClick === 'function', 'permission_denied');
+              // prepare -> arm -> customer-owned host click -> complete, exactly once. The arm token and target stay in this scope.
+              // Slow provider/extension readiness runs BEFORE the arm so it cannot consume the short click window.
+              const preparation = await browserConnector.prepareFinalClick(context, { checkout_id: id }, options); requireAdmission();
+              let armed;
+              try { armed = await client.checkouts.armFinalClick(id, { revision: input.revision }, options); }
+              catch (error) {
+                // Only an explicit refusal proves nothing was armed. Transport, schema, timeout and upstream failures may have burned the arm.
+                if (error instanceof AccelerateError && PRE_ARM_REFUSALS.has(error.code)) throw error;
+                throw new AccelerateError('outcome_unknown');
+              }
+              try {
+                await browserConnector.performFinalClick(context, { checkout_id: id, preparation,
+                  checkout_url: armed.target.checkout_url, submit_selector: armed.target.submit_selector,
+                  armed_expires_at: armed.armed_expires_at }, options);
+              } catch { /* Host failure is not retried; the service observation below is the only truth. */ }
+              try { value = await client.checkouts.completeFinalClick(id, { revision: input.revision, arm_id: armed.arm_id }, options); }
+              catch { throw new AccelerateError('outcome_unknown'); }
+              // After a click attempt any unusable observation is an uncertain outcome, never a retryable failure.
+              try { requirePolicy(projectCheckout(value)); } catch { throw new AccelerateError('outcome_unknown'); }
+              check(['submit_attempted', 'outcome_unknown'].includes(value?.status) && value.final_click_actor === 'customer' &&
+                (value.status === 'outcome_unknown' || value.submit_actor === 'customer'), 'outcome_unknown');
+            }
             else value = await client.checkouts.cancel(id, options);
             requireAdmission();
             const projected = kind === 'browser' ? projectBrowser(value) : requirePolicy(projectCheckout(value));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weaccelerateinc/agent-sdk",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "description": "Server-only payment SDK, existing-browser connectors and private host adapters for agent platforms",
   "type": "module",
   "main": "./index.js",

package/partner-starter/.env.example

@@ -2,8 +2,10 @@
 ACCELERATE_STARTER_MODE=synthetic
 # Explicit new profile: private CVV continues the armed fill in the backend.
 ACCELERATE_CHECKOUT_PROFILE=managed_review_v2
-ACCELERATE_STARTER_PURPOSE=sandbox_fill_only
-ACCELERATE_ENABLE_PURCHASE_SUBMIT=false
+ACCELERATE_STARTER_PURPOSE=purchase
+ACCELERATE_ENABLE_PURCHASE_SUBMIT=true
+# For a fill-only test, set purpose to sandbox_fill_only and submit to false.
+# This file is a template; export values or load it with your server environment.
 # Live: operator-controlled absolute file exporting createPartnerDependencies().
 # ACCELERATE_CONTEXT_MODULE=/absolute/protected/partner-host.mjs
 # ACCELERATE_API_KEY=<tenant server key>

package/partner-starter/README.md

@@ -1,20 +1,20 @@
 # Existing-browser payment starter
 
-SDK source 0.10.3, explicit `managed_review_v2`, `customer_backend_trusted`. The matching service must support this profile; source changes do not establish an archive publication or live deployment. Your platform creates its browser and installs the approved extension. This starter attaches that same browser at payment; it never creates a replacement. The older `accelerate-agent init <dir>` starter still selects Accelerate-managed Kernel custody.
+SDK 0.11.0, explicit `managed_review_v2`, `customer_backend_trusted`. Newly generated existing-browser apps default to `purpose:'purchase'` with the submit tool enabled. The matching service must support this profile; publishing the SDK does not deploy the service or qualify a merchant layout. Your platform creates its browser and installs the approved extension. This starter attaches that same browser at payment; it never creates a replacement. The older `accelerate-agent init <dir>` starter still selects Accelerate-managed Kernel custody and its fill-only default.
 
 ## Run without credentials
 
-Once Accelerate supplies the matching verified 0.10.3 archive, install it, then:
+Once Accelerate supplies the matching verified 0.11.0 archive, install it, then:
 
 ```sh
 npx --no-install accelerate-agent init ./partner-demo --browser existing
 cd partner-demo
-npm install /secure/downloads/weaccelerateinc-agent-sdk-0.10.3.tgz
+npm install /secure/downloads/weaccelerateinc-agent-sdk-0.11.0.tgz
 npm test
 npm run smoke
 ```
 
-The synthetic fixture uses the actual connector, durable-host interface, private ingress/outbox and MCP registration. It simulates verification/provider operations; no real browser, message, credential or order is created. Its in-memory persistence and fake extension metadata are test fixtures only.
+The synthetic fixture uses the actual connector, durable-host interface, private ingress/outbox and MCP registration. It simulates verification/provider operations; no real browser, message, credential or order is created. The smoke exercises default purchase mode, confirms submission is rejected before private approval, then cancels without approving or submitting. Its in-memory persistence and fake extension metadata are test fixtures only.
 
 ## Connect your platform
 
@@ -41,8 +41,21 @@ At create, v2 declares `fill_after_verification:true` and requires the service t
 
 Before attachment, use ordinary customer details for required non-secret fields or ask for missing details. Leave card number/PAN, expiry and CVV empty; never obtain them through ordinary browser tools.
 
-PAN displays stars + last four, CVV stars, expiry visible. Filled-page inspection is blocked for the agent. Provider-owner backend access remains trusted. The published release baseline qualifies `https://demos.weaccelerate.com/normal/payment`. The new universal-card source path probes compatible public HTTPS card forms instead of keeping a merchant hostname allowlist. It requires private `universal_card_v1` admission bound to the exact existing document and immutable purpose before OTP/CVV; ambiguous/unsupported forms fail without a replacement browser. That capability requires coordinated service/executor deployment and does not promise every checkout works. A candidate artifact or generic interface alone does not qualify a browser.
+PAN displays stars + last four, CVV stars, expiry visible. Filled-page inspection is blocked for the agent. Provider-owner backend access remains trusted. `universal_card_v1` is private runtime admission for the exact HTTPS checkout document and requested purpose, including both purchase and fill-only. It detects compatible payment fields and safe review support across merchants; unsupported or ambiguous forms fail before OTP/CVV without a replacement browser. It requires a matching service/executor deployment. The approved extension's original manifest records demo fill/review/cancel evidence; the [2 November sandbox report](https://github.com/weaccelerateinc/accelerate/blob/main/products/agent-sdk/qualification/REPORT.md) includes additional real merchant fill/review runs, with no real-store order submission or production qualification. The universal path reuses the approved 0.0.0.1 extension; it does not require candidate 0.0.0.2.
 
-The default is `sandbox_fill_only`, with no submit tool. After its informational image, call cancel and verify cleanup. Enable purchase only through explicit backend `purpose:'purchase'` and `enableSubmit:true` after qualification. Customer approval never automatically submits. Uncertain outcomes retain fences and require reconciliation; status/cleanup never authorize a replacement by themselves.
+## Purchase and fill-only configuration
+
+The new starter defaults are:
+
+```dotenv
+ACCELERATE_STARTER_PURPOSE=purchase
+ACCELERATE_ENABLE_PURCHASE_SUBMIT=true
+```
+
+Purchase mode exposes `accelerate_checkout_submit`. Accelerate never sends the final click: that tool arms one short click, your `createPartnerDependencies` browser connector host must implement `performFinalClick` to click once in the customer's existing browser, then Accelerate observes the outcome. Registration fails without that host. The synthetic fixture simulates the arm, host click and completion; its smoke still cancels without a purchase decision, and the starter tests run the approved path. Private CVV, a delivered masked review, a fresh customer decision and a separate explicit submit for the matching revision are still required. A ready form or customer approval never submits automatically. The default `ACCELERATE_STARTER_MODE=synthetic` makes no external requests. `live` selects real backend dependencies, not the production wallet environment; the approved key, Merchant ID and service configuration select that environment.
+
+For a no-order test, set `ACCELERATE_STARTER_PURPOSE=sandbox_fill_only` and remove the submit override or set `ACCELERATE_ENABLE_PURCHASE_SUBMIT=false`. If you copied `.env.example`, change both lines. An explicit true submit setting with fill-only purpose is rejected. After its informational review, cancel and verify cleanup. Purchase purpose with explicit submit false is also supported.
+
+The starter does not load `.env` automatically; export the settings or load them through your server's environment configuration. This change affects future `init --browser existing` output after 0.11.0 is released. Published 0.10.3 and already generated apps retain their old files; configure their existing switches explicitly to enable purchase. Reusable SDK registration defaults remain fill-only. Existing checkout purpose is immutable, so an existing fill-only checkout cannot become a purchase. Uncertain outcomes retain fences and require reconciliation; status/cleanup never authorize a replacement by themselves.
 
 Before live testing, confirm the session is executing the deployed v2 tool bundle. Updating a durable agent app does not necessarily replace an active session’s tools; settle its old work and use the framework’s supported idle deployment handoff or create a new authenticated session. Verify the quote response acknowledges `fill_after_verification:true`; a successful deployment alone is insufficient.

package/partner-starter/package.json

@@ -12,7 +12,7 @@
     "test": "node --test tests/*.test.mjs"
   },
   "dependencies": {
-    "@weaccelerateinc/agent-sdk": "0.10.3",
+    "@weaccelerateinc/agent-sdk": "0.11.0",
     "@modelcontextprotocol/server": "2.3.1"
   },
   "devDependencies": {

package/partner-starter/runtime.mjs

@@ -9,8 +9,9 @@ export async function configureStarter(server, env = process.env) {
   const mode = env.ACCELERATE_STARTER_MODE ?? 'synthetic';
   const profile = env.ACCELERATE_CHECKOUT_PROFILE ?? 'managed_review_v2';
   if (!['managed_review_v1', 'managed_review_v2'].includes(profile)) throw Error('Unsupported partner checkout profile.');
-  const purpose = env.ACCELERATE_STARTER_PURPOSE ?? 'sandbox_fill_only';
-  const enableSubmit = env.ACCELERATE_ENABLE_PURCHASE_SUBMIT === 'true';
+  const purpose = env.ACCELERATE_STARTER_PURPOSE ?? 'purchase';
+  const enableSubmit = env.ACCELERATE_ENABLE_PURCHASE_SUBMIT === undefined
+    ? purpose === 'purchase' : env.ACCELERATE_ENABLE_PURCHASE_SUBMIT === 'true';
   if (!['sandbox_fill_only', 'purchase'].includes(purpose) ||
     env.ACCELERATE_ENABLE_PURCHASE_SUBMIT !== undefined && !['true', 'false'].includes(env.ACCELERATE_ENABLE_PURCHASE_SUBMIT) ||
     enableSubmit && purpose !== 'purchase') throw Error('Unsupported server purchase policy.');

package/partner-starter/smoke.mjs

@@ -12,9 +12,9 @@ const timer = setTimeout(() => { void transport.close(); }, 15000);
 try {
   await client.connect(transport);
   const tools = await client.listTools();
-  assert.equal(tools.tools.length, 7);
+  assert.equal(tools.tools.length, 8);
   assert.equal(tools.tools.some(tool => tool.name === 'accelerate_checkout_request_payment'), true);
-  assert.equal(tools.tools.some(tool => tool.name === 'accelerate_checkout_submit'), false);
+  assert.equal(tools.tools.some(tool => tool.name === 'accelerate_checkout_submit'), true);
   assert.equal(tools.tools.some(tool => tool.name === 'accelerate_checkout_fill'), false);
   const call = async (name, args) => {
     const result = await client.callTool({ name, arguments: args });
@@ -23,8 +23,9 @@ try {
   };
   const checkoutUrl = 'https://demos.weaccelerate.com/normal/payment';
   const checkout = (await call('accelerate_checkout_start', { start_url: checkoutUrl })).checkout;
-  assert.equal(checkout.purpose, 'sandbox_fill_only'); assert.equal(checkout.submit_allowed, false);
+  assert.equal(checkout.purpose, 'purchase'); assert.equal(checkout.submit_allowed, true);
   assert.equal(checkout.approval_policy, 'after_fill'); assert.equal(checkout.purchase_approved, false);
+  assert.equal(checkout.final_click_actor, 'customer');
   assert.equal(checkout.status, 'wallet_required'); assert.equal(checkout.card, undefined);
   const id = checkout.id;
   assert.equal((await call('accelerate_checkout_status', { checkout_id: id })).checkout.status, 'wallet_required');
@@ -42,12 +43,16 @@ try {
   assert.equal(reviewed.purchase_approved, false);
   const remaining = Date.parse(reviewed.submit_expires_at) - Date.now();
   assert.ok(remaining > 290000 && remaining <= 300000);
+  const rejected = await client.callTool({ name: 'accelerate_checkout_submit', arguments: { checkout_id: id, revision: reviewed.revision } });
+  const rejection = rejected.structuredContent ?? JSON.parse(rejected.content.find(part => part.type === 'text').text);
+  assert.equal(rejection.ok, false); assert.equal(rejection.error.code, 'submit_unavailable');
   assert.equal((await call('accelerate_checkout_cancel', { checkout_id: id })).checkout.status, 'cancelled');
   complete = true;
   process.stdout.write(JSON.stringify({ ok: true, synthetic_only: true, mcp_protocol: true,
     profile: 'managed_review_v2', existing_browser_connector: true, browser_mode: 'customer_backend_trusted', verification_deferred: true, private_verification_before_fill: true,
-    private_review_receipt_acknowledged: true, approval_window_ms: 300000, purchase_approval_requested: false,
-    submit_tool_absent: true, manual_fill_tool_absent: true, fill_ready: true, cancelled: true, live_checkout_requests: 0 }) + '\n');
+    private_review_receipt_acknowledged: true, approval_window_ms: 300000, purchase_approval_requested: true,
+    purpose: 'purchase', submit_tool_present: true, unapproved_submit_blocked: true, purchase_decision_received: false,
+    submit_attempted: false, final_click_actor: 'customer', manual_fill_tool_absent: true, fill_ready: true, cancelled: true, live_checkout_requests: 0 }) + '\n');
 } catch {
   process.stderr.write(JSON.stringify({ ok: false, code: 'synthetic_smoke_failed' }) + '\n');
 } finally {