@weaccelerateinc/agent-sdk 0.0.0-stage → 0.10.3

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,43 @@
+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>;
+  /** 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,147 @@
+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 };
+    },
+    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 };
+    },
+  });
+}

package/checkout-diagnostics.d.ts

@@ -0,0 +1,23 @@
+export type CheckoutDiagnosticStage = 'not_started' | 'identity_required' | 'otp_required' | 'selection_required' |
+  'preparing_checkout' | 'approval_required' | 'cvv_required' | 'approved' | 'ready_for_submit' | 'review_delivery_required' | 'review_delivered' | 'approved_for_submit' |
+  'cancelled' | 'expired' | 'failed' | 'submit_attempted' | 'outcome_unknown';
+export type CheckoutDiagnosticAction = 'get_status' | 'continue_private_chat' | 'prepare_checkout' | 'apply_details' |
+  'request_approval' | 'fill' | 'submit' | 'cancel' | 'reconcile_order';
+export type CheckoutCleanupStatus = 'not_required' | 'not_started' | 'pending' | 'confirmed';
+export interface CheckoutDiagnostics {
+  version: 'v1';
+  stage: CheckoutDiagnosticStage;
+  /** Guidance only. Server authorization, revision, private consent and one-use checks remain mandatory. */
+  next_actions: CheckoutDiagnosticAction[];
+  support_reference: `acs_${string}`;
+  /** not_required means no retained browser reference. confirmed means worker closure acknowledgement; neither is independent provider proof. */
+  cleanup_status: CheckoutCleanupStatus;
+  submit_deadline?: string;
+}
+export const checkoutDiagnosticStages: readonly CheckoutDiagnosticStage[];
+export const checkoutDiagnosticActions: readonly CheckoutDiagnosticAction[];
+export const checkoutCleanupStatuses: readonly CheckoutCleanupStatus[];
+export const checkoutDiagnosticsJsonSchema: Readonly<Record<string, unknown>>;
+export function validateCheckoutDiagnostics(value: unknown, checkout?: {
+  status: string; purpose?: string; submit_allowed?: boolean; submit_expires_at?: string; approval_policy?: string; purchase_approved?: boolean;
+}): CheckoutDiagnostics;

package/checkout-diagnostics.js

@@ -0,0 +1,67 @@
+// Safe lifecycle metadata only. No transport, credentials, provider text or automatic actions.
+export const checkoutDiagnosticStages = Object.freeze(['not_started', 'identity_required', 'otp_required', 'selection_required',
+    'preparing_checkout', 'approval_required', 'cvv_required', 'approved', 'ready_for_submit', 'review_delivery_required', 'review_delivered', 'approved_for_submit',
+    'cancelled', 'expired', 'failed', 'submit_attempted', 'outcome_unknown']);
+export const checkoutDiagnosticActions = Object.freeze(['get_status', 'continue_private_chat', 'prepare_checkout', 'apply_details',
+    'request_approval', 'fill', 'submit', 'cancel', 'reconcile_order']);
+export const checkoutCleanupStatuses = Object.freeze(['not_required', 'not_started', 'pending', 'confirmed']);
+const freeze = (value) => { if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    for (const item of Object.values(value))
+        freeze(item);
+    Object.freeze(value);
+} return value; };
+export const checkoutDiagnosticsJsonSchema = freeze({ type: 'object', additionalProperties: false,
+    required: ['version', 'stage', 'next_actions', 'support_reference', 'cleanup_status'], properties: {
+        version: { const: 'v1' }, stage: { type: 'string', enum: checkoutDiagnosticStages },
+        next_actions: { type: 'array', minItems: 1, maxItems: checkoutDiagnosticActions.length, uniqueItems: true,
+            items: { type: 'string', enum: checkoutDiagnosticActions } },
+        support_reference: { type: 'string', pattern: '^acs_[a-f0-9]{32}$' },
+        cleanup_status: { type: 'string', enum: checkoutCleanupStatuses }, submit_deadline: { type: 'string', format: 'date-time' },
+    } });
+const terminal = new Set(['cancelled', 'expired', 'failed', 'submit_attempted', 'outcome_unknown']);
+const timestamp = (value) => typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T[\d:.]+Z$/.test(value) && Number.isFinite(Date.parse(value));
+const check = (value) => { if (!value) {
+    const error = Object.assign(Error('Invalid Accelerate checkout diagnostics.'), { code: 'invalid_response' });
+    throw error;
+} };
+/** Validate fixed metadata; optional checkout binding prevents contradictory action guidance. Never authorizes an action. */
+export function validateCheckoutDiagnostics(input, checkout) {
+    // Validation below checks every property before returning this value.
+    const value = input;
+    check(value !== null && typeof value === 'object' && !Array.isArray(value) &&
+        [Object.prototype, null].includes(Object.getPrototypeOf(value)) &&
+        Object.keys(value).every(key => Object.hasOwn(checkoutDiagnosticsJsonSchema.properties, key)) &&
+        checkoutDiagnosticsJsonSchema.required.every(key => Object.hasOwn(value, key)) && value.version === 'v1' &&
+        checkoutDiagnosticStages.includes(value.stage) && Array.isArray(value.next_actions) && value.next_actions.length >= 1 &&
+        value.next_actions.length <= checkoutDiagnosticActions.length && new Set(value.next_actions).size === value.next_actions.length &&
+        value.next_actions.every(action => checkoutDiagnosticActions.includes(action)) &&
+        typeof value.support_reference === 'string' && /^acs_[a-f0-9]{32}$/.test(value.support_reference) &&
+        checkoutCleanupStatuses.includes(value.cleanup_status) && (value.submit_deadline === undefined || timestamp(value.submit_deadline)));
+    if (checkout !== undefined) {
+        const { status, purpose = 'purchase', submit_allowed, approval_policy, purchase_approved } = checkout;
+        check(terminal.has(status) ? value.stage === status : status === 'wallet_required'
+            ? ['not_started', 'identity_required', 'otp_required', 'selection_required'].includes(value.stage)
+            : ['selection_ready', 'details_ready'].includes(status) ? value.stage === 'preparing_checkout'
+                : status === 'approval_required' ? ['approval_required', 'cvv_required'].includes(value.stage) : approval_policy === 'after_fill' && status === 'ready_for_submit' ? ['review_delivery_required', 'review_delivered', 'approval_required', 'approved_for_submit'].includes(value.stage) : value.stage === status);
+        check(status === 'ready_for_submit' ? timestamp(value.submit_deadline) && value.submit_deadline === checkout.submit_expires_at : value.submit_deadline === undefined);
+        for (const action of value.next_actions) {
+            if (action === 'submit')
+                check(status === 'ready_for_submit' && purpose === 'purchase' && submit_allowed !== false && (approval_policy !== 'after_fill' || purchase_approved === true));
+            if (action === 'fill')
+                check(status === 'approved' && purpose !== 'sandbox_source_comparison');
+            if (['prepare_checkout', 'apply_details'].includes(action))
+                check(['selection_ready', 'details_ready'].includes(status));
+            if (action === 'request_approval')
+                check(status === 'details_ready');
+            if (action === 'continue_private_chat')
+                check(['wallet_required', 'approval_required'].includes(status) || approval_policy === 'after_fill' && status === 'ready_for_submit' && !purchase_approved);
+            if (action === 'reconcile_order')
+                check(['submit_attempted', 'outcome_unknown'].includes(status));
+        }
+        if (!terminal.has(status))
+            check(value.cleanup_status !== 'pending' && value.cleanup_status !== 'confirmed');
+        if (terminal.has(status))
+            check(value.cleanup_status !== 'not_started');
+    }
+    return value;
+}

package/cli.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { AccelerateClient, AccelerateError } from './index.js';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir, realpath, readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const help = `Usage: accelerate-agent doctor
+       accelerate-agent init <empty-directory> [--browser existing]
+       accelerate-agent --version
+
+Set ACCELERATE_API_KEY and ACCELERATE_MERCHANT_ID on your server.
+ACCELERATE_BASE_URL is optional for Accelerate's hosted service.
+
+Doctor checks API connectivity and the credential pair. It does not create a
+checkout, send a code, release credentials, fill a form or submit an order.
+It does not qualify the downstream payment source or browser configuration.
+
+Init copies the packaged synthetic MCP starter without credentials, network
+requests or overwrites. --browser existing selects the new provider-independent
+existing-browser starter; omission preserves the managed Kernel starter.
+Existing symlink paths and nonempty targets are rejected.
+`;
+const starterFiles = ['package.json', '.env.example', '.gitignore', 'README.md', 'server.mjs', 'runtime.mjs',
+  'synthetic.mjs', 'smoke.mjs', 'trusted-context.example.mjs', 'tests/starter.test.mjs'];
+const initFailure = code => { const error = Error('Starter initialization unavailable.'); error.code = code; throw error; };
+async function initializeStarter(directory, existingBrowser = false) {
+  if (typeof directory !== 'string' || !directory || directory.length > 2048 || /[\u0000-\u001f\u007f]/u.test(directory)) initFailure('init_target_invalid');
+  const target = resolve(directory), parent = dirname(target);
+  if (await realpath(parent) !== parent || !(await lstat(parent)).isDirectory()) initFailure('init_target_invalid');
+  try {
+    const stat = await lstat(target);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(target) !== target) initFailure('init_target_invalid');
+    if ((await readdir(target)).length !== 0) initFailure('init_target_not_empty');
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+    await mkdir(target, { mode: 0o700 });
+  }
+  const sourceRoot = resolve(fileURLToPath(new URL(existingBrowser ? './partner-starter/' : './starter/', import.meta.url)));
+  if (await realpath(sourceRoot) !== sourceRoot) initFailure('init_failed');
+  const original = await lstat(target); let total = 0;
+  for (const name of starterFiles) {
+    const current = await lstat(target);
+    if (!current.isDirectory() || current.isSymbolicLink() || current.dev !== original.dev || current.ino !== original.ino ||
+      await realpath(target) !== target) initFailure('init_target_invalid');
+    // npm strips .gitignore from archives; emit it from this explicit template.
+    const sourcePath = join(sourceRoot, name === '.gitignore' ? 'gitignore.template' : name);
+    if (await realpath(sourcePath) !== sourcePath) initFailure('init_failed');
+    const source = await open(sourcePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let data;
+    try {
+      const stat = await source.stat();
+      if (!stat.isFile() || stat.size < 1 || stat.size > 65536 || (total += stat.size) > 262144) initFailure('init_failed');
+      data = await source.readFile();
+    } finally { await source.close(); }
+    const destination = join(target, name), folder = dirname(destination);
+    if (folder !== target) {
+      try { await mkdir(folder, { mode: 0o700 }); } catch (error) { if (error?.code !== 'EEXIST') throw error; }
+      if (!(await lstat(folder)).isDirectory() || await realpath(folder) !== folder) initFailure('init_target_invalid');
+    }
+    const output = await open(destination, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try { await output.writeFile(data); } finally { await output.close(); }
+  }
+}
+const args = process.argv.slice(2);
+if (args.length === 1 && ['--version', '-v'].includes(args[0])) {
+  const { version } = JSON.parse(await readFile(new URL('./package.json', import.meta.url), 'utf8'));
+  if (!/^\d+\.\d+\.\d+$/.test(version)) throw Error('Invalid SDK package version.');
+  process.stdout.write(version + '\n');
+} else if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+  process.stdout.write(help);
+} else if (args[0] === 'init' && (args.length === 2 || args.length === 4 && args[2] === '--browser' && args[3] === 'existing')) {
+  try {
+    await initializeStarter(args[1], args.length === 4);
+    process.stdout.write(JSON.stringify({ ok: true, status: 'initialized', mode: 'synthetic', next_action: 'install_dependencies' }) + '\n');
+  } catch (error) {
+    const code = ['init_target_invalid', 'init_target_not_empty'].includes(error?.code) ? error.code : 'init_failed';
+    process.stdout.write(JSON.stringify({ ok: false, code }) + '\n'); process.exitCode = 1;
+  }
+} else if (args.length !== 1 || args[0] !== 'doctor') {
+  process.stderr.write(help);
+  process.exitCode = 2;
+} else {
+  try {
+    const result = await AccelerateClient.fromEnv().connection.check();
+    // Do not print environment values, merchant identifiers or upstream bodies.
+    process.stdout.write(JSON.stringify({ ok: true, status: result.status, api_version: result.api_version,
+      interaction_modes: result.interaction_modes, currencies: result.currencies,
+      downstream_payment_readiness: 'not_checked' }) + '\n');
+  } catch (error) {
+    const codes = new Set(['missing_api_key', 'missing_merchant_id', 'invalid_api_key', 'invalid_merchant_id',
+      'invalid_base_url', 'invalid_input', 'tenant_unauthorized', 'unauthorized', 'permission_denied',
+      'configuration_error', 'configuration_invalid', 'route_not_found', 'invalid_response',
+      'request_timeout', 'request_cancelled', 'request_failed', 'upstream_unavailable']);
+    const actions = new Set(['check_configuration', 'check_request', 'check_status', 'stop']);
+    const code = error instanceof AccelerateError && codes.has(error.code) ? error.code : 'request_failed';
+    const nextAction = error instanceof AccelerateError && actions.has(error.nextAction)
+      ? error.nextAction : 'check_configuration';
+    process.stdout.write(JSON.stringify({ ok: false, code, next_action: nextAction }) + '\n');
+    process.exitCode = 1;
+  }
+}

package/customer.env.example

@@ -0,0 +1,6 @@
+# Required: provide these through your backend's secret configuration.
+ACCELERATE_API_KEY=
+ACCELERATE_MERCHANT_ID=
+
+# Optional: omit when using Accelerate's hosted managed service.
+# ACCELERATE_BASE_URL=https://accelerate-agent-sdk.vercel.app