@weaccelerateinc/agent-sdk 0.11.0 → 0.12.0

package/README.md

@@ -1,11 +1,13 @@
-# @weaccelerateinc/agent-sdk 0.11.0
+# @weaccelerateinc/agent-sdk 0.12.0
+
+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.11.0`. Check `npm view @weaccelerateinc/agent-sdk@0.11.0 version` to confirm registry availability. The package remains `UNLICENSED`.
+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.11.0
+npm install --ignore-scripts @weaccelerateinc/agent-sdk@0.12.0
 npx --no-install accelerate-agent init ./partner-demo --browser existing
 ```
 

package/approved-extension-releases/0.0.0.1.json

@@ -27,7 +27,8 @@
       "0.10.2",
       "0.10.3",
       "0.10.4",
-      "0.11.0"
+      "0.11.0",
+      "0.12.0"
     ],
     "executor_contract": "accelerate_manual_checkout_v1"
   },

package/approved-extension-releases/0.0.0.2.json

@@ -26,7 +26,8 @@
       "0.10.2",
       "0.10.3",
       "0.10.4",
-      "0.11.0"
+      "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.11.0';
+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.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) {

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. */
@@ -38,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 };

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,

package/host-adapter.js

@@ -300,6 +300,18 @@ export function createDurableCheckoutHost({ persistence, resolveContext } = {})
       check(MESSAGE.test(receipt.message_id) && validDate(receipt.sent_at) && Date.parse(receipt.sent_at) <= Date.now(), 'invalid_response');
       entry.receipt = clone(receipt); await commit(active); return Object.freeze(clone(receipt));
     }),
+    reconcilePrivateDelivery: (context, idempotencyKey, lookup) => locked(context, async (active, resolved) => {
+      check(/^accelerate-chat:[a-f0-9]{64}$/.test(idempotencyKey) && typeof lookup === 'function');
+      const entry = active.record.deliveries?.find(item => item.idempotency_key === idempotencyKey);
+      check(entry && active.record.attempt?.checkout_id, 'permission_denied');
+      if (entry.receipt) return Object.freeze(clone(entry.receipt));
+      // Only a trusted read-only journal lookup may be passed here. It must bind
+      // the exact owner, destination and prompt key; it must never send.
+      const receipt = await lookup(Object.freeze({ ...resolved }), idempotencyKey);
+      exact(receipt, ['message_id', 'sent_at'], [], 'invalid_response');
+      check(MESSAGE.test(receipt.message_id) && validDate(receipt.sent_at) && Date.parse(receipt.sent_at) <= Date.now(), 'invalid_response');
+      entry.receipt = clone(receipt); await commit(active); return Object.freeze(clone(receipt));
+    }),
     confirmBrowserCleanup: (context, checkoutId) => locked(context, async active => {
       check(active.record.attempt?.checkout_id === checkoutId && active.record.attempt.checkout?.diagnostics?.cleanup_status === 'confirmed', 'operation_conflict');
       active.record.attempt.cleanup_confirmed = true; await commit(active);

package/index.d.ts

@@ -88,6 +88,16 @@ export interface BrowserUseBrowserBinding {
   provider: 'browser_use';
   browser_id: string;
   custody_mode: 'customer_backend_trusted';
+  /** Opt-in provider run binding from a durable authenticated owner mapping. Never model input. */
+  provenance?: BrowserUseRunProvenance;
+}
+export interface BrowserUseRunProvenance {
+  type: 'browser_use_run_v1';
+  run_id: string;
+  session_id: string;
+  provider_workspace_id: string | null;
+  /** SHA-256 of the host's immutable owner/run reservation, not raw shopper data. */
+  binding_sha256: string;
 }
 /** Registered server-side executor connector; IDs are resolved from owned backend records. */
 export interface RegisteredBrowserBinding {
@@ -164,8 +174,12 @@ export interface ClientBrowserResource {
   startedAt: string;
   timeoutAt: string;
   recordingAvailable: false;
+  agentSessionId?: string;
+  agentRun?: { id: string; sessionId: string; workspaceId: string | null; status: 'completed' | 'cancelled' };
+  agentSession?: { sessionId: string; workspaceId: string | null; latestRunId: string; status: 'completed' | 'cancelled' };
+  agentQueue?: { queue: never[] };
   metadata: Record<string, string>;
-  extensions: [{ id: string; version: string; runtimeId: string }];
+  extensions: [{ id: string; version: string; runtimeId: string }, ...{ id: string; version: string; runtimeId: string }[]];
 }
 /** Hypothesis to inspect against the actual checkout; never a caller assertion of currency evidence. */
 export interface QuoteVerificationRequest {

package/index.js

@@ -1,6 +1,7 @@
 import { env as processEnv, versions } from 'node:process';
 import { createHash } from 'node:crypto';
 import { normalizeBrowserOperation } from './browser-operations.js';
+import { browserUseRunProvenance } from './browser-provenance.js';
 import { validateCheckoutDiagnostics, validateCheckoutReconciliation } from './checkout-diagnostics.js';
 export { checkoutDiagnosticsJsonSchema, validateCheckoutDiagnostics } from './checkout-diagnostics.js';
 
@@ -242,7 +243,10 @@ function creationInspectionInput(input) {
   for (const name of ['customer_id', 'workspace_id', 'conversation_id'])
     check(typeof input[name] === 'string' && /^[A-Za-z0-9_.:-]{1,500}$/u.test(input[name]));
   string(input.idempotency_key, 200);
-  keys(input.browser, ['provider', 'browser_id', 'custody_mode']);
+  keys(input.browser, ['provider', 'browser_id', 'custody_mode', 'provenance'], ['provider', 'browser_id', 'custody_mode']);
+  if (Object.hasOwn(input.browser, 'provenance')) {
+    try { browserUseRunProvenance(input.browser.provenance); } catch { check(false); }
+  }
   check(input.browser.provider === 'browser_use' && typeof input.browser.browser_id === 'string' &&
     UUID.test(input.browser.browser_id) && input.browser.browser_id === input.browser.browser_id.toLowerCase() &&
     input.browser.custody_mode === 'customer_backend_trusted');
@@ -450,7 +454,11 @@ export class AccelerateClient {
       input.approval_policy === 'after_fill' && input.browser?.custody_mode === 'customer_backend_trusted');
     check(input.interaction_mode === 'chat' ? typeof input.conversation_id === 'string' && /^[A-Za-z0-9_.:-]{1,500}$/u.test(input.conversation_id) : input.conversation_id === undefined);
     if (input.browser !== undefined) {
-      keys(input.browser, ['provider', 'browser_id', 'custody_mode', ...(input.browser?.provider === 'connector' ? ['connector_id'] : [])]);
+      keys(input.browser, ['provider', 'browser_id', 'custody_mode', ...(input.browser?.provider === 'connector' ? ['connector_id'] : ['provenance'])],
+        ['provider', 'browser_id', 'custody_mode', ...(input.browser?.provider === 'connector' ? ['connector_id'] : [])]);
+      if (Object.hasOwn(input.browser, 'provenance')) {
+        try { browserUseRunProvenance(input.browser.provenance); } catch { check(false); }
+      }
       const supportedBinding = input.browser.provider === 'browser_use'
         ? typeof input.browser.browser_id === 'string' && UUID.test(input.browser.browser_id) && input.browser.browser_id === input.browser.browser_id.toLowerCase()
         : input.browser.provider === 'connector' && typeof input.browser.connector_id === 'string' && /^[a-z][a-z0-9_-]{0,63}$/u.test(input.browser.connector_id) &&

package/managed-mcp.js

@@ -1,4 +1,5 @@
 import { AccelerateClient, AccelerateError } from './index.js';
+import { browserUseRunProvenance } from './browser-provenance.js';
 import { browserOperationJsonSchema, parseBrowserOperation, normalizeBrowserOperation } from './browser-operations.js';
 import { checkoutDiagnosticsJsonSchema, validateCheckoutDiagnostics, validateCheckoutReconciliation } from './checkout-diagnostics.js';
 import { createHash } from 'node:crypto';
@@ -333,7 +334,10 @@ export function registerManagedCheckoutTools(server, { client = AccelerateClient
             requireAdmission();
             const browser = attachment ? attachment.browser : scope.browser;
             if (browserMode === 'customer_backend_trusted') {
-              shape(browser, ['provider', 'browser_id', 'custody_mode'], browser?.provider === 'connector' ? ['connector_id'] : [], 'permission_denied');
+              shape(browser, ['provider', 'browser_id', 'custody_mode'], browser?.provider === 'connector' ? ['connector_id'] : ['provenance'], 'permission_denied');
+              if (browser.provenance !== undefined) {
+                try { browserUseRunProvenance(browser.provenance); } catch { check(false, 'permission_denied'); }
+              }
               const valid = browser.provider === 'browser_use'
                 ? typeof browser.browser_id === 'string' && /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/u.test(browser.browser_id)
                 : browser.provider === 'connector' && typeof browser.connector_id === 'string' && /^[a-z][a-z0-9_-]{0,63}$/u.test(browser.connector_id) &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weaccelerateinc/agent-sdk",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Server-only payment SDK, existing-browser connectors and private host adapters for agent platforms",
   "type": "module",
   "main": "./index.js",
@@ -57,6 +57,18 @@
     "./browser-use-host": {
       "types": "./browser-use-host.d.ts",
       "import": "./browser-use-host.js"
+    },
+    "./whatsapp-messaging": {
+      "types": "./whatsapp-messaging.d.ts",
+      "import": "./whatsapp-messaging.js"
+    },
+    "./whatsapp-journal": {
+      "types": "./whatsapp-journal.d.ts",
+      "import": "./whatsapp-journal.js"
+    },
+    "./postgres-whatsapp-journal": {
+      "types": "./postgres-whatsapp-journal.d.ts",
+      "import": "./postgres-whatsapp-journal.js"
     }
   },
   "files": [
@@ -91,7 +103,14 @@
     "approved-extension-releases",
     "partner-starter",
     "browser-use-host.js",
-    "browser-use-host.d.ts"
+    "browser-use-host.d.ts",
+    "whatsapp-messaging.js",
+    "whatsapp-messaging.d.ts",
+    "whatsapp-journal.js",
+    "whatsapp-journal.d.ts",
+    "browser-provenance.js",
+    "postgres-whatsapp-journal.js",
+    "postgres-whatsapp-journal.d.ts"
   ],
   "engines": {
     "node": ">=22"

package/partner-starter/README.md

@@ -1,15 +1,15 @@
 # Existing-browser payment starter
 
-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.
+SDK 0.12.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.11.0 archive, install it, then:
+Once Accelerate supplies the matching verified 0.12.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.11.0.tgz
+npm install /secure/downloads/weaccelerateinc-agent-sdk-0.12.0.tgz
 npm test
 npm run smoke
 ```
@@ -56,6 +56,6 @@ Purchase mode exposes `accelerate_checkout_submit`. Accelerate never sends the f
 
 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.
+The starter does not load `.env` automatically; export the settings or load them through your server's environment configuration. The purchase default introduced in 0.11.0 applies to newly generated `init --browser existing` projects. 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.11.0",
+    "@weaccelerateinc/agent-sdk": "0.12.0",
     "@modelcontextprotocol/server": "2.3.1"
   },
   "devDependencies": {

package/partner-starter/synthetic.mjs

@@ -225,7 +225,7 @@ export function createSyntheticDependencies({ purpose = 'sandbox_fill_only', pro
     artifact: { format: 'zip', sha256: 'a'.repeat(64), bytes: 1234 },
     bridge: { protocol: 'accelerate_extension_bridge_v1', sha256: 'b'.repeat(64) },
     capabilities: { manual_card_fill: true, document_bound_single_use: true, autosave_disabled: true, automatic_submit: false, maximum_retention_ms: 480000 },
-    compatibility: { sdk_versions: ['0.10.1', '0.10.2', '0.10.3', '0.10.4', '0.11.0'], executor_contract: 'accelerate_manual_checkout_v1' },
+    compatibility: { sdk_versions: ['0.10.1', '0.10.2', '0.10.3', '0.10.4', '0.11.0', '0.12.0'], executor_contract: 'accelerate_manual_checkout_v1' },
     qualifications: [{ provider: 'connector', scope: 'synthetic_only', evidence: 'docs/evidence/synthetic-starter.json' }],
   }; // Fake metadata for this in-process fixture only; never load it in live mode.
   const browser = { owner: context, browser: { provider: 'connector', connector_id: 'synthetic_cdp', browser_id: 'existing:browser:1', custody_mode: 'customer_backend_trusted' },

package/postgres-host.d.ts

@@ -1,4 +1,4 @@
-import type { HostPersistence } from './host-adapter.js';
+import type { HostCheckoutRecord } from './host-adapter.js';
 export const checkoutHostMigrationSql: string;
 export interface CheckoutHostPostgresClient {
   query(sql: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[]; rowCount?: number | null }>;
@@ -6,9 +6,13 @@ export interface CheckoutHostPostgresClient {
   on?(event: 'error', listener: () => void): unknown;
   removeListener?(event: 'error', listener: () => void): unknown;
 }
-export function createPostgresCheckoutPersistence(options: {
+/** Use a separate namespace for each private record type, including WhatsApp journals. */
+export function createPostgresCheckoutPersistence<Record = HostCheckoutRecord>(options: {
   pool: { connect(): Promise<CheckoutHostPostgresClient> };
   encryptionKey: Buffer | string;
   namespace?: string;
   lockTimeoutMs?: number;
-}): Readonly<HostPersistence & { initialize(): Promise<void> }>;
+}): Readonly<{
+  withLock<T>(ownerKey: string, work: (access: { load(): Promise<Record | undefined>; commit(record: Record): Promise<void> }) => Promise<T>): Promise<T>;
+  initialize(): Promise<void>;
+}>;

package/postgres-whatsapp-journal.d.ts

@@ -0,0 +1,8 @@
+import type { WhatsAppDeliveryJournal } from './whatsapp-messaging.js';
+export const whatsappJournalMigrationSql: string;
+/** Short Postgres transactions with row locks; transaction poolers are supported.
+ * initialize() executes DDL only when called by an operator. Reservations and
+ * matched evidence never expire; unmatched statuses expire after 24 hours and
+ * are capped at 64 per sender/recipient. Run pruneExpired periodically. Only
+ * hashed identifiers/status/timestamps are stored. Requires real PG qualification. */
+export function createPostgresWhatsAppDeliveryJournal(options: { pool: { query(sql: string, args?: unknown[]): Promise<{ rows: any[]; rowCount?: number | null }>; connect(): Promise<{ query(sql: string, args?: unknown[]): Promise<{ rows: any[]; rowCount?: number | null }>; release(destroy?: boolean): void }> } }): Readonly<WhatsAppDeliveryJournal & { initialize(): Promise<void>; pruneExpired(): Promise<number> }>;

package/postgres-whatsapp-journal.js

@@ -0,0 +1,95 @@
+import { AccelerateError } from './index.js';
+const HASH = /^[a-f0-9]{64}$/, MESSAGE = /^wa:[a-f0-9]{64}$/;
+const check = value => { if (!value) throw new AccelerateError('request_failed'); };
+const exact = (obj, names) => obj && typeof obj === 'object' && !Array.isArray(obj) && Object.keys(obj).length === names.length && names.every(k => Object.hasOwn(obj, k));
+const scope = s => exact(s, ['key', 'sender', 'recipient']) && HASH.test(s.key) && HASH.test(s.sender) && HASH.test(s.recipient);
+const timestamp = x => typeof x === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(x) && Number.isFinite(Date.parse(x)) && Date.parse(x) <= Date.now();
+/** Operator-only setup. Rows contain hashed IDs and timestamps only. */
+export const whatsappJournalMigrationSql = `
+CREATE TABLE IF NOT EXISTS accelerate_whatsapp_reservations (
+ sender text NOT NULL, delivery_key text NOT NULL, recipient text NOT NULL, message_id text,
+ PRIMARY KEY(sender, delivery_key), UNIQUE(sender, message_id));
+CREATE INDEX IF NOT EXISTS accelerate_whatsapp_recipient ON accelerate_whatsapp_reservations(sender, recipient, delivery_key);
+CREATE TABLE IF NOT EXISTS accelerate_whatsapp_statuses (
+ sender text NOT NULL, recipient text NOT NULL, message_id text NOT NULL, status text NOT NULL,
+ occurred_at timestamptz NOT NULL, expires_at timestamptz, conflicted boolean NOT NULL DEFAULT false,
+ PRIMARY KEY(sender,recipient,message_id,status));
+CREATE INDEX IF NOT EXISTS accelerate_whatsapp_expiry ON accelerate_whatsapp_statuses(expires_at) WHERE expires_at IS NOT NULL;`;
+/** Durable reservation rows never expire. Pre-bind event rows expire after 24h;
+ * at most 64 active unmatched events per sender+recipient are retained. */
+export function createPostgresWhatsAppDeliveryJournal({ pool } = {}) {
+  check(typeof pool?.query === 'function' && typeof pool?.connect === 'function');
+  const query = async (sql, args = []) => { try { return await pool.query(sql, args); } catch { throw new AccelerateError('request_failed'); } };
+  const transaction = async work => {
+    let client, began = false, broken = false;
+    try {
+      client = await pool.connect();
+      await client.query('BEGIN'); began = true;
+      const output = await work(client);
+      await client.query('COMMIT'); began = false;
+      return output;
+    } catch {
+      broken = true;
+      if (began) try { await client.query('ROLLBACK'); } catch {}
+      throw new AccelerateError('request_failed');
+    } finally { if (client) client.release(broken); }
+  };
+  return Object.freeze({
+    async initialize() { await query(whatsappJournalMigrationSql); },
+    async reserve(s) {
+      check(scope(s));
+      const inserted = await query('INSERT INTO accelerate_whatsapp_reservations(sender,delivery_key,recipient) VALUES($1,$2,$3) ON CONFLICT DO NOTHING RETURNING delivery_key', [s.sender,s.key,s.recipient]);
+      if (inserted.rows.length) return { created: true };
+      const found = await query('SELECT recipient FROM accelerate_whatsapp_reservations WHERE sender=$1 AND delivery_key=$2', [s.sender,s.key]);
+      check(found.rows.length === 1 && found.rows[0].recipient === s.recipient); return { created: false };
+    },
+    async bind(s) {
+      check(exact(s, ['key','sender','recipient','message_id']) && scope({ key:s.key,sender:s.sender,recipient:s.recipient }) && MESSAGE.test(s.message_id));
+      await transaction(async client => {
+        // Lock first, then issue a fresh-snapshot promotion statement. A status
+        // writer that finished while this waited is visible to the second query.
+        const found = await client.query('SELECT message_id FROM accelerate_whatsapp_reservations WHERE sender=$1 AND delivery_key=$2 AND recipient=$3 FOR UPDATE', [s.sender,s.key,s.recipient]);
+        check(found.rows.length === 1 && (found.rows[0].message_id === null || found.rows[0].message_id === s.message_id));
+        await client.query('UPDATE accelerate_whatsapp_reservations SET message_id=$4 WHERE sender=$1 AND delivery_key=$2 AND recipient=$3', [s.sender,s.key,s.recipient,s.message_id]);
+        await client.query(`UPDATE accelerate_whatsapp_statuses SET expires_at=NULL
+          WHERE sender=$1 AND recipient=$2 AND message_id=$3 AND expires_at > clock_timestamp()`, [s.sender,s.recipient,s.message_id]);
+      });
+    },
+    async recordStatus(s) {
+      check(exact(s,['sender','recipient','message_id','status','timestamp']) && HASH.test(s.sender) && HASH.test(s.recipient) && MESSAGE.test(s.message_id) && ['sent','failed'].includes(s.status) && timestamp(s.timestamp));
+      await transaction(async client => {
+        // Select the same unbound candidate for a recipient in deterministic
+        // order. Separate post-lock statements see all preceding commits.
+        const locked = await client.query(`SELECT message_id FROM accelerate_whatsapp_reservations
+          WHERE sender=$1 AND recipient=$2 AND (message_id=$3 OR message_id IS NULL)
+          ORDER BY (message_id=$3) DESC NULLS LAST,delivery_key LIMIT 1 FOR UPDATE`, [s.sender,s.recipient,s.message_id]);
+        if (!locked.rows.length) return;
+        const bound = locked.rows[0].message_id === s.message_id;
+        if (!bound) {
+          const counted = await client.query(`SELECT count(*)::int AS count,
+            COALESCE(bool_or(message_id=$3 AND status=$4),false) AS existing FROM accelerate_whatsapp_statuses
+            WHERE sender=$1 AND recipient=$2 AND expires_at > clock_timestamp()`, [s.sender,s.recipient,s.message_id,s.status]);
+          if (counted.rows[0].count >= 64 && !counted.rows[0].existing) return;
+        }
+        await client.query(`INSERT INTO accelerate_whatsapp_statuses(sender,recipient,message_id,status,occurred_at,expires_at)
+          VALUES($1,$2,$3,$4,$5::timestamptz,CASE WHEN $6::boolean THEN NULL ELSE clock_timestamp()+interval '24 hours' END)
+          ON CONFLICT(sender,recipient,message_id,status) DO UPDATE SET
+            conflicted=accelerate_whatsapp_statuses.conflicted OR accelerate_whatsapp_statuses.occurred_at<>EXCLUDED.occurred_at,
+            expires_at=CASE WHEN accelerate_whatsapp_statuses.expires_at IS NULL THEN NULL ELSE EXCLUDED.expires_at END`,
+          [s.sender,s.recipient,s.message_id,s.status,s.timestamp,bound]);
+      });
+    },
+    async get(s) {
+      check(scope(s));
+      const result = await query(`SELECT r.recipient,r.message_id,
+        EXISTS(SELECT 1 FROM accelerate_whatsapp_statuses e WHERE e.sender=r.sender AND e.recipient=r.recipient AND e.message_id=r.message_id AND (e.expires_at IS NULL OR e.expires_at>clock_timestamp()) AND (e.status='failed' OR e.conflicted)) AS failed,
+        (SELECT e.occurred_at FROM accelerate_whatsapp_statuses e WHERE e.sender=r.sender AND e.recipient=r.recipient AND e.message_id=r.message_id AND (e.expires_at IS NULL OR e.expires_at>clock_timestamp()) AND e.status='sent' AND NOT e.conflicted) AS sent_at
+        FROM accelerate_whatsapp_reservations r WHERE r.sender=$1 AND r.delivery_key=$2`, [s.sender,s.key]);
+      check(result.rows.length === 1 && result.rows[0].recipient === s.recipient);
+      const row = result.rows[0], sent = row.sent_at == null ? undefined : new Date(row.sent_at).toISOString();
+      return { sender:s.sender, recipient:s.recipient, ...(row.message_id ? { message_id:row.message_id } : {}), status:row.failed ? 'failed' : sent ? 'sent' : 'pending', ...(sent && !row.failed ? { sent_at:sent } : {}) };
+    },
+    /** Only unmatched expired events; never reservation or confirmed evidence. */
+    async pruneExpired() { const result = await query(`DELETE FROM accelerate_whatsapp_statuses e WHERE e.expires_at IS NOT NULL AND e.expires_at<=clock_timestamp() AND NOT EXISTS (SELECT 1 FROM accelerate_whatsapp_reservations r WHERE r.sender=e.sender AND r.recipient=e.recipient AND r.message_id=e.message_id)`); return result.rowCount ?? 0; },
+  });
+}

package/private-ingress.d.ts

@@ -23,6 +23,10 @@ export interface PrivateCheckoutIngress<Request = unknown> {
    * and transient parsed text. Ordinary traffic is admitted only through the
    * callback as a new minimal event, never by passing the original envelope. */
   handle(request: Request, rawBody: Uint8Array): Promise<Readonly<{ handled: boolean; retry?: true }>>;
+  /** Trusted server-only entrypoint for a provider-authenticated direct message.
+   * Never expose as a model tool. Caller must invoke before history/AI, and must
+   * retry the webhook when retry is true. Clears message.text on every outcome. */
+  handleAuthenticated(message: AuthenticatedPrivateMessage): Promise<Readonly<{ handled: boolean; retry?: true }>>;
   /** Safely recover pending lifecycle/prompt/progress deliveries only. Never
    * repeats fill or submit. Requires authenticated context from the host. */
   drain(context: ManagedCheckoutContext): Promise<number>;

package/private-ingress.js

@@ -5,6 +5,7 @@ import { deliverPrivateCheckoutReview } from './private-chat.js';
 
 const MESSAGE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/;
 const PENDING = new Set(['identity_required', 'otp_required', 'selection_required', 'cvv_required', 'approval_required', 'review_delivery_required']);
+const BEFORE_FILL = new Set(['identity_required', 'otp_required', 'selection_required', 'cvv_required']);
 const TERMINAL = new Set(['cancelled', 'expired', 'failed', 'outcome_unknown', 'submit_attempted']);
 const check = condition => { if (!condition) throw new AccelerateError('invalid_input'); };
 function digest(value) { return createHash('sha256').update(value).digest('hex'); }
@@ -75,15 +76,9 @@ export function createPrivateCheckoutIngress({ authenticate, host, privateChat,
       await saveAndDeliver(trusted, owned, response, `event-${digest(item.id)}`);
     });
   });
-  return Object.freeze({ drain,
-    async handle(request, rawBody) {
-      let verified, context, messageId;
+  async function handleAuthenticated(verified) {
+      let context, messageId;
       try {
-        check(rawBody instanceof Uint8Array);
-        verified = await authenticate(request, rawBody);
-        // Withhold the original envelope even for admitted ordinary messages.
-        // Only a new minimal event can cross the AI/history boundary below.
-        clearBody(rawBody);
         if (verified?.kind === 'ignore') return Object.freeze({ handled: true });
         check(verified?.authenticated === true && verified.direct === true);
         context = authenticatedCheckoutContext(verified.context); messageId = verified.message_id;
@@ -106,6 +101,13 @@ export function createPrivateCheckoutIngress({ authenticate, host, privateChat,
           if (isStatus) response = await privateChat.chat.get(owned.checkout_id, binding);
           else if (isCancel) response = await privateChat.chat.cancel(owned.checkout_id, binding);
           else {
+            // Private verification can fill in the same service call. Recheck
+            // after the wait while the original reply ID is durably pending.
+            // Same-ID recovery must pass this fresh check again; status and
+            // cancel remain available without inspecting the payment page.
+            if (browserConnector && (BEFORE_FILL.has(owned.previous_stage) ||
+              owned.previous_stage === 'approval_required' && owned.checkout?.approval_policy !== 'after_fill'))
+              await browserConnector.assertPaymentReady(context, { checkout_id: owned.checkout_id });
             const input = { ...binding, message_id: messageId, text: text || '[non-text reply]', ...metadata };
             try { response = await privateChat.chat.reply(owned.checkout_id, input); } finally { input.text = ''; }
           }
@@ -126,7 +128,18 @@ export function createPrivateCheckoutIngress({ authenticate, host, privateChat,
           }); } catch {}
         }
         return Object.freeze({ handled: true, retry: true });
-      } finally { clearBody(rawBody); clearReply(verified); }
+      } finally { clearReply(verified); }
+  }
+  return Object.freeze({ drain, handleAuthenticated,
+    async handle(request, rawBody) {
+      let verified;
+      try {
+        check(rawBody instanceof Uint8Array);
+        verified = await authenticate(request, rawBody);
+        clearBody(rawBody);
+        return await handleAuthenticated(verified);
+      } catch { return Object.freeze({ handled: true, retry: true }); }
+      finally { clearBody(rawBody); clearReply(verified); }
     },
   });
 }

package/starter/package.json

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

package/whatsapp-journal.d.ts

@@ -0,0 +1,11 @@
+import type { WhatsAppDeliveryJournal } from './whatsapp-messaging.js';
+/** Persistence MUST use a dedicated namespace and an exclusive sender owner
+ * lock across processes. commit must be durable before it resolves and survive
+ * later remote failures. The included Postgres persistence can be used with a
+ * separate namespace and a session-affine connection. Records contain only
+ * hashes, statuses and timestamps. Capacity limits fail closed: 1000 permanent
+ * reservations and 3000 status records per sender. Unmatched events are limited to 64 per recipient and 1000 total, and ignored when full. No automatic deletion occurs;
+ * operators must plan safe archival/reconciliation before those limits. */
+export function createWhatsAppDeliveryJournal(options: { persistence: {
+  withLock<T>(owner: string, work: (access: { load(): Promise<unknown>; commit(record: unknown): Promise<void> }) => Promise<T>): Promise<T>;
+} }): Readonly<WhatsAppDeliveryJournal>;

package/whatsapp-journal.js

@@ -0,0 +1,78 @@
+import { createHash } from 'node:crypto';
+import { AccelerateError } from './index.js';
+
+const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const HASH = /^[a-f0-9]{64}$/;
+const MESSAGE = /^wa:[a-f0-9]{64}$/;
+const time = value => typeof value === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(value) && Number.isFinite(Date.parse(value)) && Date.parse(value) <= Date.now();
+const check = value => { if (!value) throw new AccelerateError('request_failed'); };
+const exact = (value, keys) => value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === keys.length && keys.every(k => Object.hasOwn(value, k));
+const scopeOK = s => exact(s, ['key', 'sender', 'recipient']) && HASH.test(s.key) && HASH.test(s.sender) && HASH.test(s.recipient);
+const statusOK = s => exact(s, ['sender', 'recipient', 'message_id', 'status', 'timestamp']) && HASH.test(s.sender) && HASH.test(s.recipient) && MESSAGE.test(s.message_id) && ['sent', 'failed'].includes(s.status) && time(s.timestamp);
+function validate(record, sender) {
+  check(exact(record, ['version', 'sender', 'reservations', 'statuses']) && record.version === 1 && record.sender === sender && Array.isArray(record.reservations) && record.reservations.length <= 1000 && Array.isArray(record.statuses) && record.statuses.length <= 3000);
+  const reservations = new Set(), events = new Set();
+  for (const item of record.reservations) {
+    check((exact(item, ['key', 'recipient']) || exact(item, ['key', 'recipient', 'message_id'])) && HASH.test(item.key) && HASH.test(item.recipient) && (item.message_id === undefined || MESSAGE.test(item.message_id)) && !reservations.has(item.key)); reservations.add(item.key);
+  }
+  for (const item of record.statuses) {
+    check((exact(item, ['recipient', 'message_id', 'status', 'timestamp']) ||
+      exact(item, ['recipient', 'message_id', 'status', 'timestamp', 'conflicted']) && item.conflicted === true) &&
+      statusOK({ sender, recipient: item.recipient, message_id: item.message_id, status: item.status, timestamp: item.timestamp }));
+    const k = `${item.recipient}:${item.message_id}:${item.status}`; check(!events.has(k)); events.add(k);
+  }
+}
+/** Use a dedicated encrypted persistence namespace. Each sender has one SHA-256
+ * owner lock, shared by reservations and out-of-order provider status events. */
+export function createWhatsAppDeliveryJournal({ persistence } = {}) {
+  check(typeof persistence?.withLock === 'function');
+  async function locked(sender, work) {
+    check(HASH.test(sender)); let calls = 0, complete = false, expected;
+    try {
+      const result = await persistence.withLock(`accelerate-partner-host:${digest(['whatsapp-journal-v1', sender])}`, async access => {
+        check(++calls === 1 && typeof access?.load === 'function' && typeof access?.commit === 'function');
+        const record = await access.load() ?? { version: 1, sender, reservations: [], statuses: [] };
+        validate(record, sender);
+        const commit = async () => { validate(record, sender); await access.commit(structuredClone(record)); };
+        expected = await work(record, commit); complete = true; return expected;
+      });
+      check(calls === 1 && complete && result === expected); return result;
+    } catch { throw new AccelerateError('request_failed'); }
+  }
+  const find = (record, s) => { const item = record.reservations.find(row => row.key === s.key); if (item) check(item.recipient === s.recipient); return item; };
+  return Object.freeze({
+    async reserve(s) { check(scopeOK(s)); return locked(s.sender, async (record, commit) => { if (find(record, s)) return { created: false }; check(record.reservations.length < 1000); record.reservations.push({ key: s.key, recipient: s.recipient }); await commit(); return { created: true }; }); },
+    async bind(s) {
+      check(exact(s, ['key', 'sender', 'recipient', 'message_id']) && scopeOK({ key: s.key, sender: s.sender, recipient: s.recipient }) && MESSAGE.test(s.message_id));
+      return locked(s.sender, async (record, commit) => { const item = find(record, s); check(item && (!item.message_id || item.message_id === s.message_id));
+        // One provider message cannot represent multiple reservations.
+        check(!record.reservations.some(other => other !== item && other.message_id === s.message_id));
+        if (!item.message_id) { item.message_id = s.message_id; await commit(); } });
+    },
+    async recordStatus(s) { check(statusOK(s)); return locked(s.sender, async (record, commit) => {
+      // Retain an unknown ID only while a reservation for this recipient has
+      // not yet been bound. Ignore unrelated business traffic.
+      const matched = record.reservations.some(x => x.recipient === s.recipient && x.message_id === s.message_id);
+      const pending = record.reservations.some(x => x.recipient === s.recipient && !x.message_id);
+      if (!matched && !pending) return;
+      const previous = record.statuses.find(x => x.recipient === s.recipient && x.message_id === s.message_id && x.status === s.status);
+      if (previous) {
+        if (previous.timestamp !== s.timestamp) {
+          if (!previous.conflicted) { previous.conflicted = true; await commit(); }
+          check(false);
+        }
+        return;
+      }
+      // Unmatched provider traffic cannot exhaust the bounded reference journal.
+      const unmatched = record.statuses.filter(x => x.recipient === s.recipient && !record.reservations.some(r => r.recipient === x.recipient && r.message_id === x.message_id));
+      const allUnmatched = record.statuses.filter(x => !record.reservations.some(r => r.recipient === x.recipient && r.message_id === x.message_id)).length;
+      if (!matched && (unmatched.length >= 64 || allUnmatched >= 1000 || record.statuses.length >= 3000)) return;
+      check(record.statuses.length < 3000); record.statuses.push({ recipient: s.recipient, message_id: s.message_id, status: s.status, timestamp: s.timestamp }); await commit();
+    }); },
+    async get(s) { check(scopeOK(s)); return locked(s.sender, async record => {
+      const item = find(record, s); check(item); const events = record.statuses.filter(x => x.recipient === s.recipient && x.message_id === item.message_id);
+      const sent = events.find(x => x.status === 'sent'), failed = events.find(x => x.status === 'failed' || x.conflicted === true);
+      return { sender: s.sender, recipient: s.recipient, ...(item.message_id ? { message_id: item.message_id } : {}), status: failed ? 'failed' : sent ? 'sent' : 'pending', ...(sent && !failed ? { sent_at: sent.timestamp } : {}) };
+    }); },
+  });
+}

package/whatsapp-messaging.d.ts

@@ -0,0 +1,64 @@
+import type { ManagedCheckoutContext } from './managed-mcp.js';
+import type { AuthenticatedPrivateMessage, PrivateMessagingAdapter } from './private-ingress.js';
+
+type Scope = { key: string; sender: string; recipient: string };
+type Destination = { phone_number_id: string; recipient_id: string; verified_wa_id?: string };
+type Identity = { phone_number: string; wa_id: string; phone_number_id: string };
+type Resolution = ManagedCheckoutContext | { context: ManagedCheckoutContext; verified_wa_id: string } | null;
+type Status = { sender: string; recipient: string; message_id: string; status: 'sent' | 'failed'; timestamp: string };
+/** Implement with a durable, atomic, linearizable shared database. reserve must
+ * create exactly once and check the same key's sender/recipient on every call.
+ * bind must bind exactly one hashed provider ID to that reservation and reject any
+ * conflict. recordStatus retains pre-bind events only for a matching recipient
+ * with an unbound reservation and ignores unrelated statuses. Match sender,
+ * recipient and hashed message ID when binding, tolerate duplicate/out-of-order events,
+ * and fail closed on conflicting sent/failed evidence. get returns pending until
+ * an exact matched sent event; its sent_at must be the provider event timestamp.
+ * Delivered/read timestamps never substitute for sent; missing proof stays pending.
+ * Provider IDs are deterministically hashed before journaling and SDK delivery.
+ * Never store raw envelopes, image bytes, message text, OTP or CVV. Apply bounded
+ * retention to unbound status events. Unknown reservations must not be cleared
+ * or retried without independently reconciling the provider outcome. */
+export interface WhatsAppDeliveryJournal {
+  reserve(scope: Scope): Promise<{ created: boolean }>;
+  bind(input: Scope & { message_id: string }): Promise<void>;
+  recordStatus(input: Status): Promise<void>;
+  get(scope: Scope): Promise<{ sender: string; recipient: string; message_id?: string; status: 'pending' | 'sent' | 'failed'; sent_at?: string }>;
+}
+/** Provider wrapper must make one native request per call and disable retries.
+ * sendImage sends the image and caption together. Never expose provider URLs. */
+export interface WhatsAppMessagingClient {
+  uploadImage(input: { bytes: Buffer; contentType: 'image/png'; signal: AbortSignal }): Promise<{ media_id: string }>;
+  sendImage(input: { phone_number_id: string; recipient_id: string; media_id: string; caption: string; signal: AbortSignal }): Promise<{ message_id: string }>;
+  sendText(input: { phone_number_id: string; recipient_id: string; text: string; signal: AbortSignal }): Promise<{ message_id: string }>;
+}
+export function createWhatsAppMessagingAdapter(options: {
+  client: WhatsAppMessagingClient; journal: WhatsAppDeliveryJournal; sendingPhoneId: string;
+  /** Resolve from authenticated backend state only. If the provider wa_id differs
+   * from the verified phone, verified_wa_id must equal the mapped recipient_id. */
+  resolveDestination(context: Readonly<ManagedCheckoutContext>): Promise<Destination> | Destination;
+}): Readonly<PrivateMessagingAdapter & {
+  /** Read-only exact-context/key reconciliation. Never sends or uploads. */
+  findReviewReceipt(context: Readonly<ManagedCheckoutContext>, idempotencyKey: string, options?: { signal?: AbortSignal }): Promise<{ message_id: string; sent_at: string }>;
+}>;
+export function createWhatsAppWebhookAuthenticator<Request = unknown>(options: {
+  /** Verify provider signature over exact raw bytes. No callback may log those bytes. */
+  verifyWebhook(request: Request, rawBody: Uint8Array): Promise<boolean> | boolean;
+  /** Return null for unknown senders; throw only on transient resolution errors. */
+  resolveIdentity(identity: Identity): Promise<Resolution> | Resolution;
+  sendingPhoneId: string; journal: WhatsAppDeliveryJournal;
+}): (request: Request, rawBody: Uint8Array) => Promise<AuthenticatedPrivateMessage | { kind: 'ignore' }>;
+/** Verify the exact original raw bytes once, then process statuses and inbound
+ * text in provider array order. Meta's separate arrays do not encode relative
+ * ordering: statuses are recorded before messages in each change. onMessage
+ * runs transiently before any history or AI processing; it MUST durably
+ * deduplicate message_id. A thrown error or retry:true is an item failure. A failure rejects the whole
+ * webhook; provider retries can repeat earlier callbacks. No raw webhook is
+ * reserialized or retained, and rawBody is zeroed even on failure. */
+export function createWhatsAppWebhookBatchHandler<Request = unknown>(options: {
+  verifyWebhook(request: Request, rawBody: Uint8Array): Promise<boolean> | boolean;
+  /** Return null for unknown senders; throw only on transient resolution errors. */
+  resolveIdentity(identity: Identity): Promise<Resolution> | Resolution;
+  sendingPhoneId: string; journal: WhatsAppDeliveryJournal;
+  onMessage(message: AuthenticatedPrivateMessage): Promise<void | { retry?: boolean }> | void | { retry?: boolean };
+}): (request: Request, rawBody: Uint8Array) => Promise<{ handled: true }>;

package/whatsapp-messaging.js

@@ -0,0 +1,182 @@
+import { createHash } from 'node:crypto';
+import { AccelerateError } from './index.js';
+import { authenticatedCheckoutContext } from './host-adapter.js';
+
+const id = /^[A-Za-z0-9][A-Za-z0-9_.:+/=-]{0,499}$/;
+const safeId = value => `wa:${hash(value)}`;
+const digits = /^[1-9]\d{5,19}$/;
+const keyPattern = /^[A-Za-z0-9_.:-]{1,200}$/;
+const fail = () => { throw new AccelerateError('request_failed'); };
+const check = value => { if (!value) fail(); };
+const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const validTime = value => typeof value === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(value) && Number.isFinite(Date.parse(value)) && Date.parse(value) <= Date.now();
+const fromEpoch = value => {
+  check(typeof value === 'string' && /^\d{10}$/.test(value));
+  const ms = Number(value) * 1000; check(Number.isSafeInteger(ms) && ms <= Date.now());
+  return new Date(ms).toISOString();
+};
+const phoneDigits = value => { check(typeof value === 'string' && /^\+[1-9]\d{6,14}$/.test(value)); return value.slice(1); };
+function bounded(signal, deadline) {
+  const ms = deadline === undefined ? 45000 : Date.parse(deadline) - Date.now();
+  check(Number.isFinite(ms) && ms > 0);
+  return AbortSignal.any([AbortSignal.timeout(Math.min(ms, 45000)), ...(signal ? [signal] : [])]);
+}
+async function run(signal, task) {
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(new AccelerateError('request_failed'));
+    signal.addEventListener('abort', abort, { once: true });
+    Promise.resolve().then(task).then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+    if (signal.aborted) abort();
+  });
+}
+const wait = signal => run(signal, () => new Promise(resolve => setTimeout(resolve, 250)));
+function validateJournal(journal) { check(['reserve', 'bind', 'recordStatus', 'get'].every(k => typeof journal?.[k] === 'function')); }
+
+/** The injected journal MUST be durable, atomic, and linearizable across all
+ * workers. No image, caption, reply or raw provider envelope may be stored. */
+export function createWhatsAppMessagingAdapter({ client, journal, sendingPhoneId, resolveDestination } = {}) {
+  check(typeof client?.uploadImage === 'function' && typeof client?.sendImage === 'function' && typeof client?.sendText === 'function' && digits.test(sendingPhoneId) && typeof resolveDestination === 'function');
+  validateJournal(journal);
+  async function deliver(input, message, review, options = {}) {
+    let bytes;
+    try {
+      const context = authenticatedCheckoutContext(input);
+      check(message && typeof message.text === 'string' && message.text.length > 0 && message.text.length <= (review ? 1024 : 4096) && keyPattern.test(message.idempotency_key));
+      if (review) check(Buffer.isBuffer(message.bytes) && message.bytes.length > 8 && message.bytes.length <= 2 * 1024 * 1024 && message.bytes.subarray(0, 8).equals(Buffer.from([137,80,78,71,13,10,26,10])) && message.contentType === 'image/png' && message.signal instanceof AbortSignal);
+      const signal = bounded(review ? message.signal : options.signal, review ? message.delivery_expires_at : undefined);
+      const destination = await run(signal, () => resolveDestination(context));
+      check(destination && destination.phone_number_id === sendingPhoneId && (destination.recipient_id === phoneDigits(context.phone_number) || digits.test(destination.recipient_id) && destination.verified_wa_id === destination.recipient_id));
+      const scope = { key: hash([context.customer_id, context.workspace_id, context.conversation_id, message.idempotency_key]),
+        sender: hash(sendingPhoneId), recipient: hash(destination.recipient_id) };
+      const reserved = await run(signal, () => journal.reserve(scope));
+      check(reserved && typeof reserved.created === 'boolean');
+      if (reserved.created) {
+        let accepted;
+        if (review) {
+          bytes = Buffer.from(message.bytes);
+          const uploaded = await run(signal, () => client.uploadImage({ bytes, contentType: 'image/png', signal }));
+          check(typeof uploaded?.media_id === 'string' && id.test(uploaded.media_id));
+          accepted = await run(signal, () => client.sendImage({ phone_number_id: sendingPhoneId, recipient_id: destination.recipient_id, media_id: uploaded.media_id, caption: message.text, signal }));
+        } else accepted = await run(signal, () => client.sendText({ phone_number_id: sendingPhoneId, recipient_id: destination.recipient_id, text: message.text, signal }));
+        check(typeof accepted?.message_id === 'string' && id.test(accepted.message_id));
+        await run(signal, () => journal.bind({ ...scope, message_id: safeId(accepted.message_id) }));
+      }
+      for (;;) {
+        const value = await run(signal, () => journal.get(scope));
+        check(value && value.sender === scope.sender && value.recipient === scope.recipient);
+        // A reservation without an ID has an ambiguous provider outcome. Never send again.
+        check(typeof value.message_id === 'string' && id.test(value.message_id));
+        if (value.status === 'failed') fail();
+        if (value.status === 'sent') {
+          check(validTime(value.sent_at) && (!review || Date.parse(value.sent_at) < Date.parse(message.delivery_expires_at)));
+          return Object.freeze({ message_id: value.message_id, sent_at: value.sent_at });
+        }
+        check(value.status === 'pending');
+        await wait(signal);
+      }
+    } catch { throw new AccelerateError('request_failed'); }
+    finally { bytes?.fill(0); }
+  }
+  async function findReviewReceipt(input, idempotencyKey, options = {}) {
+    try {
+      const context = authenticatedCheckoutContext(input);
+      check(typeof idempotencyKey === 'string' && /^accelerate-chat:[a-f0-9]{64}$/.test(idempotencyKey));
+      const signal = bounded(options.signal);
+      const destination = await run(signal, () => resolveDestination(context));
+      check(destination && destination.phone_number_id === sendingPhoneId && (destination.recipient_id === phoneDigits(context.phone_number) || digits.test(destination.recipient_id) && destination.verified_wa_id === destination.recipient_id));
+      const scope = { key: hash([context.customer_id, context.workspace_id, context.conversation_id, idempotencyKey]), sender: hash(sendingPhoneId), recipient: hash(destination.recipient_id) };
+      const value = await run(signal, () => journal.get(scope));
+      check(value && value.sender === scope.sender && value.recipient === scope.recipient && value.status === 'sent' && typeof value.message_id === 'string' && id.test(value.message_id) && validTime(value.sent_at));
+      return Object.freeze({ message_id: value.message_id, sent_at: value.sent_at });
+    } catch { throw new AccelerateError('request_failed'); }
+  }
+  return Object.freeze({ sendText: (context, message, options) => deliver(context, message, false, options), sendReview: (context, message) => deliver(context, message, true), findReviewReceipt });
+}
+
+/** A batch handler verifies the original bytes once and invokes onMessage in
+ * provider array order. Callback processing must run before history or AI and
+ * must deduplicate provider message IDs across whole-webhook retries. */
+export function createWhatsAppWebhookBatchHandler({ verifyWebhook, resolveIdentity, sendingPhoneId, journal, onMessage } = {}) {
+  check(typeof verifyWebhook === 'function' && typeof resolveIdentity === 'function' && digits.test(sendingPhoneId) && typeof onMessage === 'function'); validateJournal(journal);
+  return async (request, rawBody) => {
+    let body;
+    try {
+      check(rawBody instanceof Uint8Array && rawBody.byteLength <= 262144 && await verifyWebhook(request, rawBody) === true);
+      body = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(rawBody));
+      check(body?.object === 'whatsapp_business_account' && Array.isArray(body.entry) && body.entry.length > 0);
+      let retry = false;
+      for (const entry of body.entry) {
+        if (!Array.isArray(entry?.changes)) { retry = true; continue; }
+        for (const change of entry.changes) {
+          if (change?.field !== 'messages') continue;
+          const value = change.value;
+          if (value?.messaging_product !== 'whatsapp' || value.metadata?.phone_number_id !== sendingPhoneId) { retry = true; continue; }
+          if ((value.statuses !== undefined && !Array.isArray(value.statuses)) || (value.messages !== undefined && !Array.isArray(value.messages))) { retry = true; continue; }
+          const statuses = value.statuses ?? [], messages = value.messages ?? [];
+          // Separate arrays have no shared provider ordering. Keep each array's order.
+          for (const status of statuses) {
+            try {
+              if (!['sent', 'failed'].includes(status?.status)) continue;
+              check(id.test(status.id) && digits.test(status.recipient_id));
+              const time = fromEpoch(status.timestamp);
+              await journal.recordStatus({ sender: hash(sendingPhoneId), recipient: hash(status.recipient_id), message_id: safeId(status.id), status: status.status, timestamp: time });
+            } catch { retry = true; }
+          }
+          for (const message of messages) {
+            let result;
+            try {
+              if (message?.type !== 'text') continue;
+              // Never treat explicitly shared/group traffic as direct.
+              if (value.group_id != null || value.is_group === true || message.group_id != null || message.groupId != null || message.group != null || message.is_group === true || message.isGroup === true || message.context?.group_id != null) continue;
+              check(message && id.test(message.id) && digits.test(message.from) && typeof message.text?.body === 'string' && message.text.body.length <= 2000);
+              const sent_at = fromEpoch(message.timestamp), phone_number = `+${message.from}`;
+              const resolved = await resolveIdentity({ phone_number, wa_id: message.from, phone_number_id: sendingPhoneId });
+              if (resolved === null) continue;
+              const mapped = resolved && Object.hasOwn(resolved, 'context') ? resolved : undefined;
+              const context = authenticatedCheckoutContext(mapped ? mapped.context : resolved);
+              check(context.phone_number === phone_number || mapped?.verified_wa_id === message.from);
+              result = { authenticated: true, direct: true, context, message_id: safeId(message.id), text: message.text.body, sent_at };
+              if (message.context?.id !== undefined) { check(id.test(message.context.id)); result.reply_to_message_id = safeId(message.context.id); }
+              const handled = await onMessage(result);
+              if (handled?.retry === true) retry = true;
+            } catch { retry = true; }
+            finally { if (result) result.text = ''; if (message?.text && typeof message.text === 'object') message.text.body = ''; }
+          }
+        }
+      }
+      check(!retry);
+      return Object.freeze({ handled: true });
+    } catch { throw new AccelerateError('permission_denied'); }
+    finally {
+      if (Array.isArray(body?.entry)) for (const entry of body.entry) if (Array.isArray(entry?.changes)) for (const change of entry.changes) if (Array.isArray(change?.value?.messages)) for (const message of change.value.messages) if (message?.text && typeof message.text === 'object') message.text.body = '';
+      if (rawBody instanceof Uint8Array) rawBody.fill(0);
+      body = undefined;
+    }
+  };
+}
+
+/** Compatibility authenticator accepts exactly one message or status event.
+ * Use the batch handler for provider endpoints that can deliver batches. */
+export function createWhatsAppWebhookAuthenticator(options = {}) {
+  return async (request, rawBody) => {
+    let message, count = 0;
+    // Batch compatibility cannot safely return multiple messages to a caller
+    // that only consumes one; reject before any journal or callback side effect.
+    let parsed;
+    try {
+      check(rawBody instanceof Uint8Array && rawBody.byteLength <= 262144 && await options.verifyWebhook(request, rawBody) === true);
+      parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(rawBody));
+      check(Array.isArray(parsed?.entry) && parsed.entry.length === 1 && Array.isArray(parsed.entry[0]?.changes) && parsed.entry[0].changes.length === 1);
+      const value = parsed.entry[0].changes[0]?.value;
+      check((value?.messages?.length ?? 0) + (value?.statuses?.length ?? 0) === 1);
+      const handler = createWhatsAppWebhookBatchHandler({ ...options, verifyWebhook: () => true, onMessage: event => { count++; message = { ...event }; } });
+      await handler(request, rawBody);
+      return count ? message : { kind: 'ignore' };
+    } catch { throw new AccelerateError('permission_denied'); }
+    finally {
+      if (Array.isArray(parsed?.entry)) for (const entry of parsed.entry) if (Array.isArray(entry?.changes)) for (const change of entry.changes) if (Array.isArray(change?.value?.messages)) for (const item of change.value.messages) if (item?.text && typeof item.text === 'object') item.text.body = '';
+      if (rawBody instanceof Uint8Array) rawBody.fill(0); parsed = undefined;
+    }
+  };
+}