@weaccelerateinc/agent-sdk 0.0.0-stage → 0.10.3

package/managed-mcp.d.ts

@@ -0,0 +1,150 @@
+import type { AccelerateClient, AccelerateNextAction, Checkout, CheckoutId, CustomerBrowserBinding } from './index.js';
+import type { BrowserResult } from './browser-operations.js';
+import type { BrowserConnector } from './browser-connector.js';
+
+/** Resolve from authenticated host state. MCP arguments and _meta alone are not identity proof. */
+export interface ManagedCheckoutContext {
+  customer_id: string;
+  workspace_id: string;
+  conversation_id: string;
+  phone_number: string;
+}
+/** Minimal private storage projection; never returned through a model tool. */
+export interface ManagedCheckoutBinding extends ManagedCheckoutContext { checkout_id: CheckoutId }
+export interface ManagedCheckoutCreation {
+  /** Server-derived key for this exact creation attempt, protected by the host's durable fence. */
+  idempotency_key: string;
+  /** Optional existing browser from the host's owned workflow, never MCP input.
+   * Only permitted with browserMode:'customer_backend_trusted'. */
+  browser?: CustomerBrowserBinding;
+  /** Resolve only after durable storage. Retain an uncertainty fence if acknowledgement is lost. */
+  persistCreated(binding: Readonly<ManagedCheckoutBinding>): Promise<void>;
+}
+export interface ManagedMcpError {
+  code: string;
+  message: string;
+  status: number;
+  next_action: AccelerateNextAction;
+  retry_safe: false;
+  payment_confirmed: false;
+  support_reference?: `acs_${string}` | `arq_${string}`;
+}
+export type ManagedMcpOutput = { ok: true; checkout: Checkout } | { ok: true; browser: BrowserResult } |
+  { ok: false; error: ManagedMcpError; checkout?: Checkout };
+export interface ManagedCheckoutEvent {
+  version: 'v1';
+  kind: 'created' | 'payment_requested' | 'approval_requested' | 'review_ready';
+  /** Stable hash-only key; deduplicate delivery durably. Never retry the underlying SDK operation. */
+  idempotency_key: `accelerate-checkout-event:${string}`;
+  checkout: Checkout;
+}
+export interface ManagedMcpToolResult {
+  [key: string]: unknown;
+  content: Array<{ type: 'text'; text: string }>;
+  structuredContent: ManagedMcpOutput;
+  isError?: true;
+}
+export interface ManagedMcpStandardSchema {
+  readonly '~standard': {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => { value: unknown } | { issues: Array<{ message: string }> };
+    readonly jsonSchema: {
+      readonly input: (options?: unknown) => Record<string, unknown>;
+      readonly output: (options?: unknown) => Record<string, unknown>;
+    };
+  };
+}
+export interface ManagedMcpRegisteredDefinition {
+  title: string;
+  description: string;
+  inputSchema: ManagedMcpStandardSchema;
+  outputSchema: ManagedMcpStandardSchema;
+  annotations: { readOnlyHint: boolean; idempotentHint: boolean; destructiveHint: boolean; openWorldHint: true };
+}
+/** Structural MCP2 registration surface; no protocol or schema package is imported at runtime. */
+export interface ManagedMcpServer<Extra = unknown> {
+  registerTool(name: string, definition: ManagedMcpRegisteredDefinition,
+    handler: (args: unknown, extra: Extra) => Promise<ManagedMcpToolResult>): unknown;
+}
+export type ManagedCheckoutProfileId = 'managed_review_v2' | 'managed_review_v1' | 'legacy_before_fill_v1';
+/** Immutable flow metadata. Does not qualify a merchant layout or grant submit
+ * authority. The private sender must verify the actual five-minute window. */
+export const managedCheckoutProfiles: Readonly<{
+  managed_review_v2: Readonly<{ id: 'managed_review_v2'; verificationTiming: 'on_payment';
+    approvalPolicy: 'after_fill'; approvalWindowMs: 300000; fillAfterVerification: true }>;
+  managed_review_v1: Readonly<{ id: 'managed_review_v1'; verificationTiming: 'on_payment';
+    approvalPolicy: 'after_fill'; approvalWindowMs: 300000 }>;
+  legacy_before_fill_v1: Readonly<{ id: 'legacy_before_fill_v1'; verificationTiming: 'on_start';
+    approvalPolicy: 'before_fill' }>;
+}>;
+export interface ManagedCheckoutToolsOptions<Extra = unknown> {
+  /** Defaults to AccelerateClient.fromEnv(). Instantiate only on the authenticated application server. */
+  client?: AccelerateClient;
+  /** Called on EVERY tool invocation; resolve verified host context, not untrusted model metadata. */
+  resolveContext(extra: Extra): Promise<ManagedCheckoutContext> | ManagedCheckoutContext;
+  /**
+   * Hold your existing durable owner lock and uncertainty fence, authorize ALL
+   * binding fields, invoke work exactly once with a minimal saved binding, and
+   * return its result. Never retry an operation or clear an uncertain purchase.
+   */
+  withOwnedCheckout<T>(context: Readonly<ManagedCheckoutContext>, checkoutId: CheckoutId,
+    work: (binding: Readonly<ManagedCheckoutBinding>) => Promise<T>,
+    metadata?: Readonly<{ operation: ManagedCheckoutToolName; revision?: number }>): Promise<T>;
+  /**
+   * Hold the same durable owner lock/fence until work resolves. Supply a stable
+   * server-derived creation key and persistCreated acknowledgement. If creation
+   * or persistence is uncertain, preserve that attempt and reconcile it; never
+   * create a replacement or automatically compensate with another payment call.
+   */
+  withCheckoutCreation<T>(context: Readonly<ManagedCheckoutContext>,
+    work: (creation: ManagedCheckoutCreation) => Promise<T>, metadata?: Readonly<{ start_url: string }>): Promise<T>;
+  /**
+   * Durably accept/deduplicate this SAFE event under its key before privately
+   * starting/reading chat state and rendering/delivering prompts. Use an outbox
+   * to recover lost acknowledgements with the SAME event key, never a new
+   * checkout/payment action. The private client/replies remain outside MCP.
+   * On unconfirmed acceptance the tool returns a fixed error and known safe
+   * checkout ID/revision; the existing owner record and uncertainty fence remain.
+   */
+  dispatchCheckoutEvent(context: Readonly<ManagedCheckoutContext>, event: Readonly<ManagedCheckoutEvent>): Promise<void>;
+  /** Immutable for newly created checkouts. Default sandbox_fill_only. */
+  purpose?: 'sandbox_fill_only' | 'purchase';
+  /** Default false. Registers final-submit tool only when true and purpose is purchase. */
+  enableSubmit?: boolean;
+  /** Default managed_review_v1: verification at payment and approval after fill.
+   * Legacy before-fill behavior requires this explicit profile or approvalPolicy:'before_fill'. */
+  profile?: ManagedCheckoutProfileId;
+  /** Must be on_payment for managed_review_v1/v2. Legacy allows either timing and defaults to on_start. */
+  verificationTiming?: 'on_start' | 'on_payment';
+  /** Must match the selected profile. An explicit before_fill without profile
+   * deliberately selects legacy behavior; requested after-fill never downgrades. */
+  approvalPolicy?: 'before_fill' | 'after_fill';
+  /** Explicitly selects trusted customer-backend existing-browser attachment. The
+   * default remains Accelerate-created private browser custody. */
+  browserMode?: 'accelerate_managed' | 'customer_backend_trusted';
+  /** Optional strict existing-browser lifecycle. Requires customer_backend_trusted
+   * and managed_review_v1. The legacy server-provided scope.browser path remains explicit. */
+  browserConnector?: BrowserConnector;
+}
+export type ManagedCheckoutToolName = 'accelerate_checkout_start' | 'accelerate_checkout_status' | 'accelerate_checkout_browser' |
+  'accelerate_checkout_request_payment' | 'accelerate_checkout_apply_details' | 'accelerate_checkout_request_approval' |
+  'accelerate_checkout_fill' | 'accelerate_checkout_cancel' | 'accelerate_checkout_submit';
+export interface ManagedCheckoutToolDefinition {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: Readonly<Record<string, unknown>>;
+  outputSchema: Readonly<Record<string, unknown>>;
+  annotations: Readonly<ManagedMcpRegisteredDefinition['annotations']>;
+  readOnly?: true;
+  destructive?: true;
+  submitOnly?: true;
+  /** Registered only when verificationTiming is on_payment. */
+  paymentOnly?: true;
+}
+/** Frozen canonical JSON Schemas and descriptions for discovery/documentation. */
+export const managedCheckoutToolDefinitions: readonly Readonly<ManagedCheckoutToolDefinition>[];
+/** Register on the customer's authenticated MCP server, with private ingress configured separately. */
+export function registerManagedCheckoutTools<Extra = unknown>(server: ManagedMcpServer<Extra>,
+  options: ManagedCheckoutToolsOptions<Extra>): readonly unknown[];

package/managed-mcp.js

@@ -0,0 +1,382 @@
+import { AccelerateClient, AccelerateError } from './index.js';
+import { browserOperationJsonSchema, parseBrowserOperation, normalizeBrowserOperation } from './browser-operations.js';
+import { checkoutDiagnosticsJsonSchema, validateCheckoutDiagnostics } from './checkout-diagnostics.js';
+import { createHash } from 'node:crypto';
+
+const ID = /^mcs_[A-Za-z0-9_-]{43}$/;
+const OWNER = /^[A-Za-z0-9_.:-]{1,500}$/;
+const PHONE = /^\+[1-9]\d{6,14}$/;
+const CONTEXT_KEYS = ['customer_id', 'workspace_id', 'conversation_id', 'phone_number'];
+const STATUSES = ['wallet_required', 'selection_ready', 'details_ready', 'approval_required', 'approved',
+  'ready_for_submit', 'cancelled', 'expired', 'failed', 'submit_attempted', 'outcome_unknown'];
+const NEXT_ACTIONS = ['check_configuration', 'check_request', 'check_status', 'complete_wallet',
+  'complete_verification', 'refresh_quote', 'refresh_revision', 'reconcile_order', 'stop'];
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value) &&
+  [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const check = (value, code = 'invalid_input') => { if (!value) throw new AccelerateError(code); };
+function shape(value, required, optional = [], code = 'invalid_input') {
+  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)) {
+    for (const child of Object.values(value)) freeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+/** Versioned server-selected flow policies. Merchant/layout qualification and
+ * the actual delivered five-minute window are verified by the managed service
+ * and private review sender; these constants grant no payment capability. */
+export const managedCheckoutProfiles = freeze({
+  managed_review_v2: { id: 'managed_review_v2', verificationTiming: 'on_payment',
+    approvalPolicy: 'after_fill', approvalWindowMs: 300000, fillAfterVerification: true },
+  managed_review_v1: { id: 'managed_review_v1', verificationTiming: 'on_payment',
+    approvalPolicy: 'after_fill', approvalWindowMs: 300000 },
+  legacy_before_fill_v1: { id: 'legacy_before_fill_v1', verificationTiming: 'on_start',
+    approvalPolicy: 'before_fill' },
+});
+function flowProfile({ profile, verificationTiming, approvalPolicy }) {
+  const id = profile === undefined ? approvalPolicy === 'before_fill' ? 'legacy_before_fill_v1' : 'managed_review_v1' : profile;
+  check(typeof id === 'string' && Object.hasOwn(managedCheckoutProfiles, id));
+  const selected = managedCheckoutProfiles[id];
+  const timing = verificationTiming === undefined ? selected.verificationTiming : verificationTiming;
+  const approval = approvalPolicy === undefined ? selected.approvalPolicy : approvalPolicy;
+  check(approval === selected.approvalPolicy && ['on_start', 'on_payment'].includes(timing) &&
+    (id === 'legacy_before_fill_v1' || timing === selected.verificationTiming));
+  return freeze({ ...selected, verificationTiming: timing });
+}
+const schemaObject = (properties, required = Object.keys(properties)) => ({ type: 'object', properties,
+  required, additionalProperties: false });
+const stringSchema = maxLength => ({ type: 'string', minLength: 1, maxLength });
+const idSchema = { type: 'string', pattern: ID.source };
+const revisionSchema = { type: 'integer', minimum: 1, maximum: 2147483647 };
+const urlSchema = { ...stringSchema(2048), format: 'uri', description: 'Actual public HTTPS merchant checkout URL. No credentials or private browser URLs.' };
+const timestampSchema = { type: 'string', format: 'date-time' };
+const nullableText = max => ({ anyOf: [stringSchema(max), { type: 'null' }] });
+const checkoutSchema = schemaObject({
+  id: idSchema, status: { type: 'string', enum: STATUSES }, revision: { type: 'integer', minimum: 0, maximum: 2147483647 },
+  expires_at: timestampSchema, purpose: { type: 'string', enum: ['purchase', 'sandbox_source_comparison', 'sandbox_fill_only'] },
+  approval_policy: { const: 'after_fill' }, purchase_approved: { type: 'boolean' },
+  fill_after_verification: { const: true },
+  submit_allowed: { type: 'boolean' }, retry_safe: { const: false }, payment_confirmed: { const: false },
+  card: schemaObject({ last4: { anyOf: [{ type: 'string', pattern: '^\\d{4}$' }, { type: 'null' }] }, brand: nullableText(40) }),
+  address: schemaObject({ label: nullableText(400), city: nullableText(128), state: nullableText(128), postal_code_mask: nullableText(128) }, ['label']),
+  quote: schemaObject({ checkout_origin: urlSchema, amount_cents: revisionSchema, currency: { const: 'USD' } }),
+  submit_expires_at: timestampSchema, diagnostics: checkoutDiagnosticsJsonSchema,
+}, ['id', 'status', 'revision', 'expires_at', 'retry_safe', 'payment_confirmed']);
+const browserSchema = schemaObject({ content: { type: 'array', minItems: 1, maxItems: 20,
+  items: schemaObject({ type: { const: 'text' }, text: { type: 'string', maxLength: 24000 } }) } });
+const errorSchema = schemaObject({ code: { type: 'string', pattern: '^[a-z][a-z0-9_]{0,63}$' }, message: stringSchema(500),
+  status: { type: 'integer', minimum: 0, maximum: 599 }, next_action: { type: 'string', enum: NEXT_ACTIONS },
+  retry_safe: { const: false }, payment_confirmed: { const: false },
+  support_reference: { type: 'string', pattern: '^(?:acs_|arq_)[a-f0-9]{32}$' },
+}, ['code', 'message', 'status', 'next_action', 'retry_safe', 'payment_confirmed']);
+const failureSchema = schemaObject({ ok: { const: false }, error: errorSchema, checkout: checkoutSchema }, ['ok', 'error']);
+const outputSchema = kind => ({ type: 'object', oneOf: [schemaObject({ ok: { const: true }, [kind]: kind === 'browser' ? browserSchema : checkoutSchema }), failureSchema] });
+const idInput = schemaObject({ checkout_id: idSchema });
+const revisionInput = schemaObject({ checkout_id: idSchema, revision: revisionSchema });
+const browserInput = { ...browserOperationJsonSchema, oneOf: browserOperationJsonSchema.oneOf.map(branch => ({ ...branch,
+  properties: { checkout_id: idSchema, ...branch.properties }, required: ['checkout_id', ...branch.required] })) };
+
+/** One model-visible contract. Private authentication and reply APIs are deliberately absent. */
+export const managedCheckoutToolDefinitions = freeze([
+  { name: 'accelerate_checkout_start', title: 'Start Accelerate checkout',
+    description: 'Start one owned chat checkout in Accelerate’s managed private browser. Identity, phone, immutable test/purchase policy and creation idempotency come from your authenticated server. The default managed_review_v1 profile defers verification until payment: prepare the purchase before calling accelerate_checkout_request_payment. Legacy verification at creation requires deliberate server configuration. Shopper verification stays private in chat. Does not submit payment. Never restart an uncertain purchase.',
+    inputSchema: schemaObject({ start_url: urlSchema }), outputSchema: outputSchema('checkout') },
+  { name: 'accelerate_checkout_status', title: 'Read Accelerate checkout status',
+    description: 'Read safe status, current revision and optional fixed recovery guidance for this owned checkout. No card credentials, private wallet tokens or browser connection are returned. Status and guidance do not confirm an order or authorize retries.',
+    inputSchema: idInput, outputSchema: outputSchema('checkout'), readOnly: true },
+  { name: 'accelerate_checkout_browser', title: 'Prepare merchant checkout',
+    description: 'Prepare this same managed checkout browser with restricted text observations, public navigation and safe actions. In deferred verification mode, shop and reach payment before requesting wallet verification; wallet_required does not prevent preparation. Each result replaces ALL earlier element refs; use only the latest refs and batch at most eight steps. No scripts, screenshots, card entry or final purchase. Generic inspection is fenced after private handover.',
+    inputSchema: browserInput, outputSchema: outputSchema('browser') },
+  { name: 'accelerate_checkout_request_payment', title: 'Start private payment verification',
+    description: 'At the merchant payment step, request private OTP and masked wallet selection for this existing owned browser. Available only with deferred verification and while wallet_required. Request this only when the observed merchant page requires payment information, never merely because status is wallet_required or diagnostics suggest private chat. Fresh CVV is requested privately after the final quote is verified; with after_fill policy the customer reviews and approves only after private filling. Does not approve, fill or submit. Private dispatch is deduplicated for this checkout; check this existing checkout after uncertain delivery instead of creating a replacement.',
+    inputSchema: idInput, outputSchema: outputSchema('checkout'), paymentOnly: true },
+  { name: 'accelerate_checkout_apply_details', title: 'Apply selected wallet address',
+    description: 'Privately apply the shopper’s selected saved address to the current merchant checkout before final shipping, tax and total. The agent supplies only the checkout URL; address values stay private. Reinspect the actual final total afterward.',
+    inputSchema: schemaObject({ checkout_id: idSchema, checkout_url: urlSchema }), outputSchema: outputSchema('checkout') },
+  { name: 'accelerate_checkout_request_approval', title: 'Request exact checkout approval',
+    description: 'Freeze the actual final merchant URL, USD cents, total control and final-submit control. Accelerate independently verifies the page total. With after_fill policy this requests private CVV for filling, then the customer reviews a masked screenshot and approves the final amount afterward. With before_fill policy it requests approval first. This call never fills or submits.',
+    inputSchema: schemaObject({ checkout_id: idSchema, checkout_url: urlSchema, amount_cents: revisionSchema, currency: { const: 'USD' },
+      checkout_total_selector: stringSchema(500), submit_selector: stringSchema(200) }), outputSchema: outputSchema('checkout') },
+  { name: 'accelerate_checkout_fill', title: 'Fill approved checkout privately',
+    description: 'Fill this exact CVV-verified revision once through Accelerate’s private extension. No automatic submission. The default managed_review_v1 profile requires private ingress to deliver the masked filled review and final total, then wait for explicit customer approval. Its five-minute decision window starts at confirmed private message delivery; the private sender verifies the actual window. purchase_approved must be true before submit. Observe the returned submit deadline and cancel fill-only tests after review. Never replay a failed or uncertain fill.',
+    inputSchema: revisionInput, outputSchema: outputSchema('checkout'), destructive: true },
+  { name: 'accelerate_checkout_cancel', title: 'Cancel owned checkout',
+    description: 'Cancel this exact owned checkout and request private browser cleanup. Cancellation does not reverse an attempted order or prove that no purchase occurred. Keep uncertain-payment fences until independently reconciled.',
+    inputSchema: idInput, outputSchema: outputSchema('checkout'), destructive: true },
+  { name: 'accelerate_checkout_submit', title: 'Explicitly submit approved purchase',
+    description: 'Explicit final purchase decision for this exact owned revision while its returned ready claim remains valid. Calls the one-use private final-submit operation once. Never automatically invoke after fill or retry after uncertainty. The default review profile requires the customer’s private post-fill approval first. submit_attempted is not order or payment confirmation. Available only when the server explicitly enables purchase submission.',
+    inputSchema: revisionInput, outputSchema: outputSchema('checkout'), destructive: true, submitOnly: true },
+].map(value => ({ ...value, annotations: { readOnlyHint: value.readOnly === true, idempotentHint: value.readOnly === true,
+  destructiveHint: value.destructive === true, openWorldHint: true } })));
+
+function safeText(value, max = 1000, multiline = false) {
+  check(typeof value === 'string' && value.length > 0 && value.length <= max &&
+    !(multiline ? /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u : /[\u0000-\u001f\u007f]/u).test(value), 'invalid_response');
+  const flat = value.replace(/[\r\n\t]/g, ' ');
+  check(!/\b(?:session_token|handoff_token|submit_token|id_token|authorizationToken|api_key|hmac_secret)\b/iu.test(flat), 'invalid_response');
+  for (let start = 0; start < flat.length; start += 1000) {
+    try { normalizeBrowserOperation('browser_act', { steps: [{ type: 'type', text: flat.slice(start, start + 2000) }] }); }
+    catch { throw new AccelerateError('invalid_response'); }
+  }
+  return value;
+}
+function timestamp(value) { check(typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T[\d:.]+Z$/u.test(value) && Number.isFinite(Date.parse(value)), 'invalid_response'); return value; }
+function projectCheckout(value) {
+  shape(value, ['id', 'status', 'revision', 'expires_at', 'retry_safe', 'payment_confirmed'],
+    ['purpose', 'submit_allowed', 'approval_policy', 'purchase_approved', 'fill_after_verification', 'card', 'address', 'quote', 'submit_expires_at', 'diagnostics'], 'invalid_response');
+  check(typeof value.id === 'string' && ID.test(value.id) && STATUSES.includes(value.status) && Number.isSafeInteger(value.revision) &&
+    value.revision >= 0 && value.revision <= 2147483647 && value.retry_safe === false && value.payment_confirmed === false, 'invalid_response');
+  const result = { id: value.id, status: value.status, revision: value.revision, expires_at: timestamp(value.expires_at), retry_safe: false, payment_confirmed: false };
+  if (value.purpose !== undefined || value.submit_allowed !== undefined) {
+    check(['purchase', 'sandbox_source_comparison', 'sandbox_fill_only'].includes(value.purpose) && value.submit_allowed === (value.purpose === 'purchase'), 'invalid_response');
+    result.purpose = value.purpose; result.submit_allowed = value.submit_allowed;
+  }
+  if (value.approval_policy !== undefined || value.purchase_approved !== undefined) {
+    check(value.approval_policy === 'after_fill' && typeof value.purchase_approved === 'boolean' && (!value.purchase_approved || value.status === 'ready_for_submit' && value.purpose === 'purchase'), 'invalid_response');
+    result.approval_policy = value.approval_policy; result.purchase_approved = value.purchase_approved;
+  }
+  if (value.fill_after_verification !== undefined) {
+    check(value.fill_after_verification === true && value.approval_policy === 'after_fill' &&
+      ['purchase', 'sandbox_fill_only'].includes(value.purpose), 'invalid_response');
+    result.fill_after_verification = true;
+  }
+  if (value.card !== undefined) {
+    shape(value.card, ['last4', 'brand'], [], 'invalid_response');
+    check(value.card.last4 === null || typeof value.card.last4 === 'string' && /^\d{4}$/u.test(value.card.last4), 'invalid_response');
+    result.card = { last4: value.card.last4, brand: value.card.brand === null ? null : safeText(value.card.brand, 40) };
+  }
+  if (value.address !== undefined) {
+    shape(value.address, ['label'], ['city', 'state', 'postal_code_mask'], 'invalid_response');
+    result.address = { label: value.address.label === null ? null : safeText(value.address.label, 400) };
+    for (const key of ['city', 'state', 'postal_code_mask']) if (value.address[key] !== undefined) result.address[key] =
+      value.address[key] === null ? null : safeText(value.address[key], 128);
+    check(result.address.postal_code_mask == null || /[*•]/u.test(result.address.postal_code_mask), 'invalid_response');
+  }
+  if (value.quote !== undefined) {
+    shape(value.quote, ['checkout_origin', 'amount_cents', 'currency'], [], 'invalid_response');
+    const url = new URL(value.quote.checkout_origin);
+    check(url.origin === value.quote.checkout_origin && Number.isSafeInteger(value.quote.amount_cents) && value.quote.amount_cents > 0 &&
+      value.quote.amount_cents <= 2147483647 && value.quote.currency === 'USD', 'invalid_response');
+    try { normalizeBrowserOperation('navigate', { url: value.quote.checkout_origin }); } catch { throw new AccelerateError('invalid_response'); }
+    result.quote = { checkout_origin: value.quote.checkout_origin, amount_cents: value.quote.amount_cents, currency: 'USD' };
+  }
+  if (value.submit_expires_at !== undefined) result.submit_expires_at = timestamp(value.submit_expires_at);
+  if (value.diagnostics !== undefined) result.diagnostics = JSON.parse(JSON.stringify(validateCheckoutDiagnostics(value.diagnostics, result)));
+  return result;
+}
+function projectBrowser(value) {
+  shape(value, ['content'], [], 'invalid_response'); check(Array.isArray(value.content) && value.content.length >= 1 && value.content.length <= 20, 'invalid_response');
+  let total = 0;
+  const content = value.content.map(part => {
+    shape(part, ['type', 'text'], [], 'invalid_response'); check(part.type === 'text', 'invalid_response');
+    // An empty text block is allowed by the ordinary browser result contract.
+    const text = part.text === '' ? '' : safeText(part.text, 24000, true); total += Buffer.byteLength(text, 'utf8');
+    return { type: 'text', text };
+  });
+  check(total <= 24000, 'invalid_response'); return { content };
+}
+function projectError(error) {
+  let safe;
+  try { safe = error instanceof AccelerateError ? new AccelerateError(error.code, error.status, error.supportReference) : new AccelerateError('request_failed'); }
+  catch { safe = new AccelerateError('request_failed'); }
+  return { code: safe.code, message: safe.message, status: safe.status, next_action: safe.nextAction,
+    retry_safe: false, payment_confirmed: false, ...(typeof safe.supportReference === 'string' && /^(?:acs_|arq_)[a-f0-9]{32}$/u.test(safe.supportReference)
+      ? { support_reference: safe.supportReference } : {}) };
+}
+function parseOutput(value, kind) {
+  if (value?.ok === false) {
+    shape(value, ['ok', 'error'], ['checkout'], 'invalid_response');
+    shape(value.error, ['code', 'message', 'status', 'next_action', 'retry_safe', 'payment_confirmed'], ['support_reference'], 'invalid_response');
+    const expected = projectError(new AccelerateError(value.error.code, value.error.status, value.error.support_reference));
+    check(Object.keys(expected).length === Object.keys(value.error).length && Object.keys(expected).every(key => expected[key] === value.error[key]), 'invalid_response');
+    if (value.checkout !== undefined) check(value.error.code === 'checkout_event_unconfirmed', 'invalid_response');
+    return { ok: false, error: expected, ...(value.checkout !== undefined ? { checkout: projectCheckout(value.checkout) } : {}) };
+  }
+  shape(value, ['ok', kind], [], 'invalid_response'); check(value.ok === true, 'invalid_response');
+  return { ok: true, [kind]: kind === 'browser' ? projectBrowser(value.browser) : projectCheckout(value.checkout) };
+}
+function parseInput(name, value) {
+  const base = name === 'accelerate_checkout_start' ? ['start_url'] : name === 'accelerate_checkout_browser'
+    ? ['checkout_id', 'operation', 'arguments'] : name === 'accelerate_checkout_apply_details' ? ['checkout_id', 'checkout_url']
+      : name === 'accelerate_checkout_request_approval' ? ['checkout_id', 'checkout_url', 'amount_cents', 'currency', 'checkout_total_selector', 'submit_selector']
+        : ['accelerate_checkout_fill', 'accelerate_checkout_submit'].includes(name) ? ['checkout_id', 'revision'] : ['checkout_id'];
+  shape(value, base);
+  if (value.checkout_id !== undefined) check(typeof value.checkout_id === 'string' && ID.test(value.checkout_id));
+  if (name === 'accelerate_checkout_browser') return { checkout_id: value.checkout_id, ...parseBrowserOperation({ operation: value.operation, arguments: value.arguments }) };
+  for (const key of ['start_url', 'checkout_url']) if (value[key] !== undefined) normalizeBrowserOperation('navigate', { url: value[key] });
+  if (value.revision !== undefined) check(Number.isSafeInteger(value.revision) && value.revision >= 1 && value.revision <= 2147483647);
+  if (name === 'accelerate_checkout_request_approval') {
+    check(Number.isSafeInteger(value.amount_cents) && value.amount_cents > 0 && value.amount_cents <= 2147483647 && value.currency === 'USD');
+    for (const [key, max] of [['checkout_total_selector', 500], ['submit_selector', 200]]) {
+      check(typeof value[key] === 'string' && value[key].length > 0 && value[key].length <= max && !/[\u0000-\u001f\u007f]/u.test(value[key]));
+      normalizeBrowserOperation('browser_act', { steps: [{ type: 'type', text: value[key] }] });
+    }
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+function standardSchema(json, parse) {
+  return freeze({ '~standard': { version: 1, vendor: 'accelerate-managed-checkout',
+    validate(value) { try { return { value: parse(value) }; } catch { return { issues: [{ message: 'Invalid Accelerate managed checkout tool value.' }] }; } },
+    jsonSchema: { input: () => json, output: () => json } } });
+}
+function contextInput(value) {
+  shape(value, CONTEXT_KEYS, [], 'permission_denied');
+  check(CONTEXT_KEYS.slice(0, 3).every(key => typeof value[key] === 'string' && OWNER.test(value[key])) &&
+    typeof value.phone_number === 'string' && PHONE.test(value.phone_number), 'permission_denied');
+  return Object.freeze(Object.fromEntries(CONTEXT_KEYS.map(key => [key, value[key]])));
+}
+function requestOptions(extra) { return extra?.signal instanceof AbortSignal ? { signal: extra.signal } : {}; }
+
+/**
+ * Register on an authenticated CUSTOMER server. The host's hooks resolve verified
+ * identity and hold the durable ownership/uncertainty fence; MCP arguments and
+ * extra/_meta are never authentication proof by themselves. Hooks invoke work
+ * exactly once, return its result and never retry it. A failed creation/persistence
+ * acknowledgement must keep a durable uncertainty fence, not create a replacement.
+ */
+export function registerManagedCheckoutTools(server, { client = AccelerateClient.fromEnv(), resolveContext,
+  withOwnedCheckout, withCheckoutCreation, dispatchCheckoutEvent, purpose = 'sandbox_fill_only', enableSubmit = false,
+  profile, verificationTiming: requestedTiming, approvalPolicy: requestedApproval, browserMode = 'accelerate_managed', browserConnector } = {}) {
+  const { verificationTiming, approvalPolicy, fillAfterVerification = false } = flowProfile({ profile, verificationTiming: requestedTiming, approvalPolicy: requestedApproval });
+  check(server && typeof server.registerTool === 'function' && client?.checkouts &&
+    ['create', 'get', 'browser', 'applyDetails', 'requestApproval', 'fill', 'submit', 'cancel'].every(key => typeof client.checkouts[key] === 'function') &&
+    [resolveContext, withOwnedCheckout, withCheckoutCreation, dispatchCheckoutEvent].every(value => typeof value === 'function') &&
+    ['purchase', 'sandbox_fill_only'].includes(purpose) && typeof enableSubmit === 'boolean' && (!enableSubmit || purpose === 'purchase') &&
+    ['on_start', 'on_payment'].includes(verificationTiming) && ['before_fill', 'after_fill'].includes(approvalPolicy) &&
+    ['accelerate_managed', 'customer_backend_trusted'].includes(browserMode) &&
+    (browserMode !== 'customer_backend_trusted' || verificationTiming === 'on_payment' && approvalPolicy === 'after_fill') &&
+    (browserConnector === undefined || browserMode === 'customer_backend_trusted' && browserConnector?.contract === 'accelerate_existing_browser_v1' &&
+      ['prepareAttachment', 'commitAttachment', 'assertPaymentReady', 'confirmCleanup'].every(key => typeof browserConnector[key] === 'function')));
+  const requirePolicy = checkout => {
+    check(approvalPolicy === 'after_fill' ? checkout.approval_policy === 'after_fill' && typeof checkout.purchase_approved === 'boolean'
+      : checkout.approval_policy === undefined && checkout.purchase_approved === undefined, 'invalid_response');
+    return checkout;
+  };
+  const registered = [];
+  for (const definition of managedCheckoutToolDefinitions) {
+    if (fillAfterVerification && definition.name === 'accelerate_checkout_fill') continue;
+    if (definition.submitOnly && !enableSubmit) continue;
+    if (definition.paymentOnly && verificationTiming !== 'on_payment') continue;
+    const kind = definition.name === 'accelerate_checkout_browser' ? 'browser' : 'checkout';
+    const customerDescriptions = {
+      accelerate_checkout_start: 'At the merchant payment step, attach the exact existing HTTPS browser document selected by the authenticated backend. Finish shopping, cart changes, all required non-secret contact/shipping fields, any required cardholder-name (cc-name) field and navigation before attachment; use ordinary customer details or ask for missing non-secret details. Leave card number/PAN, expiry and CVV empty; never obtain them through ordinary browser tools. It never creates a replacement browser. A configured connector checks ownership, extension readiness, recording policy, lifetime and automation fencing before private verification. The executor must admit actual unambiguous card fields, supported frames and safe masked review in that document before OTP or CVV. Compatible forms are detected across merchants; unsupported or ambiguous layouts stop before private collection. Identity, phone, browser connection and immutable policy are never model inputs. Continue with accelerate_checkout_request_payment. Does not fill or submit. Never restart an uncertain checkout.',
+      accelerate_checkout_browser: 'Read this exact attached checkout with snapshot, text, find or bounded wait before quote handover. Cart changes, required non-secret contact/shipping and cardholder-name fields, and navigation must finish in the platform browser before attachment. Card number/PAN, expiry and CVV remain private and must never be entered through ordinary browser tools. Generic browser actions, scripts, screenshots and credential inspection are forbidden. Each result replaces all previous element refs. Once the quote is frozen, ordinary inspection is fenced; use safe checkout status only. The private masked review is delivered outside model tools.',
+    };
+    const description = fillAfterVerification && definition.name === 'accelerate_checkout_request_approval'
+      ? 'Verify the actual final merchant quote and explicitly arm one private card fill for this exact revision, card, address and existing browser. Successful private CVV verification immediately continues the armed fill in Accelerate’s backend, without a model roundtrip. The private ingress sends the masked filled review and final total. Do not call a manual fill or submit automatically; final purchase approval and the explicit agent submit remain separate.'
+      : browserMode === 'customer_backend_trusted' ? customerDescriptions[definition.name] ?? definition.description : definition.description;
+    registered.push(server.registerTool(definition.name, { title: definition.title, description,
+      inputSchema: standardSchema(definition.inputSchema, value => parseInput(definition.name, value)),
+      outputSchema: standardSchema(definition.outputSchema, value => parseOutput(value, kind)), annotations: definition.annotations,
+    }, async (args, extra) => {
+      let creationStarted = false, creationAcknowledged = false;
+      try {
+        // Re-resolve for EVERY invocation; never cache a shopper across calls.
+        const context = contextInput(await resolveContext(extra));
+        let input;
+        try { input = parseInput(definition.name, args); } catch { throw new AccelerateError('invalid_input'); }
+        const options = requestOptions(extra);
+        let admitting = true;
+        const requireAdmission = () => check(admitting, 'operation_conflict');
+        const dispatch = async (kind, checkout) => {
+          requireAdmission();
+          const key = createHash('sha256').update(JSON.stringify(['v1', kind, checkout.id, ['approval_requested', 'review_ready'].includes(kind) ? checkout.revision : 0])).digest('hex');
+          const event = freeze({ version: 'v1', kind, idempotency_key: 'accelerate-checkout-event:' + key, checkout: projectCheckout(checkout) });
+          try { await dispatchCheckoutEvent(context, event); requireAdmission(); return { ok: true, checkout }; }
+          catch { requireAdmission(); return { ok: false, error: projectError(new AccelerateError('checkout_event_unconfirmed')), checkout }; }
+        };
+        let called = false, completed = false, repeated = false, expected;
+        const once = work => value => {
+          const pending = (async () => {
+            if (!admitting || called) { repeated = true; throw new AccelerateError('operation_conflict'); }
+            called = true;
+            const output = await work(value); requireAdmission(); completed = true; expected = output; return output;
+          })();
+          // A broken host must not turn a deliberately rejected late callback
+          // into an unhandled process rejection. The returned promise still rejects.
+          void pending.catch(() => {}); return pending;
+        };
+        let result;
+        try {
+        if (definition.name === 'accelerate_checkout_start') {
+          result = await withCheckoutCreation(context, once(async scope => {
+            shape(scope, ['idempotency_key', 'persistCreated'], browserMode === 'customer_backend_trusted' && !browserConnector ? ['browser', 'browser_resource'] : []);
+            check(typeof scope.idempotency_key === 'string' && scope.idempotency_key.length >= 1 && scope.idempotency_key.length <= 200 &&
+              !/[\u0000-\u001f\u007f]/u.test(scope.idempotency_key) && typeof scope.persistCreated === 'function');
+            const attachment = browserConnector ? await browserConnector.prepareAttachment(context, {
+              attempt_key: scope.idempotency_key, checkout_url: input.start_url,
+            }, options) : undefined;
+            requireAdmission();
+            const browser = attachment ? attachment.browser : scope.browser;
+            if (browserMode === 'customer_backend_trusted') {
+              shape(browser, ['provider', 'browser_id', 'custody_mode'], browser?.provider === 'connector' ? ['connector_id'] : [], 'permission_denied');
+              const valid = browser.provider === 'browser_use'
+                ? typeof browser.browser_id === 'string' && /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/u.test(browser.browser_id)
+                : browser.provider === 'connector' && typeof browser.connector_id === 'string' && /^[a-z][a-z0-9_-]{0,63}$/u.test(browser.connector_id) &&
+                  typeof browser.browser_id === 'string' && /^[A-Za-z0-9_.:-]{1,200}$/u.test(browser.browser_id);
+              check(valid && browser.custody_mode === browserMode, 'permission_denied');
+            }
+            creationStarted = true;
+            const created = await client.checkouts.create({ ...context, start_url: input.start_url,
+              idempotency_key: scope.idempotency_key, interaction_mode: 'chat', purpose,
+              ...(browserMode === 'customer_backend_trusted' ? { browser: { ...browser } } : {}),
+              ...(attachment?.browser_resource ?? scope.browser_resource ? { browser_resource: attachment?.browser_resource ?? scope.browser_resource } : {}),
+              ...(approvalPolicy === 'after_fill' ? { approval_policy: approvalPolicy } : {}),
+              ...(fillAfterVerification ? { fill_after_verification: true } : {}) }, options);
+            requireAdmission(); const checkout = requirePolicy(projectCheckout(created));
+            check(approvalPolicy !== 'after_fill' || checkout.purchase_approved === false, 'invalid_response');
+            check(!fillAfterVerification || checkout.fill_after_verification === true, 'invalid_response');
+            check(checkout.purpose === purpose && checkout.submit_allowed === (purpose === 'purchase'), 'invalid_response');
+            await scope.persistCreated(Object.freeze({ checkout_id: checkout.id, ...context })); requireAdmission();
+            if (browserConnector) { await browserConnector.commitAttachment(context, { checkout_id: checkout.id, attachment }, options); requireAdmission(); }
+            creationAcknowledged = true;
+            return verificationTiming === 'on_payment' ? { ok: true, checkout } : dispatch('created', checkout);
+          }), Object.freeze({ start_url: input.start_url }));
+        } else {
+          result = await withOwnedCheckout(context, input.checkout_id, once(async owned => {
+            shape(owned, ['checkout_id', ...CONTEXT_KEYS], [], 'permission_denied');
+            check(owned.checkout_id === input.checkout_id && CONTEXT_KEYS.every(key => owned[key] === context[key]), 'permission_denied');
+            const id = input.checkout_id;
+            let value;
+            if (['accelerate_checkout_status', 'accelerate_checkout_request_payment'].includes(definition.name)) value = await client.checkouts.get(id, options);
+            else if (definition.name === 'accelerate_checkout_browser') value = await client.checkouts.browser(id, { operation: input.operation, arguments: input.arguments }, options);
+            else if (definition.name === 'accelerate_checkout_apply_details') value = await client.checkouts.applyDetails(id, { checkout_url: input.checkout_url }, options);
+            else if (definition.name === 'accelerate_checkout_request_approval') {
+              if (browserConnector) { await browserConnector.assertPaymentReady(context, { checkout_id: id, checkout_url: input.checkout_url }, options); requireAdmission(); }
+              const { checkout_id: _id, ...approval } = input;
+              value = await client.checkouts.requestApproval(id, { ...approval, ...(fillAfterVerification ? { fill_after_verification: true } : {}) }, options);
+              check(!fillAfterVerification || value.fill_after_verification === true, 'invalid_response');
+            } else if (definition.name === 'accelerate_checkout_fill') value = await client.checkouts.fill(id, { revision: input.revision }, options);
+            else if (definition.name === 'accelerate_checkout_submit') { check(enableSubmit && purpose === 'purchase', 'permission_denied'); value = await client.checkouts.submit(id, { revision: input.revision }, options); }
+            else value = await client.checkouts.cancel(id, options);
+            requireAdmission();
+            const projected = kind === 'browser' ? projectBrowser(value) : requirePolicy(projectCheckout(value));
+            if (kind === 'checkout') check(projected.id === id, 'invalid_response');
+            if (definition.name === 'accelerate_checkout_request_payment') {
+              check(projected.status === 'wallet_required', 'checkout_frozen');
+              if (browserConnector) { await browserConnector.assertPaymentReady(context, { checkout_id: id }, options); requireAdmission(); }
+              return dispatch('payment_requested', projected);
+            }
+            if (browserConnector && ['accelerate_checkout_cancel', 'accelerate_checkout_status'].includes(definition.name) &&
+              projected.diagnostics?.cleanup_status === 'confirmed') {
+              await browserConnector.confirmCleanup(context, { checkout_id: id }, options); requireAdmission();
+            }
+            if (definition.name === 'accelerate_checkout_fill' && approvalPolicy === 'after_fill') return dispatch('review_ready', projected);
+            return definition.name === 'accelerate_checkout_request_approval' ? dispatch('approval_requested', projected) : { ok: true, [kind]: projected };
+          }), Object.freeze({ operation: definition.name, ...(input.revision === undefined ? {} : { revision: input.revision }) }));
+        }
+        } finally { admitting = false; }
+        check(called && completed && !repeated && result === expected, 'operation_conflict');
+        const payload = parseOutput(result, kind);
+        return { ...(payload.ok === false ? { isError: true } : {}), content: [{ type: 'text', text: JSON.stringify(payload) }], structuredContent: payload };
+      } catch (error) {
+        const payload = { ok: false, error: projectError(creationStarted && !creationAcknowledged ? new AccelerateError('outcome_unknown') : error) };
+        return { isError: true, content: [{ type: 'text', text: JSON.stringify(payload) }], structuredContent: payload };
+      }
+    }));
+  }
+  return Object.freeze(registered);
+}