@weaccelerateinc/agent-sdk 0.0.0-stage → 0.11.0

package/browser-connector.js

@@ -0,0 +1,218 @@
+import { AccelerateError } from './index.js';
+import { normalizeBrowserOperation } from './browser-operations.js';
+import { validateApprovedExtensionRelease, verifyApprovedExtensionRuntime } from './approved-extension.js';
+
+const OWNER = /^[A-Za-z0-9_.:-]{1,500}$/u;
+const ID = /^mcs_[A-Za-z0-9_-]{43}$/u;
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/u;
+const CONNECTOR = /^[a-z][a-z0-9_-]{0,63}$/u;
+const OPAQUE = /^[A-Za-z0-9_.:-]{1,200}$/u;
+const CONTEXT = ['customer_id', 'workspace_id', 'conversation_id', 'phone_number'];
+const DOC = ['owner', 'browser', 'document_id', 'checkout_url', 'expires_at'];
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value) &&
+  [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const check = (ok, code = 'configuration_invalid') => { if (!ok) throw new AccelerateError(code); };
+function shape(value, required, optional = [], code) {
+  check(object(value) && required.every(key => Object.hasOwn(value, key)) &&
+    Object.keys(value).every(key => required.includes(key) || optional.includes(key)), code);
+}
+function freeze(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.values(value).forEach(freeze); Object.freeze(value);
+  }
+  return value;
+}
+function owner(value) {
+  shape(value, CONTEXT, [], 'permission_denied');
+  check(CONTEXT.slice(0, 3).every(key => typeof value[key] === 'string' && OWNER.test(value[key])) &&
+    typeof value.phone_number === 'string' && /^\+[1-9]\d{6,14}$/u.test(value.phone_number), 'permission_denied');
+  return freeze(Object.fromEntries(CONTEXT.map(key => [key, value[key]])));
+}
+const sameOwner = (a, b) => CONTEXT.every(key => a[key] === b[key]);
+function url(value) {
+  try { normalizeBrowserOperation('navigate', { url: value }); }
+  catch { throw new AccelerateError('invalid_input'); }
+  return value;
+}
+function options(value = {}) {
+  shape(value, [], ['signal']); check(value.signal === undefined || value.signal instanceof AbortSignal);
+  check(!value.signal?.aborted, 'request_cancelled');
+  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');
+  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 };
+}
+function record(value, context, config, { fenced = false, readiness = false, checkoutUrl } = {}) {
+  shape(value, DOC, [...(fenced ? ['fence_id'] : []), ...(readiness ? ['recording_disabled', 'extension', 'automation'] : [])], 'permission_denied');
+  const identity = owner(value.owner);
+  check(sameOwner(identity, context) && typeof value.document_id === 'string' && OPAQUE.test(value.document_id), 'permission_denied');
+  const binding = browser(value.browser, config.provider, config.connectorId);
+  const checkout = url(value.checkout_url);
+  check(!checkoutUrl || checkout === checkoutUrl, 'permission_denied');
+  check(typeof value.expires_at === 'string' && /^\d{4}-\d{2}-\d{2}T[\d:.]+Z$/u.test(value.expires_at) &&
+    Number.isFinite(Date.parse(value.expires_at)), 'integration_unavailable');
+  const result = { owner: identity, browser: binding, document_id: value.document_id,
+    checkout_url: checkout, expires_at: value.expires_at };
+  if (fenced) {
+    check(typeof value.fence_id === 'string' && OPAQUE.test(value.fence_id), 'permission_denied');
+    result.fence_id = value.fence_id;
+  }
+  return freeze(result);
+}
+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]) &&
+    actual.expires_at === expected.expires_at, 'permission_denied');
+}
+function makeConnector(configuration, provider) {
+  shape(configuration, ['extensionRelease', 'host'], ['connectorId', 'minimumRemainingMs', 'now']);
+  const { connectorId, extensionRelease, host, minimumRemainingMs = 600000, now = Date.now } = configuration;
+  check(provider === 'browser_use' ? connectorId === undefined : typeof connectorId === 'string' && CONNECTOR.test(connectorId));
+  check(host && ['resolveOwnedBrowser', 'inspectBrowser', 'drainAndFence', 'bindCheckout', 'resolveCheckoutBrowser', 'confirmCleanup']
+    .every(key => typeof host[key] === 'function') && Number.isSafeInteger(minimumRemainingMs) &&
+    minimumRemainingMs >= 600000 && minimumRemainingMs <= 3600000 && typeof now === 'function');
+  let release;
+  try { release = validateApprovedExtensionRelease(extensionRelease); }
+  catch { throw new AccelerateError('configuration_invalid'); }
+  check(release.status === 'approved');
+  const config = { provider, connectorId };
+  const attachments = new WeakMap();
+  const hostCall = async (method, ...args) => {
+    try { return await host[method](...args); }
+    catch (error) {
+      // A provider transport error can contain connection URLs or credentials.
+      // Preserve only the SDK's fixed, allowlisted error projection.
+      throw error instanceof AccelerateError ? new AccelerateError(error.code, error.status, error.supportReference)
+        : new AccelerateError('integration_unavailable');
+    }
+  };
+  const checkpoint = opts => check(!opts.signal?.aborted, 'request_cancelled');
+  const inspect = async (context, expected, opts, fenceId, minimum = minimumRemainingMs) => {
+    checkpoint(opts);
+    const value = await hostCall('inspectBrowser', context, expected, opts);
+    checkpoint(opts);
+    const actual = record(value, context, config, { readiness: true });
+    sameDocument(actual, expected);
+    const current = now();
+    check(Number.isFinite(current) && Date.parse(actual.expires_at) - current >= minimum &&
+      value.recording_disabled === true, 'integration_unavailable');
+    check(object(value.extension) && value.extension.artifact_sha256 === release.artifact.sha256, 'integration_unavailable');
+    try { verifyApprovedExtensionRuntime(value.extension, release, { executorContract: 'accelerate_manual_checkout_v1', provider }); }
+    catch { throw new AccelerateError('integration_unavailable'); }
+    shape(value.automation, ['ordinary_operations_drained', 'agent_access_fenced', 'fence_id'], [], 'integration_unavailable');
+    check(typeof value.automation.ordinary_operations_drained === 'boolean' && typeof value.automation.agent_access_fenced === 'boolean' &&
+      (value.automation.fence_id === null || typeof value.automation.fence_id === 'string' && OPAQUE.test(value.automation.fence_id)), 'integration_unavailable');
+    if (fenceId) check(value.automation.ordinary_operations_drained === true && value.automation.agent_access_fenced === true &&
+      value.automation.fence_id === fenceId, 'operation_conflict');
+  };
+  const resolve = async (context, checkoutId, opts) => {
+    check(typeof checkoutId === 'string' && ID.test(checkoutId), 'invalid_input');
+    const resolved = await hostCall('resolveCheckoutBrowser', context, freeze({ checkout_id: checkoutId }), opts);
+    checkpoint(opts);
+    return record(resolved, context, config, { fenced: true });
+  };
+  const stamp = value => {
+    check(typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T[\d:.]+Z$/u.test(value) && Number.isFinite(Date.parse(value)), 'invalid_input');
+    return Date.parse(value);
+  };
+  const preparations = new WeakMap();
+  const canClick = typeof host.performFinalClick === 'function';
+  // Slow work (ownership lookup, provider read, runtime inspection) happens here, BEFORE the short arm exists,
+  // so none of it consumes the click window. The fence is never lifted. One preparation serves one click.
+  const prepareClick = canClick ? async (contextValue, input, requestOptions) => {
+    const context = owner(contextValue), opts = options(requestOptions);
+    shape(input, ['checkout_id'], [], 'invalid_input');
+    const expected = await resolve(context, input.checkout_id, opts);
+    // Fenced, drained runtime check; the ten-minute attachment headroom does not apply after the review window.
+    await inspect(context, expected, opts, expected.fence_id, 1);
+    const preparation = Object.freeze({});
+    preparations.set(preparation, { context, checkout_id: input.checkout_id, record: expected, at: now(), used: false });
+    return preparation;
+  } : undefined;
+  const finalClick = canClick ? async (contextValue, input, requestOptions) => {
+    const context = owner(contextValue), opts = options(requestOptions);
+    shape(input, ['checkout_id', 'preparation', 'checkout_url', 'submit_selector', 'armed_expires_at'], [], 'invalid_input');
+    const saved = preparations.get(input.preparation);
+    check(saved && !saved.used && sameOwner(saved.context, context) && saved.checkout_id === input.checkout_id, 'permission_denied');
+    saved.used = true;
+    check(typeof input.submit_selector === 'string' && input.submit_selector.length > 0 && input.submit_selector.length <= 200 &&
+      !/[\u0000-\u001f\u007f]/u.test(input.submit_selector), 'invalid_input');
+    const armedUntil = stamp(input.armed_expires_at), started = now();
+    // The service arm lives at most 15 seconds (never accepted longer); refuse an expired or implausibly long window.
+    check(Number.isFinite(started) && armedUntil > started && armedUntil - started <= 15000 && started - saved.at <= 60000, 'submit_unavailable');
+    // Cheap checks only inside the arm window: exact URL, browser outlives the arm, then the customer's physical click.
+    check(url(input.checkout_url) === saved.record.checkout_url && Date.parse(saved.record.expires_at) > armedUntil, 'permission_denied');
+    checkpoint(opts);
+    const result = await hostCall('performFinalClick', context, freeze({ checkout_id: input.checkout_id,
+      submit_selector: input.submit_selector, armed_expires_at: input.armed_expires_at, ...saved.record }), opts);
+    shape(result, ['dispatched'], [], 'integration_unavailable');
+    check(typeof result.dispatched === 'boolean', 'integration_unavailable');
+    return Object.freeze({ dispatched: result.dispatched });
+  } : undefined;
+  // Every method belongs to the server integration. A connector never creates a
+  // replacement browser, releases its durable fence or retries a payment call.
+  return Object.freeze({ contract: 'accelerate_existing_browser_v1', provider,
+    ...(connectorId ? { connector_id: connectorId } : {}),
+    async prepareAttachment(contextValue, input, requestOptions) {
+      const context = owner(contextValue), opts = options(requestOptions);
+      shape(input, ['attempt_key', 'checkout_url'], [], 'invalid_input');
+      check(typeof input.attempt_key === 'string' && input.attempt_key.length > 0 && input.attempt_key.length <= 200 &&
+        !/[\u0000-\u001f\u007f]/u.test(input.attempt_key), 'invalid_input');
+      const request = freeze({ attempt_key: input.attempt_key, checkout_url: url(input.checkout_url) });
+      const resolved = await hostCall('resolveOwnedBrowser', context, request, opts);
+      checkpoint(opts);
+      const expected = record(resolved, context, config, { checkoutUrl: request.checkout_url });
+      // Capabilities are checked BEFORE taking the fence or collecting OTP/CVV.
+      await inspect(context, expected, opts);
+      const ack = await hostCall('drainAndFence', context, expected, freeze({ attempt_key: request.attempt_key }), opts);
+      checkpoint(opts);
+      shape(ack, ['fence_id', 'ordinary_operations_drained', 'agent_access_fenced'], [], 'integration_unavailable');
+      check(typeof ack.fence_id === 'string' && OPAQUE.test(ack.fence_id) && ack.ordinary_operations_drained === true &&
+        ack.agent_access_fenced === true, 'operation_conflict');
+      await inspect(context, expected, opts, ack.fence_id);
+      const browser_resource = typeof host.clientBrowserResource === 'function'
+        ? await hostCall('clientBrowserResource', context, expected, opts) : undefined;
+      checkpoint(opts);
+      const attachment = Object.freeze({ browser: expected.browser, ...(browser_resource ? { browser_resource } : {}) });
+      attachments.set(attachment, { context, attempt_key: request.attempt_key, record: freeze({ ...expected, fence_id: ack.fence_id }) });
+      return attachment;
+    },
+    async commitAttachment(contextValue, input, requestOptions) {
+      const context = owner(contextValue), opts = options(requestOptions);
+      shape(input, ['checkout_id', 'attachment'], [], 'invalid_input');
+      const saved = attachments.get(input.attachment);
+      check(saved && sameOwner(saved.context, context) && typeof input.checkout_id === 'string' && ID.test(input.checkout_id), 'permission_denied');
+      check(!saved.checkout_id || saved.checkout_id === input.checkout_id, 'operation_conflict');
+      // Bind before awaiting transport so concurrent/lost-ACK recovery cannot
+      // assign this attachment to a different checkout.
+      saved.checkout_id = input.checkout_id;
+      await hostCall('bindCheckout', context, freeze({ ...saved.record, checkout_id: input.checkout_id, attempt_key: saved.attempt_key }), opts);
+      checkpoint(opts);
+      // Keep the capability for an idempotent same-checkout ACK recovery only.
+    },
+    async assertPaymentReady(contextValue, input, requestOptions) {
+      const context = owner(contextValue), opts = options(requestOptions);
+      shape(input, ['checkout_id'], ['checkout_url'], 'invalid_input');
+      const expected = await resolve(context, input.checkout_id, opts);
+      if (input.checkout_url !== undefined) check(url(input.checkout_url) === expected.checkout_url, 'permission_denied');
+      await inspect(context, expected, opts, expected.fence_id);
+    },
+    ...(finalClick ? { prepareFinalClick: prepareClick, performFinalClick: finalClick } : {}),
+    async confirmCleanup(contextValue, input, requestOptions) {
+      const context = owner(contextValue), opts = options(requestOptions);
+      shape(input, ['checkout_id'], [], 'invalid_input');
+      const expected = await resolve(context, input.checkout_id, opts);
+      const ack = await hostCall('confirmCleanup', context, expected, freeze({ checkout_id: input.checkout_id }), opts);
+      checkpoint(opts);
+      shape(ack, ['provider_browser_stopped', 'credentials_cleared', 'fence_retained'], [], 'integration_unavailable');
+      check(Object.values(ack).every(value => value === true), 'integration_unavailable');
+    },
+  });
+}
+
+export function createExistingBrowserConnector(options) { return makeConnector(options ?? {}, 'connector'); }
+export function createBrowserUseConnector(options) { return makeConnector(options ?? {}, 'browser_use'); }

package/browser-operations.d.ts

@@ -0,0 +1,56 @@
+export type BrowserStep =
+  | { type: 'click'; ref: string; button?: 'left'; num_clicks?: 1; modifiers?: [] }
+  | { type: 'hover' | 'scroll_to'; ref: string }
+  | { type: 'fill'; ref: string; value: string }
+  | { type: 'type'; text: string; repeat?: number }
+  | { type: 'key'; text: 'Enter' | 'Tab' | 'Escape' | 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' |
+      'Backspace' | 'Delete' | 'Space'; repeat?: number }
+  | { type: 'wait'; ms?: number };
+export type BrowserCondition =
+  | { type: 'text'; text: string; exists?: boolean }
+  | ({ type: 'url' | 'title'; exists?: boolean } &
+    ({ equals: string; contains?: string } | { equals?: string; contains: string }));
+export type BrowserOperation =
+  | { operation: 'browser_snapshot'; arguments: { filter?: 'all' | 'interactive'; ref?: 'root'; depth?: number } }
+  | { operation: 'browser_text'; arguments: Record<string, never> }
+  | { operation: 'browser_find'; arguments: { query: string } }
+  | { operation: 'browser_wait_for'; arguments: { expect: BrowserCondition; timeout_ms?: number; poll_ms?: number } }
+  | { operation: 'browser_act'; arguments: { steps: BrowserStep[]; timeout_ms?: number; successor?: { filter?: 'all' | 'interactive'; depth?: number } } }
+  | { operation: 'navigate'; arguments: { url: string } };
+export interface BrowserResult { content: Array<{ type: 'text'; text: string }> }
+
+/** Dependency-free JSON Schema vocabulary used by the published browser grammar. */
+export interface BrowserOperationJsonSchema {
+  [keyword: string]: unknown;
+  $schema?: 'https://json-schema.org/draft/2020-12/schema';
+  type?: 'object' | 'array' | 'string' | 'integer' | 'boolean';
+  description?: string;
+  properties?: Record<string, BrowserOperationJsonSchema>;
+  required?: string[];
+  additionalProperties?: boolean;
+  oneOf?: BrowserOperationJsonSchema[];
+  items?: BrowserOperationJsonSchema;
+  const?: string | number;
+  enum?: string[];
+  pattern?: string;
+  format?: string;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  minItems?: number;
+  maxItems?: number;
+}
+
+/** Frozen model-visible grammar. normalizeBrowserOperation remains required for semantic safety. */
+export const browserOperationJsonSchema: Readonly<BrowserOperationJsonSchema & {
+  type: 'object'; oneOf: BrowserOperationJsonSchema[];
+}>;
+
+/** Strictly parses unknown JSON input through the same runtime semantic normalizer. */
+export function parseBrowserOperation(value: unknown): BrowserOperation;
+
+/** Throws a fixed error on unsupported or credential-bearing preparation input. */
+export function normalizeBrowserOperation<T extends BrowserOperation['operation']>(
+  operation: T, args: Extract<BrowserOperation, { operation: T }>['arguments']
+): Extract<BrowserOperation, { operation: T }>['arguments'];

package/browser-operations.js

@@ -0,0 +1,144 @@
+// One wire grammar shared by the customer SDK and Accelerate's upstream adapter.
+// It contains no transport, tenant credentials or provider capabilities.
+const sensitive = /(?:\d[ -]?){13,19}|\b(?:0[1-9]|1[0-2])\s*\/\s*(?:20)?\d{2}\b|\b(?:cvv|cvc|csc|security\s*code)\b["'\s:=]{0,12}\d{3,4}\b|\b(?:Bearer\s|eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.|aw[12]\.|agw_[A-Za-z0-9_-]{43}|atk_(?:test|live)_|tok_(?:sandbox|live)_|vgs_)|\b(?:cdp_ws_url|browser_live_view_url|devtoolsFrontendUrl|webSocketDebuggerUrl|kernel_session_id|playwright_endpoint)\b|(?:wss?|chrome-extension|devtools):\/\/|https?:\/\/[^\s/]*(?:onkernel\.com|verygoodproxy\.com|verygoodvault\.com)(?:[/:\s]|$)/i;
+const limits = { timeout: [1, 8000], poll: [10, 1000], depth: [1, 15], repeat: [1, 3], wait: [1, 1000],
+  steps: [1, 8], ref: 60, text: 2000, query: 1000, url: 2048 };
+const filters = ['all', 'interactive'];
+const keys = ['Enter', 'Tab', 'Escape', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Backspace', 'Delete', 'Space'];
+const refPattern = /^e\d+_\d+$/u;
+const integerSchema = ([minimum, maximum]) => ({ type: 'integer', minimum, maximum });
+const textSchema = (maxLength, minLength = 0) => ({ type: 'string', minLength, maxLength, pattern: '^[^\\u0000-\\u001f\\u007f]*$' });
+const objectSchema = (properties, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
+const snapshotSchema = (successor = false) => objectSchema({ filter: { type: 'string', enum: filters },
+  ...(!successor ? { ref: { type: 'string', const: 'root' } } : {}), depth: integerSchema(limits.depth) });
+const conditionSchema = { oneOf: [
+  objectSchema({ type: { const: 'text' }, text: textSchema(limits.query, 1), exists: { type: 'boolean' } }, ['type', 'text']),
+  objectSchema({ type: { type: 'string', enum: ['url', 'title'] }, equals: textSchema(limits.url, 1),
+    contains: textSchema(limits.query, 1), exists: { type: 'boolean' } }, ['type', 'equals']),
+  objectSchema({ type: { type: 'string', enum: ['url', 'title'] }, contains: textSchema(limits.query, 1),
+    exists: { type: 'boolean' } }, ['type', 'contains']),
+] };
+const refSchema = { type: 'string', pattern: refPattern.source, maxLength: limits.ref,
+  description: 'Copy a bare ref from the latest result. Every browser result replaces earlier refs.' };
+const stepSchema = { oneOf: [
+  objectSchema({ type: { const: 'click' }, ref: refSchema, button: { const: 'left' }, num_clicks: { const: 1 },
+    modifiers: { type: 'array', maxItems: 0 } }, ['type', 'ref']),
+  objectSchema({ type: { type: 'string', enum: ['hover', 'scroll_to'] }, ref: refSchema }, ['type', 'ref']),
+  objectSchema({ type: { const: 'fill' }, ref: refSchema, value: { ...textSchema(limits.text),
+    description: 'Non-sensitive shopping/contact text only. Never enter card data or credentials.' } }, ['type', 'ref', 'value']),
+  objectSchema({ type: { const: 'type' }, text: textSchema(limits.text), repeat: integerSchema(limits.repeat) }, ['type', 'text']),
+  objectSchema({ type: { const: 'key' }, text: { type: 'string', enum: keys }, repeat: integerSchema(limits.repeat) }, ['type', 'text']),
+  objectSchema({ type: { const: 'wait' }, ms: integerSchema(limits.wait) }, ['type']),
+] };
+const operationSchema = (operation, args) => objectSchema({ operation: { type: 'string', const: operation }, arguments: args }, ['operation', 'arguments']);
+const freezeSchema = value => {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) freezeSchema(child);
+    Object.freeze(value);
+  }
+  return value;
+};
+
+/** Model-visible structural grammar. Always run normalizeBrowserOperation too;
+ * credential detection, URL safety and private checkout permissions remain runtime checks. */
+export const browserOperationJsonSchema = freezeSchema({ $schema: 'https://json-schema.org/draft/2020-12/schema', type: 'object',
+  description: 'Restricted checkout preparation only. No scripts, screenshots, card entry or final submission.',
+  oneOf: [
+    operationSchema('browser_snapshot', snapshotSchema()),
+    operationSchema('browser_text', objectSchema({})),
+    operationSchema('browser_find', objectSchema({ query: textSchema(limits.query, 1) }, ['query'])),
+    operationSchema('browser_wait_for', objectSchema({ expect: conditionSchema,
+      timeout_ms: integerSchema(limits.timeout), poll_ms: integerSchema(limits.poll) }, ['expect'])),
+    operationSchema('browser_act', objectSchema({ steps: { type: 'array', items: stepSchema,
+      minItems: limits.steps[0], maxItems: limits.steps[1] }, timeout_ms: integerSchema(limits.timeout), successor: snapshotSchema(true) }, ['steps'])),
+    operationSchema('navigate', objectSchema({ url: { ...textSchema(limits.url, 1), format: 'uri',
+      description: 'Actual intended public HTTPS merchant URL; never use navigation to retry uncertain payment work.' } }, ['url'])),
+  ] });
+const check = value => { if (!value) throw new Error('invalid_browser_operation'); };
+function shape(value, required, optional = []) {
+  check(value !== null && typeof value === 'object' && !Array.isArray(value) &&
+    [Object.prototype, null].includes(Object.getPrototypeOf(value)) &&
+    required.every(field => Object.hasOwn(value, field)) &&
+    Object.keys(value).every(field => required.includes(field) || optional.includes(field)));
+}
+function text(value, max, nonempty = false) {
+  check(typeof value === 'string' && value.length <= max && (!nonempty || value.length > 0) &&
+    !/[\u0000-\u001f\u007f]/u.test(value) && !sensitive.test(value));
+}
+const optionalInteger = (value, min, max) => check(value === undefined || Number.isInteger(value) && value >= min && value <= max);
+function snapshot(args, successor = false) {
+  shape(args, [], successor ? ['filter', 'depth'] : ['filter', 'ref', 'depth']);
+  check(args.filter === undefined || filters.includes(args.filter));
+  check(args.ref === undefined || args.ref === 'root'); optionalInteger(args.depth, ...limits.depth);
+}
+function checkoutUrl(value) {
+  text(value, limits.url, true); check(!/\s/u.test(value));
+  const url = new URL(value);
+  // A checkout fragment selects merchant payment state; retain the exact URL.
+  check(url.protocol === 'https:' && !url.username && !url.password && !url.port &&
+    value.match(/^https:\/\/([^/?#]+)/)?.[1] === url.hostname &&
+    /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/u.test(url.hostname) &&
+    !/(?:^|\.)(?:localhost|local|internal|lan|corp|home|home\.arpa)$/u.test(url.hostname));
+}
+
+/** Validate the restricted preparation operation and return new JSON-only arguments.
+ * Harmless Browser Loop click defaults are stripped before reaching the gateway.
+ * Unsupported fields fail locally, preserving the active browser's usability.
+ */
+export function normalizeBrowserOperation(operation, args) {
+  try {
+    if (operation === 'navigate') { shape(args, ['url']); checkoutUrl(args.url); }
+    else if (operation === 'browser_text') shape(args, []);
+    else if (operation === 'browser_find') { shape(args, ['query']); text(args.query, limits.query, true); }
+    else if (operation === 'browser_snapshot') snapshot(args);
+    else if (operation === 'browser_wait_for') {
+      shape(args, ['expect'], ['timeout_ms', 'poll_ms']);
+      if (args.expect?.type === 'text') {
+        shape(args.expect, ['type', 'text'], ['exists']);
+        text(args.expect.text, limits.query, true);
+      } else {
+        shape(args.expect, ['type'], ['equals', 'contains', 'exists']);
+        check(['url', 'title'].includes(args.expect.type));
+        check(args.expect.equals !== undefined || args.expect.contains !== undefined);
+        for (const name of ['equals', 'contains']) if (args.expect[name] !== undefined) text(args.expect[name], name === 'equals' ? limits.url : limits.query, true);
+      }
+      check(args.expect.exists === undefined || typeof args.expect.exists === 'boolean');
+      optionalInteger(args.timeout_ms, ...limits.timeout); optionalInteger(args.poll_ms, ...limits.poll);
+    } else if (operation === 'browser_act') {
+      shape(args, ['steps'], ['timeout_ms', 'successor']);
+      check(Array.isArray(args.steps) && args.steps.length >= limits.steps[0] && args.steps.length <= limits.steps[1]);
+      optionalInteger(args.timeout_ms, ...limits.timeout);
+      if (args.successor !== undefined) snapshot(args.successor, true);
+      const steps = args.steps.map(step => {
+        if (step?.type === 'click') {
+          shape(step, ['type', 'ref'], ['button', 'num_clicks', 'modifiers']);
+          check(step.button === undefined || step.button === 'left');
+          check(step.num_clicks === undefined || step.num_clicks === 1);
+          check(step.modifiers === undefined || Array.isArray(step.modifiers) && step.modifiers.length === 0);
+        } else if (['hover', 'scroll_to', 'fill'].includes(step?.type)) {
+          shape(step, step.type === 'fill' ? ['type', 'ref', 'value'] : ['type', 'ref']);
+        } else if (['type', 'key'].includes(step?.type)) {
+          shape(step, ['type', 'text'], ['repeat']); text(step.text, limits.text);
+          optionalInteger(step.repeat, ...limits.repeat);
+          if (step.type === 'key') check(keys.includes(step.text));
+          return step;
+        } else {
+          shape(step, ['type'], ['ms']); check(step.type === 'wait'); optionalInteger(step.ms, ...limits.wait); return step;
+        }
+        check(typeof step.ref === 'string' && step.ref.length <= limits.ref && refPattern.test(step.ref));
+        if (step.type === 'fill') text(step.value, limits.text);
+        return step.type === 'click' ? { type: 'click', ref: step.ref } : step;
+      });
+      args = { ...args, steps };
+    } else check(false);
+    return JSON.parse(JSON.stringify(args));
+  } catch { throw new Error('invalid_browser_operation'); }
+}
+
+/** Parse an unknown framework input without requiring an unsafe TypeScript assertion. */
+export function parseBrowserOperation(value) {
+  try {
+    shape(value, ['operation', 'arguments']);
+    return { operation: value.operation, arguments: normalizeBrowserOperation(value.operation, value.arguments) };
+  } catch { throw new Error('invalid_browser_operation'); }
+}

package/browser-use-host.d.ts

@@ -0,0 +1,46 @@
+import type { ManagedCheckoutContext } from './managed-mcp.js';
+import type { RequestOptions } from './index.js';
+import type { ApprovedExtensionRelease, ApprovedExtensionRuntime } from './approved-extension.js';
+import type { BrowserConnectorHost, OwnedBrowserDocument, FencedBrowserDocument, BrowserReadiness } from './browser-connector.js';
+
+/** Existing platform automation backend observes only the bound document and
+ * fixed extension health, never card values. It retains private CDP credentials. */
+export interface BrowserUseDocumentObservation {
+  document_id: string;
+  checkout_url: string;
+  extension: Omit<ApprovedExtensionRuntime, 'artifact_sha256'>;
+  automation: BrowserReadiness['automation'];
+}
+export interface BrowserUsePlatformHost {
+  /** Resolve an EXISTING browser from authenticated durable ownership. SDK reads actual provider expiry. */
+  resolveOwnedBrowser(context: Readonly<ManagedCheckoutContext>, request: Readonly<{ attempt_key: string; checkout_url: string }>,
+    options: RequestOptions): Promise<Omit<OwnedBrowserDocument, 'expires_at'> & { expires_at?: string }>;
+  drainAndFence: BrowserConnectorHost['drainAndFence'];
+  bindCheckout: BrowserConnectorHost['bindCheckout'];
+  resolveCheckoutBrowser: BrowserConnectorHost['resolveCheckoutBrowser'];
+  /** Use existing server browser control. Wake only the pinned MV3 registration
+   * if suspended. Do not create/navigate a page or accept model-authored code. */
+  inspectDocument(context: Readonly<ManagedCheckoutContext>, browser: Readonly<OwnedBrowserDocument>,
+    runtime: Readonly<{ runtime_id: string }>, options: RequestOptions): Promise<BrowserUseDocumentObservation>;
+  /** Optional; required for purchase. One trusted pointer click on the unique bound selector in the exact fenced document,
+   * through your existing server browser control. No retry, no general DOM reads, never lift the fence. */
+  performFinalClick?: BrowserConnectorHost['performFinalClick'];
+  /** Independently verify extension/page cleanup and retain every payment uncertainty fence. */
+  confirmLocalCleanup(context: Readonly<ManagedCheckoutContext>, browser: Readonly<FencedBrowserDocument>,
+    request: Readonly<{ checkout_id: import('./index.js').CheckoutId }>, options: RequestOptions): Promise<{
+      credentials_cleared: true; fence_retained: true;
+    }>;
+}
+/** Packaged Browser Use Cloud v4 read-only provider adapter. API key stays in
+ * the authenticated backend. No create, extension upload, navigation or stop is
+ * performed; Accelerate's executor/reaper owns payment retirement. */
+export function createBrowserUseHost(options: {
+  apiKey: string;
+  merchantId: string;
+  extensionId: string;
+  extensionRelease: ApprovedExtensionRelease;
+  host: BrowserUsePlatformHost;
+  fetchImpl?: typeof fetch;
+  /** Test clock only. */
+  now?: () => number;
+}): Readonly<BrowserConnectorHost>;

package/browser-use-host.js

@@ -0,0 +1,149 @@
+import { AccelerateError } from './index.js';
+import { validateApprovedExtensionRelease, verifyApprovedExtensionRuntime } from './approved-extension.js';
+import { normalizeBrowserOperation } from './browser-operations.js';
+
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/u;
+const RUNTIME = /^[a-p]{32}$/u;
+const BASE = 'https://api.browser-use.com/api/v4';
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value) &&
+  [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const check = (ok, code = 'integration_unavailable') => { if (!ok) throw new AccelerateError(code); };
+function exact(value, required, optional = []) {
+  check(object(value) && required.every(key => Object.hasOwn(value, key)) &&
+    Object.keys(value).every(key => required.includes(key) || optional.includes(key)));
+}
+function bounded(work, signal) {
+  return new Promise((resolve, reject) => {
+    const abort = () => { signal.removeEventListener('abort', abort); reject(new AccelerateError('integration_unavailable')); };
+    signal.addEventListener('abort', abort, { once: true });
+    if (signal.aborted) { abort(); return; }
+    Promise.resolve(work).then(value => { signal.removeEventListener('abort', abort); resolve(value); }, abort);
+  });
+}
+async function json(response, signal) {
+  const reader = response.body.getReader(), chunks = []; let length = 0;
+  const cancel = () => { void reader.cancel().catch(() => {}); };
+  signal.addEventListener('abort', cancel, { once: true });
+  try {
+    for (;;) {
+      check(!signal.aborted);
+      const { value, done } = await bounded(reader.read(), signal);
+      check(!signal.aborted);
+      if (done) break;
+      length += value.byteLength; check(length <= 262144); chunks.push(value);
+    }
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+  } finally {
+    signal.removeEventListener('abort', cancel); cancel();
+    try { reader.releaseLock(); } catch {}
+  }
+}
+const freeze = value => {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) { Object.values(value).forEach(freeze); Object.freeze(value); }
+  return 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;
+  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');
+  let release;
+  try { release = validateApprovedExtensionRelease(configuration.extensionRelease); }
+  catch { throw new AccelerateError('configuration_invalid'); }
+  check(release.qualifications.some(value => value.provider === 'browser_use'), 'configuration_invalid');
+  const callHost = async (method, ...args) => {
+    try { return await host[method](...args); }
+    catch { throw new AccelerateError('integration_unavailable'); }
+  };
+  const owned = (context, document) => {
+    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']);
+    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 };
+  };
+  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}`;
+    let response;
+    try {
+      check(!signal.aborted);
+      const pending = Promise.resolve(fetchImpl(endpoint, { method: 'GET', headers: {
+        'X-Browser-Use-API-Key': apiKey, Accept: 'application/json',
+      }, cache: 'no-store', redirect: 'error', signal }));
+      void pending.then(value => { if (signal.aborted) void value.body?.cancel().catch(() => {}); }, () => {});
+      response = await bounded(pending, signal);
+      check(response.ok && !response.redirected && (!response.url || response.url === endpoint) &&
+        /^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);
+      const metadata = value?.metadata;
+      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 &&
+        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 &&
+        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 ?? ''));
+      // Deliberately project away provider CDP/viewer URLs and unknown response fields.
+      const read = freeze({ expires_at: value.timeoutAt, runtime_id: value.extensions[0].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 }) });
+    } catch {
+      void response?.body?.cancel().catch(() => {});
+      throw new AccelerateError(options.signal?.aborted ? 'request_cancelled' : 'integration_unavailable');
+    }
+  };
+  return Object.freeze({
+    async resolveOwnedBrowser(context, request, options) {
+      const document = await callHost('resolveOwnedBrowser', context, request, options);
+      const observed = await resource(context, document, 'active', options);
+      return { ...owned(context, document), expires_at: observed.expires_at };
+    },
+    /** This browser's connection for Accelerate, read here so the provider key stays with the host. */
+    async clientBrowserResource(context, document, options) {
+      return (await resource(context, document, 'active', { ...options, withConnection: true })).connection;
+    },
+    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.extension, ['extension_version', 'success', 'initialized', 'wasmInitialized', 'autosaveDisabled',
+        'boundedRetentionSupported', 'maximumRetentionMs'], ['bridge_protocol']);
+      const extension = { ...current.extension, artifact_sha256: release.artifact.sha256 };
+      try { verifyApprovedExtensionRuntime(extension, release, { provider: 'browser_use' }); }
+      catch { throw new AccelerateError('integration_unavailable'); }
+      return { ...owned(context, document), document_id: current.document_id, checkout_url: current.checkout_url, expires_at: observed.expires_at,
+        recording_disabled: true, extension,
+        automation: current.automation };
+    },
+    // Optional: only a platform host that can click may enable purchases. Readiness was read by prepareFinalClick before the arm.
+    ...(typeof host.performFinalClick === 'function' ? { performFinalClick: (...args) => callHost('performFinalClick', ...args) } : {}),
+    drainAndFence: (...args) => callHost('drainAndFence', ...args),
+    bindCheckout: (...args) => callHost('bindCheckout', ...args),
+    resolveCheckoutBrowser: (...args) => callHost('resolveCheckoutBrowser', ...args),
+    async confirmCleanup(context, document, request, options) {
+      // A service closure or stop response is insufficient: GET the exact
+      // original provider resource before accepting the local cleanup proof.
+      await resource(context, document, 'stopped', options);
+      const receipt = await callHost('confirmLocalCleanup', context, document, request, options);
+      exact(receipt, ['credentials_cleared', 'fence_retained']);
+      check(receipt.credentials_cleared === true && receipt.fence_retained === true);
+      return { provider_browser_stopped: true, credentials_cleared: true, fence_retained: true };
+    },
+  });
+}