@weaccelerateinc/agent-sdk 0.10.3 → 0.11.0

package/README.md

@@ -1,9 +1,11 @@
-# @weaccelerateinc/agent-sdk 0.10.3
+# @weaccelerateinc/agent-sdk 0.11.0
 
-Server-only ESM SDK with TypeScript declarations, Node 22+, zero runtime dependencies. New partners use their existing browser and explicitly select `managed_review_v2`, which continues an armed fill immediately after private CVV verification. Existing callers keep `managed_review_v1` unless they opt in. Public npm releases use `@weaccelerateinc/agent-sdk`; install an exact available version with `npm install @weaccelerateinc/agent-sdk@0.10.3`. Check `npm view @weaccelerateinc/agent-sdk@0.10.3 version` to confirm registry availability. The package remains `UNLICENSED`.
+Version 0.11.0 is a breaking release: **Accelerate never sends the final payment click.** A purchase arms one short click, the customer's agent performs it once through its own browser connection (`BrowserConnectorHost.performFinalClick`) in the customer's existing browser, then Accelerate observes the outcome. Purchase requires `final_click_actor:'customer'` and that host; the managed Kernel browser is fill-only. `client.checkouts.submit` rejects locally with `customer_click_required`. See [customer-owned final click](../../docs/customer-final-click.md). Release 0.10.3 keeps its existing behavior. Merchant layouts remain limited to the qualified sandbox page; this SDK release does not by itself qualify any merchant layout, a service deployment or production payments.
+
+Server-only ESM SDK with TypeScript declarations, Node 22+, zero runtime dependencies. New partners use their existing browser and explicitly select `managed_review_v2`, which continues an armed fill immediately after private CVV verification. Existing callers keep `managed_review_v1` unless they opt in. Public npm releases use `@weaccelerateinc/agent-sdk`; install an exact available version with `npm install @weaccelerateinc/agent-sdk@0.11.0`. Check `npm view @weaccelerateinc/agent-sdk@0.11.0 version` to confirm registry availability. The package remains `UNLICENSED`.
 
 ```sh
-npm install --ignore-scripts @weaccelerateinc/agent-sdk@0.10.3
+npm install --ignore-scripts @weaccelerateinc/agent-sdk@0.11.0
 npx --no-install accelerate-agent init ./partner-demo --browser existing
 ```
 
@@ -25,15 +27,15 @@ The platform creates the browser and installs the approved extension using its e
 | `/managed-mcp` | Lower-level canonical tool registration and explicit legacy/managed browser compatibility. |
 | `/browser-operations` | Strict bounded operation schemas; attached-customer mode permits pre-fill reads only. |
 
-The matching [partner guide](https://github.com/weaccelerateinc/accelerate-agent-sdk/blob/main/docs/new-customer-integration.md) and packaged `partner-starter/` show composition. Connect actual backend authentication, document controls, durable queues and private webhook before live use; examples intentionally fail without them.
+The matching [partner guide](https://github.com/weaccelerateinc/accelerate/blob/main/products/agent-sdk/docs/new-customer-integration.md) and packaged `partner-starter/` show composition. Connect actual backend authentication, document controls, durable queues and private webhook before live use; examples intentionally fail without them.
 
 Store `ACCELERATE_API_KEY` and `ACCELERATE_MERCHANT_ID` on the server. `ACCELERATE_BASE_URL` defaults to `https://accelerate-agent-sdk.vercel.app`. `accelerate-agent doctor` checks only that credential/API pair, never live downstream readiness. `new AccelerateClient({baseUrl,apiKey,merchantId,fetchImpl?})` supports custom transport; `allowLoopbackForTests:true` is local-test-only.
 
-For v2, create declares `fill_after_verification:true` and requires the service acknowledgement before OTP. That declaration alone cannot fill. The later verified quote repeats the flag to arm one exact revision; the successful private CVV reply fills immediately under the same backend lease and returns `review_delivery_required`. Private ingress delivers and acknowledges the masked image without asking the model to call fill. The v2 MCP registry omits the fill tool; an armed checkout rejects direct manual fill with `fill_continuation_required`. Read only its safe status. Final submit remains explicit. See [managed review v2](https://github.com/weaccelerateinc/accelerate-agent-sdk/blob/main/docs/managed-review-v2.md).
+For v2, create declares `fill_after_verification:true` and requires the service acknowledgement before OTP. That declaration alone cannot fill. The later verified quote repeats the flag to arm one exact revision; the successful private CVV reply fills immediately under the same backend lease and returns `review_delivery_required`. Private ingress delivers and acknowledges the masked image without asking the model to call fill. The v2 MCP registry omits the fill tool; an armed checkout rejects direct manual fill with `fill_continuation_required`. Read only its safe status. Final submit remains explicit. See [managed review v2](https://github.com/weaccelerateinc/accelerate/blob/main/products/agent-sdk/docs/managed-review-v2.md).
 
 Required sequence: shop → payment → same-browser attachment → private OTP/card → address/final amount → private CVV → fill once → private masked image/amount → five-minute decision → explicit submit → cleanup. PAN stars+last four, CVV stars, expiry visible. Compatible layouts require the matching qualified service/executor; unsupported fields or safe review stop before private collection. Provider-owner access remains trusted.
 
-`registerPartnerCheckoutTools({profile:'managed_review_v2', ...})` selects automatic private continuation and defaults to `purpose:'sandbox_fill_only',enableSubmit:false`. Its returned private ingress must run before framework logging/parsing/history/AI. A fresh private receipt/approval enables purchase; it never triggers submission. Fill-only tests cancel after delivered informational review. Private replies/browser credentials are never tool inputs/results. Recover only safe deliveries; never replay fill/submit.
+`registerPartnerCheckoutTools({profile:'managed_review_v2', ...})` selects automatic private continuation and retains its API defaults `purpose:'sandbox_fill_only',enableSubmit:false`. Pass `purpose:'purchase',enableSubmit:true` for purchase registration; it also requires a connector whose host implements `performFinalClick`. New `init --browser existing` projects from 0.11.0 select purchase mode by default; already generated apps keep their copied runtime. Its returned private ingress must run before framework logging/parsing/history/AI. A fresh private receipt/approval enables purchase; it never triggers submission. Fill-only tests cancel after delivered informational review. Private replies/browser credentials are never tool inputs/results. Recover only safe deliveries; never replay fill/submit.
 
 Compatibility: `accelerate-agent init <dir>` without `--browser existing` keeps the original managed Kernel starter. `registerManagedCheckoutTools` still defaults to `browserMode:'accelerate_managed'`. Existing before-fill integrations explicitly use `legacy_before_fill_v1`. Low-level hosted/raw APIs keep their compatibility defaults; a package upgrade does not change custody.
 
@@ -117,7 +119,7 @@ import {
 
 Use this entry point only in authenticated ingress **before** history, queues, analytics or model calls. `chat.start/get/reply/cancel` require the exact customer/workspace/conversation binding. `chat.reply` also requires a stable provider message ID and transient `text`; the mutable input text is cleared after the request, including failures.
 
-`renderPrivateChatState(state,{messageId})` returns a safe prompt or `undefined`. `privateChatProgress` returns a fixed safe preparation/verification/closure event. Both revalidate safe metadata and provide a hashed delivery idempotency key. They do not verify webhooks, authorize owners or replace durable ingress/delivery deduplication. Reuse your existing authenticated webhook, ownership lock and message sender. See the [private ingress example](https://github.com/weaccelerateinc/accelerate-agent-sdk/blob/main/examples/private-chat-ingress.js).
+`renderPrivateChatState(state,{messageId})` returns a safe prompt or `undefined`. `privateChatProgress` returns a fixed safe preparation/verification/closure event. Both revalidate safe metadata and provide a hashed delivery idempotency key. They do not verify webhooks, authorize owners or replace durable ingress/delivery deduplication. Reuse your existing authenticated webhook, ownership lock and message sender. See the [private ingress example](https://github.com/weaccelerateinc/accelerate/blob/main/products/agent-sdk/examples/private-chat-ingress.js).
 
 ## Safe results and recovery
 

package/approved-extension-releases/0.0.0.1.json

@@ -25,7 +25,9 @@
       "0.10.0",
       "0.10.1",
       "0.10.2",
-      "0.10.3"
+      "0.10.3",
+      "0.10.4",
+      "0.11.0"
     ],
     "executor_contract": "accelerate_manual_checkout_v1"
   },

package/approved-extension-releases/0.0.0.2.json

@@ -24,7 +24,9 @@
       "0.10.0",
       "0.10.1",
       "0.10.2",
-      "0.10.3"
+      "0.10.3",
+      "0.10.4",
+      "0.11.0"
     ],
     "executor_contract": "accelerate_manual_checkout_v1"
   },

package/approved-extension.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 
-const SDK_VERSION = '0.10.3';
+const SDK_VERSION = '0.11.0';
 const EXECUTOR_CONTRACT = 'accelerate_manual_checkout_v1';
 const BRIDGE_PROTOCOL = 'accelerate_extension_bridge_v1';
 const LEGACY_SHA256 = '65574cbb27ab344687963f72a136f2653551b57458b284e486946b27699099c8';

package/browser-connector.d.ts

@@ -46,8 +46,22 @@ export interface BrowserConnectorHost {
   }>, options: RequestOptions): Promise<{
     provider_browser_stopped: true; credentials_cleared: true; fence_retained: true;
   }>;
+  /** Optional, but REQUIRED for purchase. Perform exactly one trusted pointer click on the unique selector in the exact bound
+   * browser, document and URL under the existing owner fence. No retry, no general DOM reads, never lift the fence.
+   * Accelerate sends no physical input. A thrown error or dispatched:false is observation only; the caller then completes once. */
+  performFinalClick?(context: Readonly<ManagedCheckoutContext>, request: Readonly<FinalClickRequest>, options: RequestOptions): Promise<{ dispatched: boolean }>;
+}
+/** Private request to the customer-owned browser host for the ONE physical final click. Never model/MCP data. */
+export interface FinalClickRequest extends FencedBrowserDocument {
+  checkout_id: CheckoutId;
+  /** Unique selector bound at approval, inside the exact fenced document. */
+  submit_selector: string;
+  armed_expires_at: string;
 }
 declare const attachmentBrand: unique symbol;
+declare const finalClickPreparationBrand: unique symbol;
+/** One-use private readiness proof from prepareFinalClick; valid for one performFinalClick on this connector instance. */
+export interface PreparedFinalClick { readonly [finalClickPreparationBrand]: true }
 /** Private one-connector capability returned only to the authenticated backend. */
 export interface PreparedBrowserAttachment {
   readonly browser: Readonly<CustomerBrowserBinding>;
@@ -70,6 +84,14 @@ export interface BrowserConnector {
   confirmCleanup(context: Readonly<ManagedCheckoutContext>, request: Readonly<{
     checkout_id: CheckoutId;
   }>, options?: RequestOptions): Promise<void>;
+  /** Present only when the host implements performFinalClick. Call BEFORE arming: resolves the fenced owned document, checks
+   * provider/extension readiness and the drained fence, without lifting it, so none of that work consumes the short click window. */
+  prepareFinalClick?(context: Readonly<ManagedCheckoutContext>, request: Readonly<{ checkout_id: CheckoutId }>, options?: RequestOptions): Promise<PreparedFinalClick>;
+  /** Cheap checks only (one-use preparation, exact URL, arm window <= 15s, browser outlives the arm), then asks the customer's
+   * host for one physical click. The arm token never reaches the host. No retry. */
+  performFinalClick?(context: Readonly<ManagedCheckoutContext>, request: Readonly<{
+    checkout_id: CheckoutId; preparation: PreparedFinalClick; checkout_url: string; submit_selector: string; armed_expires_at: string;
+  }>, options?: RequestOptions): Promise<{ dispatched: boolean }>;
 }
 export interface ExistingBrowserConnectorOptions {
   /** Provisioned server connector ID; the Accelerate executor must enable this ID separately. */

package/browser-connector.js

@@ -91,14 +91,14 @@ function makeConnector(configuration, provider) {
     }
   };
   const checkpoint = opts => check(!opts.signal?.aborted, 'request_cancelled');
-  const inspect = async (context, expected, opts, fenceId) => {
+  const inspect = async (context, expected, opts, fenceId, minimum = minimumRemainingMs) => {
     checkpoint(opts);
     const value = await hostCall('inspectBrowser', context, expected, opts);
     checkpoint(opts);
     const actual = record(value, context, config, { readiness: true });
     sameDocument(actual, expected);
     const current = now();
-    check(Number.isFinite(current) && Date.parse(actual.expires_at) - current >= minimumRemainingMs &&
+    check(Number.isFinite(current) && Date.parse(actual.expires_at) - current >= minimum &&
       value.recording_disabled === true, 'integration_unavailable');
     check(object(value.extension) && value.extension.artifact_sha256 === release.artifact.sha256, 'integration_unavailable');
     try { verifyApprovedExtensionRuntime(value.extension, release, { executorContract: 'accelerate_manual_checkout_v1', provider }); }
@@ -115,6 +115,44 @@ function makeConnector(configuration, provider) {
     checkpoint(opts);
     return record(resolved, context, config, { fenced: true });
   };
+  const stamp = value => {
+    check(typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T[\d:.]+Z$/u.test(value) && Number.isFinite(Date.parse(value)), 'invalid_input');
+    return Date.parse(value);
+  };
+  const preparations = new WeakMap();
+  const canClick = typeof host.performFinalClick === 'function';
+  // Slow work (ownership lookup, provider read, runtime inspection) happens here, BEFORE the short arm exists,
+  // so none of it consumes the click window. The fence is never lifted. One preparation serves one click.
+  const prepareClick = canClick ? async (contextValue, input, requestOptions) => {
+    const context = owner(contextValue), opts = options(requestOptions);
+    shape(input, ['checkout_id'], [], 'invalid_input');
+    const expected = await resolve(context, input.checkout_id, opts);
+    // Fenced, drained runtime check; the ten-minute attachment headroom does not apply after the review window.
+    await inspect(context, expected, opts, expected.fence_id, 1);
+    const preparation = Object.freeze({});
+    preparations.set(preparation, { context, checkout_id: input.checkout_id, record: expected, at: now(), used: false });
+    return preparation;
+  } : undefined;
+  const finalClick = canClick ? async (contextValue, input, requestOptions) => {
+    const context = owner(contextValue), opts = options(requestOptions);
+    shape(input, ['checkout_id', 'preparation', 'checkout_url', 'submit_selector', 'armed_expires_at'], [], 'invalid_input');
+    const saved = preparations.get(input.preparation);
+    check(saved && !saved.used && sameOwner(saved.context, context) && saved.checkout_id === input.checkout_id, 'permission_denied');
+    saved.used = true;
+    check(typeof input.submit_selector === 'string' && input.submit_selector.length > 0 && input.submit_selector.length <= 200 &&
+      !/[\u0000-\u001f\u007f]/u.test(input.submit_selector), 'invalid_input');
+    const armedUntil = stamp(input.armed_expires_at), started = now();
+    // The service arm lives at most 15 seconds (never accepted longer); refuse an expired or implausibly long window.
+    check(Number.isFinite(started) && armedUntil > started && armedUntil - started <= 15000 && started - saved.at <= 60000, 'submit_unavailable');
+    // Cheap checks only inside the arm window: exact URL, browser outlives the arm, then the customer's physical click.
+    check(url(input.checkout_url) === saved.record.checkout_url && Date.parse(saved.record.expires_at) > armedUntil, 'permission_denied');
+    checkpoint(opts);
+    const result = await hostCall('performFinalClick', context, freeze({ checkout_id: input.checkout_id,
+      submit_selector: input.submit_selector, armed_expires_at: input.armed_expires_at, ...saved.record }), opts);
+    shape(result, ['dispatched'], [], 'integration_unavailable');
+    check(typeof result.dispatched === 'boolean', 'integration_unavailable');
+    return Object.freeze({ dispatched: result.dispatched });
+  } : undefined;
   // Every method belongs to the server integration. A connector never creates a
   // replacement browser, releases its durable fence or retries a payment call.
   return Object.freeze({ contract: 'accelerate_existing_browser_v1', provider,
@@ -163,6 +201,7 @@ function makeConnector(configuration, provider) {
       if (input.checkout_url !== undefined) check(url(input.checkout_url) === expected.checkout_url, 'permission_denied');
       await inspect(context, expected, opts, expected.fence_id);
     },
+    ...(finalClick ? { prepareFinalClick: prepareClick, performFinalClick: finalClick } : {}),
     async confirmCleanup(contextValue, input, requestOptions) {
       const context = owner(contextValue), opts = options(requestOptions);
       shape(input, ['checkout_id'], [], 'invalid_input');

package/browser-use-host.d.ts

@@ -22,6 +22,9 @@ export interface BrowserUsePlatformHost {
    * if suspended. Do not create/navigate a page or accept model-authored code. */
   inspectDocument(context: Readonly<ManagedCheckoutContext>, browser: Readonly<OwnedBrowserDocument>,
     runtime: Readonly<{ runtime_id: string }>, options: RequestOptions): Promise<BrowserUseDocumentObservation>;
+  /** Optional; required for purchase. One trusted pointer click on the unique bound selector in the exact fenced document,
+   * through your existing server browser control. No retry, no general DOM reads, never lift the fence. */
+  performFinalClick?: BrowserConnectorHost['performFinalClick'];
   /** Independently verify extension/page cleanup and retain every payment uncertainty fence. */
   confirmLocalCleanup(context: Readonly<ManagedCheckoutContext>, browser: Readonly<FencedBrowserDocument>,
     request: Readonly<{ checkout_id: import('./index.js').CheckoutId }>, options: RequestOptions): Promise<{

package/browser-use-host.js

@@ -131,6 +131,8 @@ export function createBrowserUseHost(configuration = {}) {
         recording_disabled: true, extension,
         automation: current.automation };
     },
+    // Optional: only a platform host that can click may enable purchases. Readiness was read by prepareFinalClick before the arm.
+    ...(typeof host.performFinalClick === 'function' ? { performFinalClick: (...args) => callHost('performFinalClick', ...args) } : {}),
     drainAndFence: (...args) => callHost('drainAndFence', ...args),
     bindCheckout: (...args) => callHost('bindCheckout', ...args),
     resolveCheckoutBrowser: (...args) => callHost('resolveCheckoutBrowser', ...args),

package/checkout-diagnostics.d.ts

@@ -1,9 +1,19 @@
 export type CheckoutDiagnosticStage = 'not_started' | 'identity_required' | 'otp_required' | 'selection_required' |
-  'preparing_checkout' | 'approval_required' | 'cvv_required' | 'approved' | 'ready_for_submit' | 'review_delivery_required' | 'review_delivered' | 'approved_for_submit' |
+  'preparing_checkout' | 'approval_required' | 'cvv_required' | 'approved' | 'ready_for_submit' | 'review_delivery_required' | 'review_delivered' | 'approved_for_submit' | 'final_click_armed' |
   'cancelled' | 'expired' | 'failed' | 'submit_attempted' | 'outcome_unknown';
 export type CheckoutDiagnosticAction = 'get_status' | 'continue_private_chat' | 'prepare_checkout' | 'apply_details' |
   'request_approval' | 'fill' | 'submit' | 'cancel' | 'reconcile_order';
 export type CheckoutCleanupStatus = 'not_required' | 'not_started' | 'pending' | 'confirmed';
+export type CheckoutReconciliationState = 'confirmed' | 'declined' | 'not_found';
+/** The client backend's statement of the merchant's result. Not Accelerate's proof: payment_confirmed stays false. */
+export interface CheckoutReconciliation {
+  state: CheckoutReconciliationState;
+  /** Short label for where the client read the result, such as merchant_order_api. */
+  source: string;
+  amount_cents: number | null;
+  currency: 'USD' | null;
+  reconciled_at: string;
+}
 export interface CheckoutDiagnostics {
   version: 'v1';
   stage: CheckoutDiagnosticStage;
@@ -19,5 +29,6 @@ export const checkoutDiagnosticActions: readonly CheckoutDiagnosticAction[];
 export const checkoutCleanupStatuses: readonly CheckoutCleanupStatus[];
 export const checkoutDiagnosticsJsonSchema: Readonly<Record<string, unknown>>;
 export function validateCheckoutDiagnostics(value: unknown, checkout?: {
-  status: string; purpose?: string; submit_allowed?: boolean; submit_expires_at?: string; approval_policy?: string; purchase_approved?: boolean;
+  status: string; purpose?: string; submit_allowed?: boolean; submit_expires_at?: string; approval_policy?: string; purchase_approved?: boolean; reconciliation?: unknown; final_click_actor?: string;
 }): CheckoutDiagnostics;
+export function validateCheckoutReconciliation(value: unknown, status?: string): CheckoutReconciliation;

package/checkout-diagnostics.js

@@ -1,6 +1,6 @@
 // Safe lifecycle metadata only. No transport, credentials, provider text or automatic actions.
 export const checkoutDiagnosticStages = Object.freeze(['not_started', 'identity_required', 'otp_required', 'selection_required',
-    'preparing_checkout', 'approval_required', 'cvv_required', 'approved', 'ready_for_submit', 'review_delivery_required', 'review_delivered', 'approved_for_submit',
+    'preparing_checkout', 'approval_required', 'cvv_required', 'approved', 'ready_for_submit', 'review_delivery_required', 'review_delivered', 'approved_for_submit', 'final_click_armed',
     'cancelled', 'expired', 'failed', 'submit_attempted', 'outcome_unknown']);
 export const checkoutDiagnosticActions = Object.freeze(['get_status', 'continue_private_chat', 'prepare_checkout', 'apply_details',
     'request_approval', 'fill', 'submit', 'cancel', 'reconcile_order']);
@@ -38,7 +38,7 @@ export function validateCheckoutDiagnostics(input, checkout) {
         typeof value.support_reference === 'string' && /^acs_[a-f0-9]{32}$/.test(value.support_reference) &&
         checkoutCleanupStatuses.includes(value.cleanup_status) && (value.submit_deadline === undefined || timestamp(value.submit_deadline)));
     if (checkout !== undefined) {
-        const { status, purpose = 'purchase', submit_allowed, approval_policy, purchase_approved } = checkout;
+        const { status, purpose = 'purchase', submit_allowed, approval_policy, purchase_approved, reconciliation, final_click_actor } = checkout;
         check(terminal.has(status) ? value.stage === status : status === 'wallet_required'
             ? ['not_started', 'identity_required', 'otp_required', 'selection_required'].includes(value.stage)
             : ['selection_ready', 'details_ready'].includes(status) ? value.stage === 'preparing_checkout'
@@ -46,7 +46,7 @@ export function validateCheckoutDiagnostics(input, checkout) {
         check(status === 'ready_for_submit' ? timestamp(value.submit_deadline) && value.submit_deadline === checkout.submit_expires_at : value.submit_deadline === undefined);
         for (const action of value.next_actions) {
             if (action === 'submit')
-                check(status === 'ready_for_submit' && purpose === 'purchase' && submit_allowed !== false && (approval_policy !== 'after_fill' || purchase_approved === true));
+                check(status === 'ready_for_submit' && purpose === 'purchase' && submit_allowed !== false && final_click_actor === 'customer' && (approval_policy !== 'after_fill' || purchase_approved === true));
             if (action === 'fill')
                 check(status === 'approved' && purpose !== 'sandbox_source_comparison');
             if (['prepare_checkout', 'apply_details'].includes(action))
@@ -56,8 +56,11 @@ export function validateCheckoutDiagnostics(input, checkout) {
             if (action === 'continue_private_chat')
                 check(['wallet_required', 'approval_required'].includes(status) || approval_policy === 'after_fill' && status === 'ready_for_submit' && !purchase_approved);
             if (action === 'reconcile_order')
-                check(['submit_attempted', 'outcome_unknown'].includes(status));
+                check(['submit_attempted', 'outcome_unknown'].includes(status) && reconciliation === undefined);
         }
+        // While a customer click is armed only a safe read or cancel is advertised: no browser work, no re-arm.
+        if (status === 'final_click_armed')
+            check(value.next_actions.every(action => ['get_status', 'cancel'].includes(action)));
         if (!terminal.has(status))
             check(value.cleanup_status !== 'pending' && value.cleanup_status !== 'confirmed');
         if (terminal.has(status))
@@ -65,3 +68,14 @@ export function validateCheckoutDiagnostics(input, checkout) {
     }
     return value;
 }
+/** Validate the client backend's stored statement of the merchant's result. Never proof of payment. */
+export function validateCheckoutReconciliation(input, status) {
+    const value = input;
+    check(value !== null && typeof value === 'object' && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value)) &&
+        Object.keys(value).length === 5 && ['confirmed', 'declined', 'not_found'].includes(value.state) &&
+        typeof value.source === 'string' && /^[a-z][a-z0-9_.-]{0,39}$/.test(value.source) && !/(?:\d[ -]?){13,19}/.test(value.source) &&
+        (value.amount_cents === null || Number.isSafeInteger(value.amount_cents) && value.amount_cents > 0 && value.amount_cents <= 2147483647) &&
+        (value.currency === null || value.currency === 'USD') && (value.state !== 'confirmed' || value.amount_cents !== null && value.currency === 'USD') &&
+        timestamp(value.reconciled_at) && (status === undefined || ['submit_attempted', 'outcome_unknown'].includes(status)));
+    return value;
+}

package/cli.js

@@ -18,7 +18,10 @@ It does not qualify the downstream payment source or browser configuration.
 
 Init copies the packaged synthetic MCP starter without credentials, network
 requests or overwrites. --browser existing selects the new provider-independent
-existing-browser starter; omission preserves the managed Kernel starter.
+existing-browser starter with purchase purpose and a submit tool; omission
+preserves the managed Kernel starter, which is fill-only. Both start in
+synthetic mode. Purchase requires private approval, an explicit submit and your
+own browser host performing the one final click: Accelerate never clicks.
 Existing symlink paths and nonempty targets are rejected.
 `;
 const starterFiles = ['package.json', '.env.example', '.gitignore', 'README.md', 'server.mjs', 'runtime.mjs',

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) {

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. */
@@ -125,6 +149,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;
@@ -165,6 +192,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 +240,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>;
   };
 }