@weaccelerateinc/agent-sdk 0.10.3 → 0.12.0

package/README.md

@@ -1,9 +1,13 @@
-# @weaccelerateinc/agent-sdk 0.10.3
+# @weaccelerateinc/agent-sdk 0.12.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`.
+SDK 0.12.0 adds opt-in Browser Use run-created fill-only checkout, exact additional-extension policies, and private WhatsApp adapters with durable sent-receipt reconciliation. The platform must implement durable owner/session/viewer fences and qualify its provider. Existing connector defaults and the 0.11.0 customer-final-click purchase contract remain. The approved extension ZIP is unchanged; its compatibility metadata includes 0.12.0.
+
+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.12.0`. Check `npm view @weaccelerateinc/agent-sdk@0.12.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.12.0
 npx --no-install accelerate-agent init ./partner-demo --browser existing
 ```
 
@@ -25,15 +29,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 +121,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,10 @@
       "0.10.0",
       "0.10.1",
       "0.10.2",
-      "0.10.3"
+      "0.10.3",
+      "0.10.4",
+      "0.11.0",
+      "0.12.0"
     ],
     "executor_contract": "accelerate_manual_checkout_v1"
   },

package/approved-extension-releases/0.0.0.2.json

@@ -24,7 +24,10 @@
       "0.10.0",
       "0.10.1",
       "0.10.2",
-      "0.10.3"
+      "0.10.3",
+      "0.10.4",
+      "0.11.0",
+      "0.12.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.12.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

@@ -1,4 +1,5 @@
 import { AccelerateError } from './index.js';
+import { browserUseRunProvenance, sameBrowserUseProvenance } from './browser-provenance.js';
 import { normalizeBrowserOperation } from './browser-operations.js';
 import { validateApprovedExtensionRelease, verifyApprovedExtensionRuntime } from './approved-extension.js';
 
@@ -40,11 +41,14 @@ function options(value = {}) {
   return Object.freeze(value.signal ? { signal: value.signal } : {});
 }
 function browser(value, provider, connectorId) {
-  shape(value, ['provider', 'browser_id', 'custody_mode'], provider === 'connector' ? ['connector_id'] : [], 'permission_denied');
+  shape(value, ['provider', 'browser_id', 'custody_mode'], provider === 'connector' ? ['connector_id'] : ['provenance'], 'permission_denied');
   check(value.provider === provider && value.custody_mode === 'customer_backend_trusted' &&
     typeof value.browser_id === 'string' && (provider === 'browser_use' ? UUID : OPAQUE).test(value.browser_id) &&
     (provider !== 'connector' || value.connector_id === connectorId), 'permission_denied');
-  return { ...value };
+  let provenance;
+  try { if (value.provenance !== undefined) provenance = browserUseRunProvenance(value.provenance); }
+  catch { throw new AccelerateError('permission_denied'); }
+  return { ...value, ...(provenance ? { provenance } : {}) };
 }
 function record(value, context, config, { fenced = false, readiness = false, checkoutUrl } = {}) {
   shape(value, DOC, [...(fenced ? ['fence_id'] : []), ...(readiness ? ['recording_disabled', 'extension', 'automation'] : [])], 'permission_denied');
@@ -66,6 +70,7 @@ function record(value, context, config, { fenced = false, readiness = false, che
 function sameDocument(actual, expected) {
   check(actual.document_id === expected.document_id && actual.checkout_url === expected.checkout_url &&
     ['provider', 'browser_id', 'connector_id', 'custody_mode'].every(key => actual.browser[key] === expected.browser[key]) &&
+    sameBrowserUseProvenance(actual.browser.provenance, expected.browser.provenance) &&
     actual.expires_at === expected.expires_at, 'permission_denied');
 }
 function makeConnector(configuration, provider) {
@@ -91,14 +96,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 +120,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 +206,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-provenance.js

@@ -0,0 +1,17 @@
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/u;
+const fields = ['type', 'run_id', 'session_id', 'provider_workspace_id', 'binding_sha256'];
+/** Private backend binding. Provider workspace membership is not shopper ownership. */
+export function browserUseRunProvenance(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(value)) || Object.keys(value).length !== fields.length ||
+    !fields.every(key => Object.hasOwn(value, key)) || value.type !== 'browser_use_run_v1' ||
+    !uuid.test(value.run_id) || !uuid.test(value.session_id) ||
+    !(value.provider_workspace_id === null || uuid.test(value.provider_workspace_id)) ||
+    typeof value.binding_sha256 !== 'string' || !/^[a-f0-9]{64}$/u.test(value.binding_sha256)) throw Error('Invalid browser provenance.');
+  return Object.freeze(Object.fromEntries(fields.map(key => [key, value[key]])));
+}
+export function sameBrowserUseProvenance(a, b) {
+  if (a === undefined || b === undefined) return a === b;
+  try { return JSON.stringify(browserUseRunProvenance(a)) === JSON.stringify(browserUseRunProvenance(b)); }
+  catch { return false; }
+}

package/browser-use-host.d.ts

@@ -10,6 +10,9 @@ export interface BrowserUseDocumentObservation {
   checkout_url: string;
   extension: Omit<ApprovedExtensionRuntime, 'artifact_sha256'>;
   automation: BrowserReadiness['automation'];
+  /** Required after a run-created browser is fenced. Derived from the durable session store,
+   * including queued/follow-up work, live-view issuance and human takeover routes. */
+  run_control?: { checkout_reserved: true; session_scheduling_fenced: true; live_view_blocked: true };
 }
 export interface BrowserUsePlatformHost {
   /** Resolve an EXISTING browser from authenticated durable ownership. SDK reads actual provider expiry. */
@@ -22,6 +25,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<{
@@ -35,8 +41,16 @@ export function createBrowserUseHost(options: {
   apiKey: string;
   merchantId: string;
   extensionId: string;
+  /** Primary runtime ID pinned in durable operator installation configuration.
+   * Required for run-created or multi-extension mode; stable across host restarts. */
+  extensionRuntimeId?: string;
   extensionRelease: ApprovedExtensionRelease;
   host: BrowserUsePlatformHost;
+  /** Requires a durable owned run reservation and a fence covering all session runs and queued work.
+   * The executor must separately enable this merchant. Default false. */
+  allowRunCreatedBrowsers?: boolean;
+  /** Complete additional extension set approved for this merchant/provider. This is not qualification evidence. */
+  additionalExtensions?: ReadonlyArray<Readonly<{ id: string; runtimeId: string; version: string }>>;
   fetchImpl?: typeof fetch;
   /** Test clock only. */
   now?: () => number;

package/browser-use-host.js

@@ -1,4 +1,5 @@
 import { AccelerateError } from './index.js';
+import { browserUseRunProvenance } from './browser-provenance.js';
 import { validateApprovedExtensionRelease, verifyApprovedExtensionRuntime } from './approved-extension.js';
 import { normalizeBrowserOperation } from './browser-operations.js';
 
@@ -44,12 +45,23 @@ const freeze = value => {
 };
 
 export function createBrowserUseHost(configuration = {}) {
-  exact(configuration, ['apiKey', 'merchantId', 'extensionId', 'extensionRelease', 'host'], ['fetchImpl', 'now']);
-  const { apiKey, merchantId, extensionId, host, fetchImpl = fetch, now = Date.now } = configuration;
+  exact(configuration, ['apiKey', 'merchantId', 'extensionId', 'extensionRelease', 'host'], ['fetchImpl', 'now', 'allowRunCreatedBrowsers', 'additionalExtensions', 'extensionRuntimeId']);
+  const { apiKey, merchantId, extensionId, host, fetchImpl = fetch, now = Date.now,
+    allowRunCreatedBrowsers = false, additionalExtensions = [], extensionRuntimeId } = configuration;
   check(typeof apiKey === 'string' && apiKey.length >= 16 && apiKey.length <= 500 && !/[\u0000-\u0020\u007f]/u.test(apiKey) &&
     UUID.test(merchantId) && UUID.test(extensionId) && typeof fetchImpl === 'function' && typeof now === 'function' && host &&
     ['resolveOwnedBrowser', 'drainAndFence', 'bindCheckout', 'resolveCheckoutBrowser', 'inspectDocument', 'confirmLocalCleanup']
       .every(key => typeof host[key] === 'function'), 'configuration_invalid');
+  check(typeof allowRunCreatedBrowsers === 'boolean' && Array.isArray(additionalExtensions) && additionalExtensions.length <= 2, 'configuration_invalid');
+  check(extensionRuntimeId === undefined || RUNTIME.test(extensionRuntimeId), 'configuration_invalid');
+  check(!(allowRunCreatedBrowsers || additionalExtensions.length) || RUNTIME.test(extensionRuntimeId ?? ''), 'configuration_invalid');
+  const extensionIds = new Set([extensionId]), runtimes = new Set();
+  const extras = additionalExtensions.map(value => {
+    exact(value, ['id', 'runtimeId', 'version']);
+    check(UUID.test(value.id) && RUNTIME.test(value.runtimeId) && typeof value.version === 'string' &&
+      /^\d+(?:\.\d+){0,3}$/u.test(value.version) && !extensionIds.has(value.id) && !runtimes.has(value.runtimeId), 'configuration_invalid');
+    extensionIds.add(value.id); runtimes.add(value.runtimeId); return Object.freeze({ ...value });
+  });
   let release;
   try { release = validateApprovedExtensionRelease(configuration.extensionRelease); }
   catch { throw new AccelerateError('configuration_invalid'); }
@@ -58,21 +70,25 @@ export function createBrowserUseHost(configuration = {}) {
     try { return await host[method](...args); }
     catch { throw new AccelerateError('integration_unavailable'); }
   };
-  const owned = (context, document) => {
+  const owned = (context, document, cleanup = false) => {
     exact(document, ['owner', 'browser', 'document_id', 'checkout_url'], ['expires_at', 'fence_id']);
     exact(document.owner, ['customer_id', 'workspace_id', 'conversation_id', 'phone_number']);
     check(['customer_id', 'workspace_id', 'conversation_id', 'phone_number'].every(key => document.owner[key] === context[key]), 'permission_denied');
-    exact(document.browser, ['provider', 'browser_id', 'custody_mode']);
+    exact(document.browser, ['provider', 'browser_id', 'custody_mode'], ['provenance']);
     check(document.browser.provider === 'browser_use' && document.browser.custody_mode === 'customer_backend_trusted' && UUID.test(document.browser.browser_id) &&
       typeof document.document_id === 'string' && /^[A-Za-z0-9_.:-]{1,200}$/u.test(document.document_id), 'permission_denied');
     try { normalizeBrowserOperation('navigate', { url: document.checkout_url }); }
     catch { throw new AccelerateError('permission_denied'); }
-    return { owner: { ...document.owner }, browser: { ...document.browser }, document_id: document.document_id, checkout_url: document.checkout_url };
+    let provenance;
+    if (Object.hasOwn(document.browser, 'provenance')) {
+      check(allowRunCreatedBrowsers || cleanup && typeof document.fence_id === 'string' && document.fence_id.length > 0, 'permission_denied');
+      try { provenance = browserUseRunProvenance(document.browser.provenance); }
+      catch { throw new AccelerateError('permission_denied'); }
+    }
+    return { owner: { ...document.owner }, browser: { ...document.browser, ...(provenance ? { provenance } : {}) }, document_id: document.document_id, checkout_url: document.checkout_url };
   };
-  const resource = async (context, document, requiredStatus, options = {}) => {
-    const binding = owned(context, document).browser;
-    const timeout = AbortSignal.timeout(10000), signal = AbortSignal.any([timeout, ...(options.signal ? [options.signal] : [])]);
-    const endpoint = `${BASE}/browsers/${binding.browser_id}`;
+  const providerRead = async (path, signal) => {
+    const endpoint = `${BASE}${path}`;
     let response;
     try {
       check(!signal.aborted);
@@ -85,26 +101,63 @@ export function createBrowserUseHost(configuration = {}) {
         /^application\/json(?:\s*;|$)/iu.test(response.headers.get('content-type') ?? '') && response.body);
       const length = response.headers.get('content-length');
       check(length === null || /^\d+$/u.test(length) && Number(length) <= 262144);
-      const value = await json(response, signal);
+      return await json(response, signal);
+    } finally { void response?.body?.cancel().catch(() => {}); }
+  };
+  const resource = async (context, document, requiredStatus, options = {}) => {
+    const binding = owned(context, document, requiredStatus === 'stopped').browser;
+    const timeout = AbortSignal.timeout(10000), signal = AbortSignal.any([timeout, ...(options.signal ? [options.signal] : [])]);
+    try {
+      const value = await providerRead(`/browsers/${binding.browser_id}`, signal);
       const metadata = value?.metadata;
+      let runEvidence;
+      if (binding.provenance) {
+        const provenance = binding.provenance;
+        const run = await providerRead(`/runs/${provenance.run_id}`, signal);
+        check(object(run) && run.id === provenance.run_id && run.sessionId === provenance.session_id &&
+          run.workspaceId === provenance.provider_workspace_id && value.agentSessionId === provenance.session_id);
+        // A breached scheduling fence must block payment, but must not prevent
+        // confirmation that this exact original owned browser has stopped.
+        if (requiredStatus !== 'stopped') {
+        const session = await providerRead(`/sessions/${provenance.session_id}`, signal);
+        const queue = await providerRead(`/sessions/${provenance.session_id}/queue`, signal);
+        check(['completed', 'cancelled'].includes(run.status) &&
+          object(session) && session.sessionId === provenance.session_id && session.latestRunId === provenance.run_id &&
+          session.workspaceId === provenance.provider_workspace_id && ['completed', 'cancelled'].includes(session.status) &&
+          object(queue) && Array.isArray(queue.queue) && queue.queue.length === 0 && value.agentSessionId === provenance.session_id);
+        runEvidence = { agentSessionId: value.agentSessionId,
+          agentRun: { id: run.id, sessionId: run.sessionId, workspaceId: run.workspaceId, status: run.status },
+          agentSession: { sessionId: session.sessionId, workspaceId: session.workspaceId, latestRunId: session.latestRunId, status: session.status },
+          agentQueue: { queue: [] } };
+        }
+      }
       check(object(value) && value.id === binding.browser_id && value.status === requiredStatus &&
         value.recordingAvailable === false && (value.recordingUrl == null || value.recordingUrl === '') &&
-        object(metadata) && metadata.accelerate_merchant_id === merchantId &&
+        (binding.provenance || object(metadata) && metadata.accelerate_merchant_id === merchantId &&
         metadata.accelerate_owner_user_id === context.customer_id && metadata.accelerate_workspace_id === context.workspace_id &&
         metadata.accelerate_custody_mode === 'customer_backend_trusted' && metadata.accelerate_agent_extension_id === extensionId &&
-        metadata.accelerate_extension_sha256 === release.artifact.sha256 && metadata.accelerate_extension_version === release.extension_version &&
+        metadata.accelerate_extension_sha256 === release.artifact.sha256 && metadata.accelerate_extension_version === release.extension_version) &&
         typeof value.timeoutAt === 'string' && Number.isFinite(Date.parse(value.timeoutAt)) &&
         (requiredStatus === 'stopped' || Date.parse(value.timeoutAt) > now()) &&
-        Array.isArray(value.extensions) && value.extensions.length === 1 && value.extensions[0]?.id === extensionId &&
-        value.extensions[0]?.version === release.extension_version && RUNTIME.test(value.extensions[0]?.runtimeId ?? ''));
+        Array.isArray(value.extensions) && value.extensions.length === extras.length + 1 &&
+        new Set(value.extensions.map(item => item?.id)).size === value.extensions.length &&
+        new Set(value.extensions.map(item => item?.runtimeId)).size === value.extensions.length);
+      const primary = value.extensions.find(item => item?.id === extensionId);
+      check(primary?.version === release.extension_version && RUNTIME.test(primary?.runtimeId ?? '') &&
+        extras.every(expected => value.extensions.some(item => ['id', 'version', 'runtimeId'].every(key => item?.[key] === expected[key]))));
+      check(extensionRuntimeId === undefined || primary.runtimeId === extensionRuntimeId);
       // Deliberately project away provider CDP/viewer URLs and unknown response fields.
-      const read = freeze({ expires_at: value.timeoutAt, runtime_id: value.extensions[0].runtimeId });
+      const read = freeze({ expires_at: value.timeoutAt, runtime_id: primary.runtimeId });
       if (!options.withConnection) return read;
       check(typeof value.cdpUrl === 'string' && value.cdpUrl.length <= 2048 && typeof value.startedAt === 'string');
       return freeze({ ...read, connection: freeze({ id: value.id, status: value.status, cdpUrl: value.cdpUrl, startedAt: value.startedAt,
-        timeoutAt: value.timeoutAt, recordingAvailable: false, metadata, extensions: value.extensions }) });
+        timeoutAt: value.timeoutAt, recordingAvailable: false,
+        metadata: binding.provenance ? {} : Object.fromEntries(['accelerate_merchant_id', 'accelerate_owner_user_id',
+          'accelerate_workspace_id', 'accelerate_custody_mode', 'accelerate_agent_extension_id',
+          'accelerate_extension_sha256', 'accelerate_extension_version'].map(key => [key, metadata[key]])),
+        extensions: value.extensions.map(item => ({ id: item.id, runtimeId: item.runtimeId, version: item.version })),
+        ...runEvidence }) });
     } catch {
-      void response?.body?.cancel().catch(() => {});
       throw new AccelerateError(options.signal?.aborted ? 'request_cancelled' : 'integration_unavailable');
     }
   };
@@ -121,7 +174,11 @@ export function createBrowserUseHost(configuration = {}) {
     async inspectBrowser(context, document, options) {
       const observed = await resource(context, document, 'active', options);
       const current = await callHost('inspectDocument', context, document, freeze({ runtime_id: observed.runtime_id }), options);
-      exact(current, ['document_id', 'checkout_url', 'extension', 'automation']);
+      exact(current, ['document_id', 'checkout_url', 'extension', 'automation'], ['run_control']);
+      if (document.browser.provenance && current.automation?.agent_access_fenced === true) {
+        exact(current.run_control, ['checkout_reserved', 'session_scheduling_fenced', 'live_view_blocked']);
+        check(Object.values(current.run_control).every(value => value === true));
+      }
       exact(current.extension, ['extension_version', 'success', 'initialized', 'wasmInitialized', 'autosaveDisabled',
         'boundedRetentionSupported', 'maximumRetentionMs'], ['bridge_protocol']);
       const extension = { ...current.extension, artifact_sha256: release.artifact.sha256 };
@@ -131,6 +188,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.d.ts

@@ -70,6 +70,11 @@ export interface DurableCheckoutHost<Extra = unknown> {
    * without uploading/sending the same review again. */
   withPrivateDelivery(context: ManagedCheckoutContext, idempotencyKey: string,
     deliver: () => Promise<{ message_id: string; sent_at: string }>): Promise<Readonly<{ message_id: string; sent_at: string }>>;
+  /** Recover only an existing pending delivery under its owner lock. lookup must
+   * be a trusted read-only journal function binding exact context, destination,
+   * and prompt idempotency key; it must never upload or send. */
+  reconcilePrivateDelivery(context: ManagedCheckoutContext, idempotencyKey: string,
+    lookup: (context: Readonly<ManagedCheckoutContext>, idempotencyKey: string) => Promise<{ message_id: string; sent_at: string }>): Promise<Readonly<{ message_id: string; sent_at: string }>>;
   /** Call ONLY after connector independently verifies stopped/cleared and retained fence. */
   confirmBrowserCleanup(context: ManagedCheckoutContext, checkoutId: CheckoutId): Promise<void>;
   withPrivateCheckout<T>(context: ManagedCheckoutContext, metadata: PrivateHostOperation,