@weaccelerateinc/agent-sdk 0.0.0-stage → 0.11.0

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
+# @weaccelerateinc/agent-sdk 0.11.0
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Version 0.11.0 is a breaking release: **Accelerate never sends the final payment click.** A purchase arms one short click, the customer's agent performs it once through its own browser connection (`BrowserConnectorHost.performFinalClick`) in the customer's existing browser, then Accelerate observes the outcome. Purchase requires `final_click_actor:'customer'` and that host; the managed Kernel browser is fill-only. `client.checkouts.submit` rejects locally with `customer_click_required`. See [customer-owned final click](../../docs/customer-final-click.md). Release 0.10.3 keeps its existing behavior. Merchant layouts remain limited to the qualified sandbox page; this SDK release does not by itself qualify any merchant layout, a service deployment or production payments.
+
+Server-only ESM SDK with TypeScript declarations, Node 22+, zero runtime dependencies. New partners use their existing browser and explicitly select `managed_review_v2`, which continues an armed fill immediately after private CVV verification. Existing callers keep `managed_review_v1` unless they opt in. Public npm releases use `@weaccelerateinc/agent-sdk`; install an exact available version with `npm install @weaccelerateinc/agent-sdk@0.11.0`. Check `npm view @weaccelerateinc/agent-sdk@0.11.0 version` to confirm registry availability. The package remains `UNLICENSED`.
+
+```sh
+npm install --ignore-scripts @weaccelerateinc/agent-sdk@0.11.0
+npx --no-install accelerate-agent init ./partner-demo --browser existing
+```
+
+The platform creates the browser and installs the approved extension using its existing setup. Accelerate attaches it only at payment. SDK checks fail before private collection if ownership, recording, approved runtime, lifetime, drain/fencing or qualification is unsupported. No provider replacement fallback is created.
+
+| Export | Purpose |
+| --- | --- |
+| `@weaccelerateinc/agent-sdk` | `AccelerateClient`, safe errors/status/REST checkout methods. |
+| `/partner` | `registerPartnerCheckoutTools`: composes common connector, durable host, private ingress and canonical MCP tools with existing-browser custody. |
+| `/browser-connector` | Provider-independent attachment/readiness/fence/cleanup contract, generic connector and Browser Use recipe. |
+| `/browser-use-host` | Fixed-origin bounded Browser Use v4 metadata/extension/recording/lifetime reads and stopped-resource proof, using the platform's existing document automation. No browser creation/upload. |
+| `/approved-extension` | Validate trusted release metadata, verify ZIP checksum and live runtime compatibility. |
+| `/approved-extension-releases/*` | Versioned capability/compatibility/qualification manifests. Candidate builds rejected for live use. |
+| `/host-adapter` | Durable ownership, independent effect admissions, safe outbox, native review receipts and uncertainty fences. |
+| `/postgres-host` | AES-256-GCM records with cross-process session locks; accepts your pg Pool. Explicit `initialize()` migration; no implicit database provisioning. |
+| `/private-ingress` | Authenticated sensitive interception before AI/history and safe outbox recovery. |
+| `/linq-messaging` | Linq/iMessage native private image+text/receipt transport and webhook authenticator using your actual signature verifier. |
+| `/private-chat` | Private state/reply/review APIs and bounded `deliverPrivateCheckoutReview`; never register as model tools. |
+| `/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/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/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 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.
+
+## Bounded status waiting
+
+```js
+const selected = await accelerate.checkouts.waitFor(id, {
+  statuses: ['selection_ready'],
+  timeoutMs: 120_000,
+}, { signal });
+if (selected.status !== 'selection_ready') {
+  // Handle the actual state; do not advance a payment automatically.
+  return;
+}
+```
+
+`waitFor` uses sequential GET requests only. Defaults: 60-second overall timeout and one-second interval. Maximum overall timeout: five minutes; interval range: 250–5000ms. It returns immediately for any requested state, `ready_for_submit` or any terminal state, even if not requested. It aborts hung requests within the overall deadline, rejects as `wait_timeout`, and never retries errors. Readiness must not be hidden behind a long polling loop.
+
+## Browser preparation and tool schemas
+
+Supported operations: `browser_snapshot`, `browser_text`, `browser_find`, `browser_wait_for`, `browser_act`, `navigate`.
+
+```js
+import { browserOperationJsonSchema } from '@weaccelerateinc/agent-sdk/browser-operations';
+// Use this framework-neutral schema as the browser-operation tool input schema.
+
+const snapshot = await accelerate.checkouts.browser(id, {
+  operation: 'browser_snapshot',
+  arguments: { filter: 'interactive', depth: 5 },
+});
+await accelerate.checkouts.browser(id, {
+  operation: 'browser_act',
+  arguments: {
+    steps: [{ type: 'click', ref: 'e1_1' }], // current snapshot reference
+    successor: { filter: 'all', depth: 5 },
+  },
+});
+await accelerate.checkouts.browser(id, {
+  operation: 'browser_wait_for',
+  arguments: { expect: { type: 'url', contains: '/payment' }, timeout_ms: 8000 },
+});
+```
+
+Wait conditions follow their `type`: text waits require nonempty `text`; URL/title waits require nonempty `equals` or `contains`. Do not use `text` for a URL/title condition, or URL comparators for text. `exists: false` negates the match. If both URL/title comparators are provided, `equals` takes precedence. Malformed conditions are rejected locally before an HTTP request; a valid condition that fails to appear still stops the checkout under the existing browser failure policy.
+
+The JSON schema and input normalizer share operation bounds and discriminated shapes. For framework values typed as unknown, `parseBrowserOperation(value)` returns a validated, normalized `BrowserOperation` without a TypeScript assertion. The normalizer and server remain the security authority. References have shape `eN_N`; newer snapshots replace them. Actions: click, hover, scroll_to, fill, type, key and bounded wait. Batches allow at most eight steps and action waits at most eight seconds. Arbitrary scripts, selectors in actions, screenshots, tabs, payment controls and final purchase clicks are excluded. Responses contain bounded text without browser control URLs or raw input values.
+
+## Verify a quote before private approval
+
+After `applyDetails`, inspect the current amount using the original total selector and ask the backend to verify its currency. `expected_currency` is an expectation to check, not evidence supplied by the agent; a dollar symbol alone does not establish USD.
+
+```js
+const verified = await accelerate.checkouts.verifyQuote(id, {
+  revision: details.revision,
+  checkout_url: exactCheckoutUrl,
+  expected_amount_cents: 1299,
+  expected_currency: 'USD',
+  checkout_total_selector: originalTotalSelector,
+});
+```
+
+The bounded receipt contains only `checkout_id`, the unchanged `revision`, `verified:true` and `{checkout_origin,amount_cents,currency}` in `quote`. It requires the current selected-address details, exact checkout URL (including query and fragment) and authoritative backend currency proof. It does not arm filling, request CVV or approve a purchase. Use its verified amount and currency in the existing `requestApproval` flow, which independently inspects the original quote again. A rejected inspection is a blocker, not permission to infer currency or repeat uncertain payment work.
+
+For `sandbox_fill_only`, retain the actual visible original payment continuation as `submit_selector`, such as Review Your Order, even when disabled. Filling never clicks it. Purchase purpose retains its final-submit readiness and separate private approval requirements.
+
+## Inspect a failed creation without replay
+
+`checkouts.inspectCreation({customer_id,workspace_id,conversation_id,idempotency_key,browser})` is a server-only read. Derive scope, the original key and exact Browser Use binding from authenticated ownership and the application's permanent reservation; never expose these fields as model input.
+
+The service looks up only that tenant/key and requires the exact owner, private conversation and browser, a failed revision-zero creation before authentication, no operation lock or private effects, and independent stopped-provider/closed-lease proof. A positive receipt contains `confirmed:true`, the opaque checkout ID, revision zero, immutable purpose, the key's SHA-256 and strict retirement booleans. Missing or incomplete proof returns only `confirmed:false`. Inspection never creates, replays, verifies, fills, cancels, recovers a lock or writes checkout state. Keep the old browser permanently reserved. A separately authorized fresh request still needs a new ordinary browser and normal fresh-start checks.
+
+## Private chat helpers
+
+```js
+import {
+  AcceleratePrivateChatClient,
+  renderPrivateChatState,
+  privateChatProgress,
+} from '@weaccelerateinc/agent-sdk/private-chat';
+```
+
+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/blob/main/products/agent-sdk/examples/private-chat-ingress.js).
+
+## Safe results and recovery
+
+Ordinary status includes only opaque checkout ID, state, revision, expiry, purpose/policy, optional masked wallet and quote metadata. It contains no PAN, expiry, CVV, wallet auth capability, source ID or unrestricted browser access.
+
+Current and compatible earlier clients opt ordinary requests into `X-Accelerate-Diagnostics: v1`. When the service supports it, safe checkout `diagnostics` includes fixed `stage`, `next_actions`, opaque `support_reference`, `cleanup_status` and the exact `submit_deadline` at readiness. Cleanup `confirmed` means worker acknowledgement, not independently verified provider destruction. `AccelerateError.supportReference` correlates negotiated errors without exposing upstream text. Older ordinary response bodies are unchanged without opt-in; private-chat and hosted bodies retain their existing contract. Current clients accept older service responses without diagnostics, but the supported review profile still requires its policy echo and actual full-window proof. A compatible status response is not a profile-readiness preflight.
+
+Every request accepts `{signal}` last. Bounds including server/cleanup headroom: create 245s; fill 235s; details/verifyQuote/approval/submit 125s; browser 85s; inspectCreation 60s; status/cancel/connection 45s. These are transport bounds, not provider-destruction guarantees.
+
+No request automatically retries. `AccelerateError` provides fixed `code`, `status`, `message`, `nextAction`, `retrySafe:false`, `paymentConfirmed:false`; upstream bodies and credential-bearing diagnostics are excluded. `nextAction` is guidance only:
+
+| Value | Backend action |
+| --- | --- |
+| `check_configuration` | Check provisioned key, merchant and service configuration |
+| `check_request` | Correct local request shape |
+| `complete_wallet` / `complete_verification` | Continue the existing private shopper flow |
+| `refresh_quote` / `refresh_revision` | Inspect safe state and prepare a new valid quote/revision if allowed |
+| `check_status` | Read the existing checkout; do not repeat payment effects |
+| `reconcile_order` | Check the merchant independently before any replacement purchase |
+| `stop` | Stop and investigate |
+
+An uncertain fill/submit outcome must be reconciled; do not automatically replay or create a replacement purchase. `submit_attempted` and `outcome_unknown` never confirm an order. The SDK does not certify PCI scope or source correctness.
+
+## Development
+
+```sh
+npm test --workspace @weaccelerateinc/agent-sdk
+```
+
+Tests use synthetic data and local HTTP; they do not collect live credentials or make purchases.

package/approved-extension-releases/0.0.0.1.json

@@ -0,0 +1,41 @@
+{
+  "schema_version": 1,
+  "release_id": "accelerate-extension-0.0.0.1",
+  "status": "approved",
+  "extension_version": "0.0.0.1",
+  "artifact": {
+    "format": "zip",
+    "sha256": "65574cbb27ab344687963f72a136f2653551b57458b284e486946b27699099c8",
+    "bytes": 29397270
+  },
+  "bridge": {
+    "protocol": "accelerate_extension_bridge_v1",
+    "sha256": "1ba039eb78a5b18bfab4486c7835f1ac188b96682ec67c92bfef889c763811a6",
+    "runtime_reporting": "legacy_pinned_artifact"
+  },
+  "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.0",
+      "0.10.1",
+      "0.10.2",
+      "0.10.3",
+      "0.10.4",
+      "0.11.0"
+    ],
+    "executor_contract": "accelerate_manual_checkout_v1"
+  },
+  "qualifications": [
+    {
+      "provider": "browser_use",
+      "scope": "sandbox_demo_normal_fill_review_cancel",
+      "evidence": "docs/evidence/browser-use-wallet-fill-review-2026-10-27.json"
+    }
+  ]
+}

package/approved-extension-releases/0.0.0.2.json

@@ -0,0 +1,34 @@
+{
+  "schema_version": 1,
+  "release_id": "accelerate-extension-0.0.0.2",
+  "status": "candidate_pending_browser_qualification",
+  "extension_version": "0.0.0.2",
+  "artifact": {
+    "format": "zip",
+    "sha256": "7a7a4ab8a874f7b8e2387433534ca0c6e78df3c4465f2e4d7f7d56a128951839",
+    "bytes": 29397375
+  },
+  "bridge": {
+    "protocol": "accelerate_extension_bridge_v1",
+    "sha256": "e86412da654acaca1ed108b624a112c6c5439d9d0a0f1beb90a59c86b68ed40b"
+  },
+  "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.0",
+      "0.10.1",
+      "0.10.2",
+      "0.10.3",
+      "0.10.4",
+      "0.11.0"
+    ],
+    "executor_contract": "accelerate_manual_checkout_v1"
+  },
+  "qualifications": []
+}

package/approved-extension.d.ts

@@ -0,0 +1,24 @@
+export interface ApprovedExtensionRelease {
+  schema_version: 1;
+  release_id: `accelerate-extension-${string}`;
+  status: 'approved' | 'candidate_pending_browser_qualification';
+  extension_version: string;
+  artifact: { format: 'zip'; sha256: string; bytes: number };
+  bridge: { protocol: 'accelerate_extension_bridge_v1'; sha256: string; runtime_reporting?: 'protocol_and_version' | 'legacy_pinned_artifact' };
+  capabilities: { manual_card_fill: true; document_bound_single_use: true; autosave_disabled: true; automatic_submit: false; maximum_retention_ms: 480000 };
+  compatibility: { sdk_versions: string[]; executor_contract: 'accelerate_manual_checkout_v1' };
+  qualifications: Array<{ provider: string; scope: string; evidence: string }>;
+}
+export interface ApprovedExtensionRuntime {
+  extension_version: string;
+  artifact_sha256: string;
+  success: true; initialized: true; wasmInitialized: true; autosaveDisabled: true;
+  boundedRetentionSupported: true; maximumRetentionMs: 480000;
+  bridge_protocol?: 'accelerate_extension_bridge_v1';
+}
+export class ApprovedExtensionError extends Error { readonly code: string; }
+export function validateApprovedExtensionRelease(input: unknown, options?: { allowCandidate?: boolean }): Readonly<ApprovedExtensionRelease>;
+export function verifyApprovedExtensionArtifact(bytes: Uint8Array, release: ApprovedExtensionRelease): Readonly<{ verified: true; extension_version: string; artifact_sha256: string }>;
+export function verifyApprovedExtensionRuntime(runtime: ApprovedExtensionRuntime, release: ApprovedExtensionRelease, options: {
+  sdkVersion?: string; executorContract?: 'accelerate_manual_checkout_v1'; provider: string;
+}): Readonly<{ verified: true; extension_version: string; artifact_sha256: string; bridge_protocol: 'accelerate_extension_bridge_v1'; provider: string }>;

package/approved-extension.js

@@ -0,0 +1,90 @@
+import { createHash } from 'node:crypto';
+
+const SDK_VERSION = '0.11.0';
+const EXECUTOR_CONTRACT = 'accelerate_manual_checkout_v1';
+const BRIDGE_PROTOCOL = 'accelerate_extension_bridge_v1';
+const LEGACY_SHA256 = '65574cbb27ab344687963f72a136f2653551b57458b284e486946b27699099c8';
+const hashPattern = /^[a-f0-9]{64}(?![\s\S])/;
+const versionPattern = /^(?:0|[1-9]\d{0,4})(?:\.(?:0|[1-9]\d{0,4})){0,3}(?![\s\S])/;
+const identifier = /^[a-z][a-z0-9_-]{0,79}(?![\s\S])/;
+const reject = code => { throw new ApprovedExtensionError(code); };
+const check = (condition, code = 'invalid_extension_release') => { if (!condition) reject(code); };
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value) &&
+  [Object.prototype, null].includes(Object.getPrototypeOf(value));
+function keys(value, required, optional = []) {
+  check(object(value));
+  check(required.every(key => Object.hasOwn(value, key)) &&
+    Object.keys(value).every(key => required.includes(key) || optional.includes(key)));
+}
+const version = value => typeof value === 'string' && versionPattern.test(value) &&
+  value.split('.').every(part => Number(part) <= 65535) && value.split('.').some(part => Number(part) > 0);
+const freeze = value => {
+  if (value && typeof value === 'object') { Object.values(value).forEach(freeze); Object.freeze(value); }
+  return value;
+};
+
+export class ApprovedExtensionError extends Error {
+  constructor(code) { super('The Accelerate extension could not be verified.'); this.name = 'ApprovedExtensionError'; this.code = code; }
+}
+
+/** Validate operator-supplied metadata. Metadata must come from trusted backend
+ * configuration; this validates a contract and is not a publisher signature. */
+export function validateApprovedExtensionRelease(input, { allowCandidate = false } = {}) {
+  check(typeof allowCandidate === 'boolean');
+  keys(input, ['schema_version', 'release_id', 'status', 'extension_version', 'artifact', 'bridge', 'capabilities', 'compatibility', 'qualifications']);
+  check(input.schema_version === 1 && version(input.extension_version) && input.release_id === `accelerate-extension-${input.extension_version}`);
+  check(['approved', 'candidate_pending_browser_qualification'].includes(input.status));
+  check(input.status === 'approved' || allowCandidate, 'extension_release_not_approved');
+  keys(input.artifact, ['format', 'sha256', 'bytes']);
+  check(input.artifact.format === 'zip' && typeof input.artifact.sha256 === 'string' && hashPattern.test(input.artifact.sha256) &&
+    Number.isSafeInteger(input.artifact.bytes) && input.artifact.bytes > 0 && input.artifact.bytes <= 100 * 1024 * 1024);
+  keys(input.bridge, ['protocol', 'sha256'], ['runtime_reporting']);
+  check(input.bridge.protocol === BRIDGE_PROTOCOL && typeof input.bridge.sha256 === 'string' && hashPattern.test(input.bridge.sha256));
+  const reporting = input.bridge.runtime_reporting ?? 'protocol_and_version';
+  check(['protocol_and_version', 'legacy_pinned_artifact'].includes(reporting));
+  if (reporting === 'legacy_pinned_artifact') check(input.extension_version === '0.0.0.1' && input.artifact.sha256 === LEGACY_SHA256);
+  keys(input.capabilities, ['manual_card_fill', 'document_bound_single_use', 'autosave_disabled', 'automatic_submit', 'maximum_retention_ms']);
+  check(input.capabilities.manual_card_fill === true && input.capabilities.document_bound_single_use === true &&
+    input.capabilities.autosave_disabled === true && input.capabilities.automatic_submit === false && input.capabilities.maximum_retention_ms === 480000);
+  keys(input.compatibility, ['sdk_versions', 'executor_contract']);
+  check(Array.isArray(input.compatibility.sdk_versions) && input.compatibility.sdk_versions.length > 0 && input.compatibility.sdk_versions.length <= 20 &&
+    input.compatibility.sdk_versions.every(item => typeof item === 'string' && /^\d+\.\d+\.\d+(?![\s\S])/.test(item)) &&
+    new Set(input.compatibility.sdk_versions).size === input.compatibility.sdk_versions.length && input.compatibility.executor_contract === EXECUTOR_CONTRACT);
+  check(Array.isArray(input.qualifications) && input.qualifications.length <= 32);
+  for (const qualification of input.qualifications) {
+    keys(qualification, ['provider', 'scope', 'evidence']);
+    check(typeof qualification.provider === 'string' && identifier.test(qualification.provider) &&
+      typeof qualification.scope === 'string' && identifier.test(qualification.scope) &&
+      typeof qualification.evidence === 'string' && /^docs\/evidence\/[a-z0-9][a-z0-9._-]{0,150}\.json(?![\s\S])/.test(qualification.evidence));
+  }
+  check(input.status !== 'approved' || input.qualifications.length > 0, 'extension_qualification_missing');
+  return freeze(structuredClone(input));
+}
+
+/** Verify local ZIP bytes before a platform installs them. No upload occurs. */
+export function verifyApprovedExtensionArtifact(bytes, release) {
+  const approved = validateApprovedExtensionRelease(release);
+  check(bytes instanceof Uint8Array && bytes.byteLength === approved.artifact.bytes, 'extension_artifact_mismatch');
+  const actual = createHash('sha256').update(bytes).digest('hex');
+  check(actual === approved.artifact.sha256, 'extension_artifact_mismatch');
+  return freeze({ verified: true, extension_version: approved.extension_version, artifact_sha256: actual });
+}
+
+/** Verify private connector observations. The artifact pin must be derived from
+ * trusted installation records, not a field supplied by an agent/model. */
+export function verifyApprovedExtensionRuntime(runtime, release, {
+  sdkVersion = SDK_VERSION, executorContract = EXECUTOR_CONTRACT, provider,
+} = {}) {
+  const approved = validateApprovedExtensionRelease(release);
+  check(approved.compatibility.sdk_versions.includes(sdkVersion) && executorContract === approved.compatibility.executor_contract, 'extension_compatibility_mismatch');
+  check(typeof provider === 'string' && identifier.test(provider) && approved.qualifications.some(item => item.provider === provider), 'extension_provider_unqualified');
+  keys(runtime, ['extension_version', 'artifact_sha256', 'success', 'initialized', 'wasmInitialized', 'autosaveDisabled', 'boundedRetentionSupported', 'maximumRetentionMs'], ['bridge_protocol']);
+  check(runtime.extension_version === approved.extension_version && runtime.artifact_sha256 === approved.artifact.sha256, 'extension_runtime_mismatch');
+  check(runtime.success === true && runtime.initialized === true && runtime.wasmInitialized === true && runtime.autosaveDisabled === true &&
+    runtime.boundedRetentionSupported === true && runtime.maximumRetentionMs === approved.capabilities.maximum_retention_ms, 'extension_runtime_not_ready');
+  if (approved.bridge.runtime_reporting === 'legacy_pinned_artifact') {
+    check(runtime.bridge_protocol === undefined || runtime.bridge_protocol === BRIDGE_PROTOCOL, 'extension_runtime_mismatch');
+  } else check(runtime.bridge_protocol === BRIDGE_PROTOCOL, 'extension_runtime_mismatch');
+  return freeze({ verified: true, extension_version: approved.extension_version, artifact_sha256: approved.artifact.sha256,
+    bridge_protocol: BRIDGE_PROTOCOL, provider });
+}

package/browser-connector.d.ts

@@ -0,0 +1,109 @@
+import type { CheckoutId, CustomerBrowserBinding, RequestOptions } from './index.js';
+import type { ManagedCheckoutContext } from './managed-mcp.js';
+import type { ApprovedExtensionRelease, ApprovedExtensionRuntime } from './approved-extension.js';
+
+/** Private, authenticated host projection. Never put this record in MCP arguments/results. */
+export interface OwnedBrowserDocument {
+  owner: ManagedCheckoutContext;
+  browser: CustomerBrowserBinding;
+  document_id: string;
+  checkout_url: string;
+  expires_at: string;
+}
+export interface FencedBrowserDocument extends OwnedBrowserDocument {
+  fence_id: string;
+}
+export interface BrowserReadiness extends OwnedBrowserDocument {
+  recording_disabled: true;
+  /** Actual runtime receipt plus the independently pinned installed ZIP checksum. */
+  extension: ApprovedExtensionRuntime;
+  automation: {
+    ordinary_operations_drained: boolean;
+    agent_access_fenced: boolean;
+    fence_id: string | null;
+  };
+}
+/** Durable fencing is a host responsibility; acquiring a JavaScript mutex is insufficient. */
+export interface BrowserConnectorHost {
+  resolveOwnedBrowser(context: Readonly<ManagedCheckoutContext>, request: Readonly<{
+    attempt_key: string; checkout_url: string;
+  }>, options: RequestOptions): Promise<OwnedBrowserDocument>;
+  inspectBrowser(context: Readonly<ManagedCheckoutContext>, browser: Readonly<OwnedBrowserDocument>, options: RequestOptions): Promise<BrowserReadiness>;
+  /** Persist the fence, reject new ordinary work and await all in-flight automation before resolving. */
+  drainAndFence(context: Readonly<ManagedCheckoutContext>, browser: Readonly<OwnedBrowserDocument>, request: Readonly<{
+    attempt_key: string;
+  }>, options: RequestOptions): Promise<{
+    fence_id: string; ordinary_operations_drained: true; agent_access_fenced: true;
+  }>;
+  /** Persist exact attempt/browser/document/fence binding. A lost ACK must retain its uncertainty fence. */
+  bindCheckout(context: Readonly<ManagedCheckoutContext>, request: Readonly<FencedBrowserDocument & {
+    checkout_id: CheckoutId; attempt_key: string;
+  }>, options: RequestOptions): Promise<void>;
+  resolveCheckoutBrowser(context: Readonly<ManagedCheckoutContext>, request: Readonly<{ checkout_id: CheckoutId }>, options: RequestOptions): Promise<FencedBrowserDocument>;
+  /** Verify cleanup independently after Accelerate reports closure. Never release an uncertain-payment fence. */
+  confirmCleanup(context: Readonly<ManagedCheckoutContext>, browser: Readonly<FencedBrowserDocument>, request: Readonly<{
+    checkout_id: CheckoutId;
+  }>, 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>;
+  readonly [attachmentBrand]: true;
+}
+export interface BrowserConnector {
+  readonly contract: 'accelerate_existing_browser_v1';
+  readonly provider: 'browser_use' | 'connector';
+  readonly connector_id?: string;
+  prepareAttachment(context: Readonly<ManagedCheckoutContext>, request: Readonly<{
+    attempt_key: string; checkout_url: string;
+  }>, options?: RequestOptions): Promise<PreparedBrowserAttachment>;
+  commitAttachment(context: Readonly<ManagedCheckoutContext>, request: Readonly<{
+    checkout_id: CheckoutId; attachment: PreparedBrowserAttachment;
+  }>, options?: RequestOptions): Promise<void>;
+  /** Fresh check before private OTP dispatch and before quote/CVV dispatch. */
+  assertPaymentReady(context: Readonly<ManagedCheckoutContext>, request: Readonly<{
+    checkout_id: CheckoutId; checkout_url?: string;
+  }>, options?: RequestOptions): Promise<void>;
+  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. */
+  connectorId: string;
+  extensionRelease: ApprovedExtensionRelease;
+  host: BrowserConnectorHost;
+  /** Can only increase the required ten-minute headroom, never shorten approval. */
+  minimumRemainingMs?: number;
+  /** Test clock only. */
+  now?: () => number;
+}
+/** Generic registered-executor connector. Does not create/upload/replace a browser or provision a provider. */
+export function createExistingBrowserConnector(options: ExistingBrowserConnectorOptions): BrowserConnector;
+/** First provider recipe. Uses Browser Use IDs through the same host contract; no API key is accepted. */
+export function createBrowserUseConnector(options: Omit<ExistingBrowserConnectorOptions, 'connectorId'>): BrowserConnector;