@weaccelerateinc/agent-sdk 0.0.0-stage → 0.11.0

package/managed-mcp.js

@@ -0,0 +1,427 @@
+import { AccelerateClient, AccelerateError } from './index.js';
+import { browserOperationJsonSchema, parseBrowserOperation, normalizeBrowserOperation } from './browser-operations.js';
+import { checkoutDiagnosticsJsonSchema, validateCheckoutDiagnostics, validateCheckoutReconciliation } 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', 'final_click_armed', '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'];
+// Errors that prove the final-click arm was not created. Everything else after an arm request is an unknown outcome.
+const PRE_ARM_REFUSALS = new Set(['approval_required', 'revision_conflict', 'checkout_expired', 'checkout_closed', 'customer_click_required',
+  'permission_denied', 'submit_unavailable', 'capability_disabled']);
+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 },
+  final_click_actor: { const: 'customer' }, submit_actor: { const: 'customer' },
+  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. Accelerate never clicks: this arms one short-lived click, your own backend performs the single physical final click in the customer’s existing browser, then Accelerate observes the outcome 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', 'reconciliation', 'final_click_actor', 'submit_actor'], '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 || ['ready_for_submit', 'final_click_armed'].includes(value.status) && 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;
+  }
+  // The customer's own backend/browser performs any final click; Accelerate never does.
+  if (value.final_click_actor !== undefined) {
+    check(value.final_click_actor === 'customer' && value.purpose === 'purchase', 'invalid_response');
+    result.final_click_actor = 'customer';
+  }
+  if (value.submit_actor !== undefined) {
+    check(value.submit_actor === 'customer' && value.final_click_actor === 'customer' && ['submit_attempted', 'outcome_unknown'].includes(value.status), 'invalid_response');
+    result.submit_actor = 'customer';
+  }
+  // An attested attempt names the customer; an unknown outcome cannot assert that a click happened.
+  if (value.status === 'submit_attempted' && value.purpose === 'purchase') check(value.submit_actor === 'customer', 'invalid_response');
+  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);
+  // A backend record: checked here so a reconciled checkout stays readable, and never projected to the agent.
+  if (value.reconciliation !== undefined) { try { validateCheckoutReconciliation(value.reconciliation, value.status); } catch { check(false, 'invalid_response'); } }
+  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') &&
+    (!enableSubmit || ['armFinalClick', 'completeFinalClick'].every(key => typeof client.checkouts[key] === 'function')) &&
+    // Purchases are never clicked by Accelerate or by Accelerate's private Kernel browser: only the customer's own browser host can click.
+    (purpose !== 'purchase' || browserMode === 'customer_backend_trusted' && ['prepareFinalClick', 'performFinalClick'].every(key => typeof browserConnector?.[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(purpose !== 'purchase' || checkout.final_click_actor === 'customer', 'invalid_response');
+    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,
+              ...(purpose === 'purchase' ? { final_click_actor: 'customer' } : {}),
+              ...(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' && typeof browserConnector?.performFinalClick === 'function' && typeof browserConnector.prepareFinalClick === 'function', 'permission_denied');
+              // prepare -> arm -> customer-owned host click -> complete, exactly once. The arm token and target stay in this scope.
+              // Slow provider/extension readiness runs BEFORE the arm so it cannot consume the short click window.
+              const preparation = await browserConnector.prepareFinalClick(context, { checkout_id: id }, options); requireAdmission();
+              let armed;
+              try { armed = await client.checkouts.armFinalClick(id, { revision: input.revision }, options); }
+              catch (error) {
+                // Only an explicit refusal proves nothing was armed. Transport, schema, timeout and upstream failures may have burned the arm.
+                if (error instanceof AccelerateError && PRE_ARM_REFUSALS.has(error.code)) throw error;
+                throw new AccelerateError('outcome_unknown');
+              }
+              try {
+                await browserConnector.performFinalClick(context, { checkout_id: id, preparation,
+                  checkout_url: armed.target.checkout_url, submit_selector: armed.target.submit_selector,
+                  armed_expires_at: armed.armed_expires_at }, options);
+              } catch { /* Host failure is not retried; the service observation below is the only truth. */ }
+              try { value = await client.checkouts.completeFinalClick(id, { revision: input.revision, arm_id: armed.arm_id }, options); }
+              catch { throw new AccelerateError('outcome_unknown'); }
+              // After a click attempt any unusable observation is an uncertain outcome, never a retryable failure.
+              try { requirePolicy(projectCheckout(value)); } catch { throw new AccelerateError('outcome_unknown'); }
+              check(['submit_attempted', 'outcome_unknown'].includes(value?.status) && value.final_click_actor === 'customer' &&
+                (value.status === 'outcome_unknown' || value.submit_actor === 'customer'), 'outcome_unknown');
+            }
+            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);
+}

package/package.json

@@ -1,6 +1,116 @@
 {
   "name": "@weaccelerateinc/agent-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.11.0",
+  "description": "Server-only payment SDK, existing-browser connectors and private host adapters for agent platforms",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "bin": {
+    "accelerate-agent": "./cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./browser-operations": {
+      "types": "./browser-operations.d.ts",
+      "import": "./browser-operations.js"
+    },
+    "./private-chat": {
+      "types": "./private-chat.d.ts",
+      "import": "./private-chat.js"
+    },
+    "./managed-mcp": {
+      "types": "./managed-mcp.d.ts",
+      "import": "./managed-mcp.js"
+    },
+    "./approved-extension": {
+      "types": "./approved-extension.d.ts",
+      "import": "./approved-extension.js"
+    },
+    "./browser-connector": {
+      "types": "./browser-connector.d.ts",
+      "import": "./browser-connector.js"
+    },
+    "./host-adapter": {
+      "types": "./host-adapter.d.ts",
+      "import": "./host-adapter.js"
+    },
+    "./postgres-host": {
+      "types": "./postgres-host.d.ts",
+      "import": "./postgres-host.js"
+    },
+    "./private-ingress": {
+      "types": "./private-ingress.d.ts",
+      "import": "./private-ingress.js"
+    },
+    "./linq-messaging": {
+      "types": "./linq-messaging.d.ts",
+      "import": "./linq-messaging.js"
+    },
+    "./partner": {
+      "types": "./partner.d.ts",
+      "import": "./partner.js"
+    },
+    "./approved-extension-releases/*": "./approved-extension-releases/*",
+    "./browser-use-host": {
+      "types": "./browser-use-host.d.ts",
+      "import": "./browser-use-host.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "browser-operations.js",
+    "browser-operations.d.ts",
+    "private-chat.js",
+    "private-chat.d.ts",
+    "cli.js",
+    "customer.env.example",
+    "README.md",
+    "managed-mcp.js",
+    "managed-mcp.d.ts",
+    "checkout-diagnostics.js",
+    "checkout-diagnostics.d.ts",
+    "starter",
+    "approved-extension.js",
+    "approved-extension.d.ts",
+    "browser-connector.js",
+    "browser-connector.d.ts",
+    "host-adapter.js",
+    "host-adapter.d.ts",
+    "postgres-host.js",
+    "postgres-host.d.ts",
+    "private-ingress.js",
+    "private-ingress.d.ts",
+    "linq-messaging.js",
+    "linq-messaging.d.ts",
+    "partner.js",
+    "partner.d.ts",
+    "approved-extension-releases",
+    "partner-starter",
+    "browser-use-host.js",
+    "browser-use-host.d.ts"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weaccelerateinc/accelerate.git",
+    "directory": "products/agent-sdk/packages/sdk"
+  },
+  "homepage": "https://github.com/weaccelerateinc/accelerate/tree/main/products/agent-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/weaccelerateinc/accelerate/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/partner-starter/.env.example

@@ -0,0 +1,13 @@
+# Synthetic mode makes no external requests and needs no credentials.
+ACCELERATE_STARTER_MODE=synthetic
+# Explicit new profile: private CVV continues the armed fill in the backend.
+ACCELERATE_CHECKOUT_PROFILE=managed_review_v2
+ACCELERATE_STARTER_PURPOSE=purchase
+ACCELERATE_ENABLE_PURCHASE_SUBMIT=true
+# For a fill-only test, set purpose to sandbox_fill_only and submit to false.
+# This file is a template; export values or load it with your server environment.
+# Live: operator-controlled absolute file exporting createPartnerDependencies().
+# ACCELERATE_CONTEXT_MODULE=/absolute/protected/partner-host.mjs
+# ACCELERATE_API_KEY=<tenant server key>
+# ACCELERATE_MERCHANT_ID=<provisioned merchant UUID>
+# ACCELERATE_BASE_URL=https://accelerate-agent-sdk.vercel.app