@weaccelerateinc/agent-sdk 0.0.0-stage → 0.10.3

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.10.3",
+  "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,11 @@
+# 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=sandbox_fill_only
+ACCELERATE_ENABLE_PURCHASE_SUBMIT=false
+# 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

package/partner-starter/README.md

@@ -0,0 +1,48 @@
+# Existing-browser payment starter
+
+SDK source 0.10.3, explicit `managed_review_v2`, `customer_backend_trusted`. The matching service must support this profile; source changes do not establish an archive publication or live deployment. Your platform creates its browser and installs the approved extension. This starter attaches that same browser at payment; it never creates a replacement. The older `accelerate-agent init <dir>` starter still selects Accelerate-managed Kernel custody.
+
+## Run without credentials
+
+Once Accelerate supplies the matching verified 0.10.3 archive, install it, then:
+
+```sh
+npx --no-install accelerate-agent init ./partner-demo --browser existing
+cd partner-demo
+npm install /secure/downloads/weaccelerateinc-agent-sdk-0.10.3.tgz
+npm test
+npm run smoke
+```
+
+The synthetic fixture uses the actual connector, durable-host interface, private ingress/outbox and MCP registration. It simulates verification/provider operations; no real browser, message, credential or order is created. Its in-memory persistence and fake extension metadata are test fixtures only.
+
+## Connect your platform
+
+Select `ACCELERATE_CHECKOUT_PROFILE=managed_review_v2` explicitly. This starter selects v2 by default; the reusable `registerPartnerCheckoutTools()` API retains `managed_review_v1` for existing callers unless they opt in. Set `ACCELERATE_CHECKOUT_PROFILE=managed_review_v1` only for that legacy manual-fill flow.
+
+Set `ACCELERATE_STARTER_MODE=live` and an operator-owned absolute `ACCELERATE_CONTEXT_MODULE` exporting `createPartnerDependencies({client,privateChat})`. Use `trusted-context.example.mjs` and the SDK TypeScript contracts. Required dependencies:
+
+- `resolveContext`: verify the customer/workspace/conversation/phone on every invocation.
+- `persistence`: durable cross-process lock and independently committed safe records. `@weaccelerateinc/agent-sdk/postgres-host` accepts your existing pg Pool and an independently managed 32-byte encryption key. Run its explicit `initialize()` migration during deployment.
+- `browserConnector`: `createBrowserUseConnector` with packaged `createBrowserUseHost` provider checks or a provisioned `createExistingBrowserConnector`; use your actual browser/document records, extension readiness, recording policy, durable drain/fence and independent cleanup proof.
+- `authenticate`: verify private raw webhook bytes and map to an established direct identity. Never derive authorization from tool arguments or a model transcript.
+- `messaging`: `PrivateMessagingAdapter` with provider-confirmed sent receipts. `@weaccelerateinc/agent-sdk/linq-messaging` supplies Linq/iMessage transport and an authenticator using your existing signature verifier.
+- `admitOrdinaryMessage`, `dispatchSafeProgress`: your durable deduplicated queues. Only fresh allowlisted safe events enter the model.
+
+`configureStarter` returns `privateIngress`. Mount `privateIngress.handle(request,rawBody)` BEFORE framework JSON parsing, logging, tracing, history and AI admission. It wipes the mutable input buffer. Do not keep another body copy. Call `privateIngress.drain(authenticatedContext)` from your existing durable event worker to recover safe prompt/image delivery. Never retry fill or submit there.
+
+The stdio launcher demonstrates tool registration only; it cannot host your application's webhook or authenticate arbitrary remote clients. Embed `configureStarter` in your authenticated server for live traffic.
+
+## Flow
+
+Shop normally in your browser, completing required non-secret contact/shipping and cardholder-name (`cc-name`) fields → reach payment → `accelerate_checkout_start` attaches/fences that browser → `accelerate_checkout_request_payment` starts private OTP/card selection → apply address → verify real total using `accelerate_checkout_request_approval` (private CVV under this profile) → successful private CVV immediately continues one armed fill in the backend → private masked PNG + final total → five-minute fresh yes/no decision → separately explicit agent submit → cleanup.
+
+At create, v2 declares `fill_after_verification:true` and requires the service to acknowledge capability before private OTP; this does not arm fill. Later, `accelerate_checkout_request_approval` sends `fill_after_verification:true` from the trusted SDK backend, bound to the actual quote and revision. The service must acknowledge that flag before requesting CVV. V2 exposes no `accelerate_checkout_fill` tool and never waits for a model roundtrip after private CVV. Status reads and outbox recovery cannot start another fill. Final approval and submission remain separate. Do not silently opt legacy checkouts into v2.
+
+Before attachment, use ordinary customer details for required non-secret fields or ask for missing details. Leave card number/PAN, expiry and CVV empty; never obtain them through ordinary browser tools.
+
+PAN displays stars + last four, CVV stars, expiry visible. Filled-page inspection is blocked for the agent. Provider-owner backend access remains trusted. The published release baseline qualifies `https://demos.weaccelerate.com/normal/payment`. The new universal-card source path probes compatible public HTTPS card forms instead of keeping a merchant hostname allowlist. It requires private `universal_card_v1` admission bound to the exact existing document and immutable purpose before OTP/CVV; ambiguous/unsupported forms fail without a replacement browser. That capability requires coordinated service/executor deployment and does not promise every checkout works. A candidate artifact or generic interface alone does not qualify a browser.
+
+The default is `sandbox_fill_only`, with no submit tool. After its informational image, call cancel and verify cleanup. Enable purchase only through explicit backend `purpose:'purchase'` and `enableSubmit:true` after qualification. Customer approval never automatically submits. Uncertain outcomes retain fences and require reconciliation; status/cleanup never authorize a replacement by themselves.
+
+Before live testing, confirm the session is executing the deployed v2 tool bundle. Updating a durable agent app does not necessarily replace an active session’s tools; settle its old work and use the framework’s supported idle deployment handoff or create a new authenticated session. Verify the quote response acknowledges `fill_after_verification:true`; a successful deployment alone is insufficient.

package/partner-starter/gitignore.template

@@ -0,0 +1,5 @@
+node_modules/
+.env
+.env.*
+!.env.example
+*.log

package/partner-starter/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "accelerate-existing-browser-starter",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "start": "node server.mjs",
+    "smoke": "node smoke.mjs",
+    "test": "node --test tests/*.test.mjs"
+  },
+  "dependencies": {
+    "@weaccelerateinc/agent-sdk": "0.10.3",
+    "@modelcontextprotocol/server": "2.3.1"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.3.1"
+  }
+}

package/partner-starter/runtime.mjs

@@ -0,0 +1,32 @@
+import { isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { AccelerateClient } from '@weaccelerateinc/agent-sdk';
+import { AcceleratePrivateChatClient } from '@weaccelerateinc/agent-sdk/private-chat';
+import { registerPartnerCheckoutTools } from '@weaccelerateinc/agent-sdk/partner';
+import { createSyntheticDependencies } from './synthetic.mjs';
+
+export async function configureStarter(server, env = process.env) {
+  const mode = env.ACCELERATE_STARTER_MODE ?? 'synthetic';
+  const profile = env.ACCELERATE_CHECKOUT_PROFILE ?? 'managed_review_v2';
+  if (!['managed_review_v1', 'managed_review_v2'].includes(profile)) throw Error('Unsupported partner checkout profile.');
+  const purpose = env.ACCELERATE_STARTER_PURPOSE ?? 'sandbox_fill_only';
+  const enableSubmit = env.ACCELERATE_ENABLE_PURCHASE_SUBMIT === 'true';
+  if (!['sandbox_fill_only', 'purchase'].includes(purpose) ||
+    env.ACCELERATE_ENABLE_PURCHASE_SUBMIT !== undefined && !['true', 'false'].includes(env.ACCELERATE_ENABLE_PURCHASE_SUBMIT) ||
+    enableSubmit && purpose !== 'purchase') throw Error('Unsupported server purchase policy.');
+  let dependencies;
+  if (mode === 'synthetic') dependencies = createSyntheticDependencies({ purpose, profile });
+  else if (mode === 'live') {
+    if (typeof env.ACCELERATE_CONTEXT_MODULE !== 'string' || !isAbsolute(env.ACCELERATE_CONTEXT_MODULE)) {
+      throw Error('A trusted absolute server context module is required.');
+    }
+    const module = await import(pathToFileURL(env.ACCELERATE_CONTEXT_MODULE).href);
+    if (typeof module.createPartnerDependencies !== 'function') throw Error('The trusted partner module is incomplete.');
+    const client = AccelerateClient.fromEnv(env), privateChat = AcceleratePrivateChatClient.fromEnv(env);
+    dependencies = { ...await module.createPartnerDependencies({ client, privateChat }), client, privateChat };
+  } else throw Error('Unsupported starter mode.');
+  const integration = registerPartnerCheckoutTools(server, { ...dependencies, profile, purpose, enableSubmit });
+  // Mount privateIngress.handle on the platform's AUTHENTICATED webhook before
+  // parsing/history/AI, and drain from its existing durable outbox worker.
+  return { mode, profile, ...integration, counters: dependencies.counters };
+}

package/partner-starter/server.mjs

@@ -0,0 +1,13 @@
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import { configureStarter } from './runtime.mjs';
+
+const server = new McpServer({ name: 'accelerate-partner-starter', version: '0.1.0' });
+try {
+  await configureStarter(server);
+  server.onerror = () => {}; // Never print protocol arguments or provider errors.
+  await server.connect(new StdioServerTransport());
+} catch {
+  process.stderr.write(JSON.stringify({ ok: false, code: 'starter_configuration_unavailable' }) + '\n');
+  process.exitCode = 1;
+}

package/partner-starter/smoke.mjs

@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict';
+import { fileURLToPath } from 'node:url';
+import { Client } from '@modelcontextprotocol/client';
+import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/client/stdio';
+
+const client = new Client({ name: 'accelerate-starter-smoke', version: '0.1.0' });
+const transport = new StdioClientTransport({ command: process.execPath,
+  args: [fileURLToPath(new URL('./server.mjs', import.meta.url))],
+  env: { ...getDefaultEnvironment(), ACCELERATE_STARTER_MODE: 'synthetic', ACCELERATE_CHECKOUT_PROFILE: 'managed_review_v2' }, stderr: 'pipe' });
+let complete = false;
+const timer = setTimeout(() => { void transport.close(); }, 15000);
+try {
+  await client.connect(transport);
+  const tools = await client.listTools();
+  assert.equal(tools.tools.length, 7);
+  assert.equal(tools.tools.some(tool => tool.name === 'accelerate_checkout_request_payment'), true);
+  assert.equal(tools.tools.some(tool => tool.name === 'accelerate_checkout_submit'), false);
+  assert.equal(tools.tools.some(tool => tool.name === 'accelerate_checkout_fill'), false);
+  const call = async (name, args) => {
+    const result = await client.callTool({ name, arguments: args });
+    const value = result.structuredContent ?? JSON.parse(result.content.find(part => part.type === 'text').text);
+    assert.equal(value.ok, true); return value;
+  };
+  const checkoutUrl = 'https://demos.weaccelerate.com/normal/payment';
+  const checkout = (await call('accelerate_checkout_start', { start_url: checkoutUrl })).checkout;
+  assert.equal(checkout.purpose, 'sandbox_fill_only'); assert.equal(checkout.submit_allowed, false);
+  assert.equal(checkout.approval_policy, 'after_fill'); assert.equal(checkout.purchase_approved, false);
+  assert.equal(checkout.status, 'wallet_required'); assert.equal(checkout.card, undefined);
+  const id = checkout.id;
+  assert.equal((await call('accelerate_checkout_status', { checkout_id: id })).checkout.status, 'wallet_required');
+  await call('accelerate_checkout_browser', { checkout_id: id, operation: 'browser_snapshot', arguments: { filter: 'all' } });
+  assert.equal((await call('accelerate_checkout_status', { checkout_id: id })).checkout.status, 'wallet_required');
+  const requested = await call('accelerate_checkout_request_payment', { checkout_id: id });
+  assert.equal(requested.checkout.status, 'wallet_required');
+  assert.equal((await call('accelerate_checkout_status', { checkout_id: id })).checkout.status, 'selection_ready');
+  await call('accelerate_checkout_apply_details', { checkout_id: id, checkout_url: checkoutUrl });
+  const quote = (await call('accelerate_checkout_request_approval', { checkout_id: id, checkout_url: checkoutUrl,
+    amount_cents: 100, currency: 'USD', checkout_total_selector: '#checkout-total', submit_selector: '#place-order' })).checkout;
+  assert.equal(quote.fill_after_verification, true);
+  assert.equal((await call('accelerate_checkout_status', { checkout_id: id })).checkout.status, 'ready_for_submit');
+  const reviewed = (await call('accelerate_checkout_status', { checkout_id: id })).checkout;
+  assert.equal(reviewed.purchase_approved, false);
+  const remaining = Date.parse(reviewed.submit_expires_at) - Date.now();
+  assert.ok(remaining > 290000 && remaining <= 300000);
+  assert.equal((await call('accelerate_checkout_cancel', { checkout_id: id })).checkout.status, 'cancelled');
+  complete = true;
+  process.stdout.write(JSON.stringify({ ok: true, synthetic_only: true, mcp_protocol: true,
+    profile: 'managed_review_v2', existing_browser_connector: true, browser_mode: 'customer_backend_trusted', verification_deferred: true, private_verification_before_fill: true,
+    private_review_receipt_acknowledged: true, approval_window_ms: 300000, purchase_approval_requested: false,
+    submit_tool_absent: true, manual_fill_tool_absent: true, fill_ready: true, cancelled: true, live_checkout_requests: 0 }) + '\n');
+} catch {
+  process.stderr.write(JSON.stringify({ ok: false, code: 'synthetic_smoke_failed' }) + '\n');
+} finally {
+  clearTimeout(timer); await client.close().catch(() => {}); await transport.close().catch(() => {});
+  process.exitCode = complete ? 0 : 1;
+}

package/partner-starter/synthetic.mjs

@@ -0,0 +1,226 @@
+import { createHash } from 'node:crypto';
+import { createExistingBrowserConnector } from '@weaccelerateinc/agent-sdk/browser-connector';
+import { AccelerateClient } from '@weaccelerateinc/agent-sdk';
+import { AcceleratePrivateChatClient, deliverPrivateCheckoutReview } from '@weaccelerateinc/agent-sdk/private-chat';
+
+const context = Object.freeze({ customer_id: 'synthetic-customer', workspace_id: 'synthetic-workspace',
+  conversation_id: 'synthetic-direct-conversation', phone_number: '+15555550123' });
+const origin = 'https://synthetic.accelerate.invalid';
+export const syntheticCheckoutUrl = 'https://demos.weaccelerate.com/normal/payment';
+const invalid = () => { throw Error('Synthetic checkout request rejected.'); };
+const digest = value => createHash('sha256').update(value).digest('base64url');
+const png = () => Buffer.from([137, 80, 78, 71, 13, 10, 26, 10, 1, 2, 3]);
+
+/** In-process fixtures only: no network, source, browser, raw OTP or security code.
+ * Private verification is simulated; safe image delivery uses the real SDK. */
+function createSyntheticHost({ purpose = 'sandbox_fill_only', profile = 'managed_review_v1', deliverReview } = {}) {
+  if (!['sandbox_fill_only', 'purchase'].includes(purpose) || !['managed_review_v1', 'managed_review_v2'].includes(profile)) invalid();
+  const records = new Map(), owners = new Map(), events = new Set(), messages = new Map();
+  const calls = { create: 0, browser: 0, payment_requested: 0, approval_requested: 0,
+    private_verification: 0, fill: 0, review: 0, review_sent: 0, review_acknowledged: 0,
+    purchase_decision: 0, submit: 0, cancel: 0, external: 0 };
+  let tail = Promise.resolve();
+  const locked = async work => {
+    const previous = tail; let release;
+    tail = new Promise(resolve => { release = resolve; }); await previous;
+    try { return await work(); } finally { release(); }
+  };
+  const view = record => ({ id: record.id, status: record.status, revision: record.revision,
+    expires_at: record.expires_at, purpose, submit_allowed: purpose === 'purchase',
+    approval_policy: 'after_fill', purchase_approved: record.purchaseApproved === true,
+    retry_safe: false, payment_confirmed: false,
+    ...(record.fillAfterVerificationProfile ? { fill_after_verification: true } : {}),
+    ...(record.selected ? { card: { brand: 'Visa', last4: '4242' }, address: { label: 'Saved address ***23' } } : {}),
+    ...(record.quote ? { quote: record.quote } : {}),
+    ...(record.review ? { submit_expires_at: record.review.expires_at } : {}),
+    ...(record.status === 'cancelled' ? { diagnostics: { version: 'v1', stage: 'cancelled', next_actions: ['get_status'], support_reference: 'acs_' + 'a'.repeat(32), cleanup_status: 'confirmed' } } : {}) });
+  const privateView = record => ({ checkout: view(record), stage: record.stage, handled: true, duplicate: false,
+    cards: [], addresses: [],
+    ...(['cvv_required', 'review_delivery_required', 'review_delivered', 'approval_required', 'approved_for_submit'].includes(record.stage)
+      ? { approval: { revision: record.revision, ...record.quote } } : {}),
+    ...(record.review ? { review: { ...record.review } } : {}) });
+  const fill = record => {
+    if (record.status !== 'approved') invalid();
+    calls.fill++; record.status = 'ready_for_submit'; record.stage = 'review_delivery_required';
+    record.review = { id: 'rvr_' + digest(record.id + ':' + record.revision), delivered: false, approval_window_ms: 300000,
+      expires_at: new Date(Date.now() + 420000).toISOString(), delivery_expires_at: new Date(Date.now() + 60000).toISOString() };
+  };
+  const verify = record => {
+    calls.approval_requested++; calls.private_verification++; record.status = 'approved'; record.stage = 'verified';
+    if (record.fillAfterVerification) fill(record);
+  };
+  const fetchImpl = async (url, request) => {
+    const parsed = new URL(url);
+    if (parsed.origin !== origin) { calls.external++; invalid(); }
+    const body = request.body ? JSON.parse(request.body) : undefined;
+    if (parsed.pathname === '/v1/checkouts' && request.method === 'POST') {
+      if (body.interaction_mode !== 'chat' || body.purpose !== purpose || body.approval_policy !== 'after_fill' ||
+        Object.keys(context).some(key => body[key] !== context[key]) || body.start_url !== syntheticCheckoutUrl ||
+        JSON.stringify(body.browser) !== JSON.stringify({ provider: 'connector', connector_id: 'synthetic_cdp', browser_id: 'existing:browser:1', custody_mode: 'customer_backend_trusted' })) invalid();
+      if ((profile === 'managed_review_v2') !== (body.fill_after_verification === true)) invalid();
+      const id = 'mcs_' + digest(body.idempotency_key);
+      if (!records.has(id)) { calls.create++; records.set(id, { id, status: 'wallet_required', stage: 'not_started', revision: 0,
+        expires_at: new Date(Date.now() + 900000).toISOString(), selected: false, fillAfterVerificationProfile: body.fill_after_verification === true }); }
+      return Response.json(view(records.get(id)), { status: 201 });
+    }
+    const match = /^\/v1\/checkouts\/(mcs_[A-Za-z0-9_-]{43})(?:\/(browser|details|approval|fill|submit|cancel|private-chat\/(?:start|state|review|review-delivered|reply)))?$/.exec(parsed.pathname);
+    if (!match || !records.has(match[1])) invalid();
+    const record = records.get(match[1]), action = match[2];
+    if (!action && request.method === 'GET') return Response.json(view(record));
+    if (request.method !== 'POST') invalid();
+    if (action?.startsWith('private-chat/')) {
+      if (['customer_id', 'workspace_id', 'conversation_id'].some(key => body[key] !== context[key])) invalid();
+      if (action === 'private-chat/start') {
+        if (record.stage === 'not_started') { calls.payment_requested++; record.selected = true; record.status = 'selection_ready'; record.stage = 'preparing_checkout'; record.revision = 1; }
+        return Response.json(privateView(record));
+      }
+      if (action === 'private-chat/state') {
+        if (record.stage === 'cvv_required') verify(record);
+        return Response.json(privateView(record));
+      }
+      if (action === 'private-chat/review' && record.stage === 'review_delivery_required' && Date.now() < Date.parse(record.review.delivery_expires_at)) {
+        calls.review++; record.imageRetrieved = true;
+        return new Response(png(), { headers: { 'Content-Type': 'image/png',
+          'X-Accelerate-Review-Id': record.review.id, 'X-Accelerate-Review-Expires-At': record.review.expires_at,
+          'X-Accelerate-Review-Amount-Cents': String(record.quote.amount_cents), 'X-Accelerate-Review-Currency': 'USD',
+          'X-Accelerate-Review-Approval-Window-Ms': '300000', 'X-Accelerate-Review-Delivery-Expires-At': record.review.delivery_expires_at } });
+      }
+      if (action === 'private-chat/review-delivered') {
+        const receipt = messages.get(body.message_id);
+        if (!record.imageRetrieved || body.review_id !== record.review?.id || !receipt || receipt.checkout !== record.id ||
+          receipt.sent_at !== body.sent_at || Date.parse(body.sent_at) > Date.now() ||
+          Date.parse(body.sent_at) >= Date.parse(record.review.delivery_expires_at)) invalid();
+        if (!record.review.delivered) { calls.review_acknowledged++; record.review.delivered = true;
+          record.review.expires_at = new Date(Date.parse(body.sent_at) + 300000).toISOString();
+          record.stage = purpose === 'purchase' ? 'approval_required' : 'review_delivered'; }
+        return Response.json(privateView(record));
+      }
+      if (action === 'private-chat/reply' && purpose === 'purchase' && record.stage === 'approval_required' &&
+        record.review?.delivered && typeof body.sent_at === 'string' && Date.parse(body.sent_at) <= Date.now() &&
+        Date.parse(body.sent_at) > Date.parse(record.review.expires_at) - 300000 && Date.now() < Date.parse(record.review.expires_at)) {
+        if (!['approve', 'decline'].includes(body.text)) invalid();
+        calls.purchase_decision++;
+        if (body.text === 'approve') { record.purchaseApproved = true; record.stage = 'approved_for_submit'; }
+        else { record.status = 'cancelled'; record.stage = 'closed'; delete record.review; }
+        return Response.json(privateView(record));
+      }
+      invalid();
+    }
+    if (action === 'browser' && ['wallet_required', 'selection_ready', 'details_ready'].includes(record.status)) {
+      calls.browser++;
+      return Response.json({ content: [{ type: 'text',
+        text: 'Synthetic demo checkout\nUSD $1.00\n#checkout-total\n#place-order\n[e1_1] Button Continue' }] });
+    }
+    if (action === 'details' && record.status === 'selection_ready' && body.checkout_url === syntheticCheckoutUrl) record.status = 'details_ready';
+    else if (action === 'approval' && record.status === 'details_ready' && body.checkout_url === syntheticCheckoutUrl &&
+      body.amount_cents === 100 && body.currency === 'USD') {
+      if ((profile === 'managed_review_v2') !== (body.fill_after_verification === true)) invalid();
+      record.fillAfterVerification = body.fill_after_verification === true;
+      record.status = 'approval_required'; record.stage = 'cvv_required'; record.revision++;
+      record.quote = { checkout_origin: 'https://demos.weaccelerate.com', amount_cents: 100, currency: 'USD' };
+    } else if (action === 'fill' && record.status === 'approved' && body.revision === record.revision) {
+      if (record.fillAfterVerification) invalid();
+      fill(record);
+    } else if (action === 'cancel') { calls.cancel++; record.status = 'cancelled'; record.stage = 'closed'; record.purchaseApproved = false; delete record.review; }
+    else if (action === 'submit') {
+      calls.submit++;
+      if (purpose !== 'purchase' || !record.purchaseApproved || record.stage !== 'approved_for_submit' ||
+        body.revision !== record.revision || Date.now() >= Date.parse(record.review.expires_at)) return Response.json({ error: { code: 'submit_unavailable' } }, { status: 409 });
+      record.status = 'submit_attempted'; record.stage = 'closed'; record.purchaseApproved = false; delete record.review;
+    } else invalid();
+    return Response.json(view(record));
+  };
+  const options = { baseUrl: origin, apiKey: 'synthetic_tenant_not_a_real_key'.padEnd(48, 'x'),
+    merchantId: 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee', fetchImpl };
+  const client = new AccelerateClient(options), privateChat = new AcceleratePrivateChatClient(options);
+  const host = { client, privateChat,
+    resolveContext: async () => ({ ...context }),
+    withOwnedCheckout: async (current, id, work) => locked(async () => {
+      const saved = owners.get(id);
+      if (!saved || Object.keys(context).some(key => current[key] !== context[key] || saved[key] !== current[key])) invalid();
+      return work({ ...saved });
+    }),
+    withCheckoutCreation: async (current, work) => locked(() => {
+      if (Object.keys(context).some(key => current[key] !== context[key])) invalid();
+      return work({ idempotency_key: 'synthetic-exact-attempt-1', persistCreated: async saved => {
+        if (Object.keys(context).some(key => saved[key] !== context[key])) invalid();
+        owners.set(saved.checkout_id, { ...saved });
+      } });
+    }),
+    sendPrivateReview: async (current, message) => {
+      if (Object.keys(context).some(key => current[key] !== context[key]) || message.contentType !== 'image/png' ||
+        !message.bytes.equals(png()) || message.signal.aborted || Date.now() >= Date.parse(message.delivery_expires_at)) invalid();
+      const record = [...records.values()].find(value => value.stage === 'review_delivery_required');
+      if (!record || !message.text.includes('1.00 USD') || (purpose === 'sandbox_fill_only'
+        ? !message.text.includes('No purchase approval is needed') || message.text.includes('Do you approve')
+        : !message.text.includes('5 minutes from this message'))) invalid();
+      const message_id = 'synthetic-review-' + digest(message.idempotency_key);
+      if (!messages.has(message_id)) { calls.review_sent++; messages.set(message_id, { checkout: record.id, sent_at: new Date(Date.now()).toISOString() }); }
+      return { message_id, sent_at: messages.get(message_id).sent_at };
+    },
+    dispatchCheckoutEvent: async (current, event) => {
+      if (Object.keys(context).some(key => current[key] !== context[key]) ||
+        event.version !== 'v1' || !['payment_requested', 'approval_requested', 'review_ready'].includes(event.kind) ||
+        event.idempotency_key !== 'accelerate-checkout-event:' + createHash('sha256').update(JSON.stringify([
+          'v1', event.kind, event.checkout.id, ['approval_requested', 'review_ready'].includes(event.kind) ? event.checkout.revision : 0])).digest('hex') ||
+        !owners.has(event.checkout.id)) invalid();
+      if (events.has(event.idempotency_key)) return;
+      const record = records.get(event.checkout.id);
+      if (event.kind === 'payment_requested' && record.status === 'wallet_required') {
+        calls.payment_requested++; record.selected = true; record.status = 'selection_ready'; record.stage = 'preparing_checkout'; record.revision = 1;
+      } else if (event.kind === 'approval_requested' && record.stage === 'cvv_required') {
+        verify(record);
+      } else if (event.kind === 'review_ready' && record.stage === 'review_delivery_required') {
+        if (deliverReview) await deliverReview(current, event);
+        else await deliverPrivateCheckoutReview({ client: privateChat, state: privateView(record),
+          binding: Object.fromEntries(['customer_id', 'workspace_id', 'conversation_id'].map(key => [key, context[key]])),
+          messageId: event.idempotency_key, send: message => host.sendPrivateReview(current, message) });
+      } else invalid();
+      // Only receipt acknowledgement completes this event; a failure retains
+      // this exact event for redelivery, without replaying private filling.
+      events.add(event.idempotency_key);
+    },
+    counters: () => ({ ...calls }),
+  };
+  return host;
+}
+
+/** Synthetic-only host dependencies. This memory store is deliberately not
+ * exported as a production persistence adapter. No browser/provider is created. */
+export function createSyntheticDependencies({ purpose = 'sandbox_fill_only', profile = 'managed_review_v1' } = {}) {
+  const fixture = createSyntheticHost({ purpose, profile }); let record, tail = Promise.resolve(), fenced = false;
+  const saved = new Map();
+  const persistence = { async withLock(_key, work) {
+    const previous = tail; let release; tail = new Promise(resolve => { release = resolve; }); await previous;
+    try { return await work({ load: async () => record && structuredClone(record), commit: async value => { record = structuredClone(value); } }); }
+    finally { release(); }
+  } };
+  const extensionRelease = {
+    schema_version: 1, release_id: 'accelerate-extension-0.0.0.2', status: 'approved', extension_version: '0.0.0.2',
+    artifact: { format: 'zip', sha256: 'a'.repeat(64), bytes: 1234 },
+    bridge: { protocol: 'accelerate_extension_bridge_v1', sha256: 'b'.repeat(64) },
+    capabilities: { manual_card_fill: true, document_bound_single_use: true, autosave_disabled: true, automatic_submit: false, maximum_retention_ms: 480000 },
+    compatibility: { sdk_versions: ['0.10.1', '0.10.2', '0.10.3'], executor_contract: 'accelerate_manual_checkout_v1' },
+    qualifications: [{ provider: 'connector', scope: 'synthetic_only', evidence: 'docs/evidence/synthetic-starter.json' }],
+  }; // Fake metadata for this in-process fixture only; never load it in live mode.
+  const browser = { owner: context, browser: { provider: 'connector', connector_id: 'synthetic_cdp', browser_id: 'existing:browser:1', custody_mode: 'customer_backend_trusted' },
+    document_id: 'existing:document:1', checkout_url: syntheticCheckoutUrl, expires_at: new Date(Date.now() + 1800000).toISOString() };
+  const browserConnector = createExistingBrowserConnector({ connectorId: 'synthetic_cdp', extensionRelease, host: {
+    resolveOwnedBrowser: async () => structuredClone(browser),
+    inspectBrowser: async () => ({ ...structuredClone(browser), recording_disabled: true,
+      extension: { success: true, initialized: true, wasmInitialized: true, autosaveDisabled: true, boundedRetentionSupported: true, maximumRetentionMs: 480000,
+        extension_version: '0.0.0.2', artifact_sha256: 'a'.repeat(64), bridge_protocol: 'accelerate_extension_bridge_v1' },
+      automation: { ordinary_operations_drained: fenced, agent_access_fenced: fenced, fence_id: fenced ? 'synthetic:fence:1' : null } }),
+    drainAndFence: async () => { fenced = true; return { ordinary_operations_drained: true, agent_access_fenced: true, fence_id: 'synthetic:fence:1' }; },
+    bindCheckout: async (_context, value) => { saved.set(value.checkout_id, value); },
+    resolveCheckoutBrowser: async (_context, { checkout_id }) => { const { checkout_id: _id, attempt_key: _key, ...value } = saved.get(checkout_id); return value; },
+    confirmCleanup: async () => ({ provider_browser_stopped: true, credentials_cleared: true, fence_retained: true }),
+  } });
+  return { client: fixture.client, privateChat: fixture.privateChat, resolveContext: fixture.resolveContext,
+    persistence, browserConnector,
+    authenticate: async () => { throw Error('Synthetic mode has no public webhook.'); },
+    messaging: { sendText: async () => ({ message_id: 'synthetic-private-prompt', sent_at: new Date().toISOString() }), sendReview: fixture.sendPrivateReview },
+    admitOrdinaryMessage: async () => { throw Error('Synthetic mode has no AI ingress.'); },
+    dispatchSafeProgress: async () => {}, counters: fixture.counters, record: () => structuredClone(record),
+  };
+}

package/partner-starter/tests/starter.test.mjs

@@ -0,0 +1,69 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { configureStarter } from '../runtime.mjs';
+import { syntheticCheckoutUrl } from '../synthetic.mjs';
+async function fixture(env = {}) {
+  const tools = new Map(); const integration = await configureStarter({ registerTool(name, _config, callback) { tools.set(name, callback); } }, env);
+  const call = async (name, args) => { const result = (await tools.get(name)(args, {})).structuredContent; assert.equal(result.ok, true, JSON.stringify(result)); return result; };
+  return { ...integration, tools, call };
+}
+test('explicit v2 starter verifies privately then fills and acknowledges review without a model fill tool', async t => {
+  const old = globalThis.fetch; globalThis.fetch = () => assert.fail('No network in synthetic starter'); t.after(() => { globalThis.fetch = old; });
+  const f = await fixture(), checkout = (await f.call('accelerate_checkout_start', { start_url: syntheticCheckoutUrl })).checkout;
+  const id = checkout.id; assert.equal(checkout.fill_after_verification, true); assert.equal(f.counters().fill, 0); assert.equal(checkout.status, 'wallet_required'); assert.equal(f.counters().payment_requested, 0);
+  assert.equal(f.tools.has('accelerate_checkout_submit'), false); assert.equal(f.tools.size, 7); assert.equal(f.tools.has('accelerate_checkout_fill'), false);
+  assert.equal(f.profile, 'managed_review_v2');
+  await f.call('accelerate_checkout_request_payment', { checkout_id: id });
+  assert.equal((await f.call('accelerate_checkout_status', { checkout_id: id })).checkout.status, 'selection_ready');
+  await f.call('accelerate_checkout_apply_details', { checkout_id: id, checkout_url: syntheticCheckoutUrl });
+  const quote = (await f.call('accelerate_checkout_request_approval', { checkout_id: id, checkout_url: syntheticCheckoutUrl, amount_cents: 100, currency: 'USD', checkout_total_selector: '#checkout-total', submit_selector: '#place-order' })).checkout;
+  assert.equal(quote.fill_after_verification, true);
+  assert.equal((await f.call('accelerate_checkout_status', { checkout_id: id })).checkout.status, 'ready_for_submit');
+  assert.equal(f.counters().fill, 1); assert.equal(f.counters().review_sent, 1); assert.equal(f.counters().review_acknowledged, 1);
+  // Safe state reads recover delivery only; they cannot replay the armed fill.
+  await f.call('accelerate_checkout_status', { checkout_id: id });
+  assert.equal(f.counters().fill, 1); assert.equal(f.counters().private_verification, 1);
+  assert.equal(f.counters().purchase_decision, 0);
+  await f.call('accelerate_checkout_cancel', { checkout_id: id });
+  assert.equal(f.counters().submit, 0); assert.equal(f.counters().cancel, 1); assert.equal(f.counters().external, 0);
+});
+test('legacy v1 remains an explicit starter profile with one manual fill and no silent upgrade', async () => {
+  const f = await fixture({ ACCELERATE_CHECKOUT_PROFILE: 'managed_review_v1' });
+  assert.equal(f.tools.has('accelerate_checkout_fill'), true); assert.equal(f.tools.size, 8);
+  const id = (await f.call('accelerate_checkout_start', { start_url: syntheticCheckoutUrl })).checkout.id;
+  await f.call('accelerate_checkout_request_payment', { checkout_id: id });
+  await f.call('accelerate_checkout_apply_details', { checkout_id: id, checkout_url: syntheticCheckoutUrl });
+  const quote = (await f.call('accelerate_checkout_request_approval', { checkout_id: id, checkout_url: syntheticCheckoutUrl, amount_cents: 100, currency: 'USD', checkout_total_selector: '#checkout-total', submit_selector: '#place-order' })).checkout;
+  assert.equal(quote.fill_after_verification, undefined);
+  assert.equal((await f.call('accelerate_checkout_status', { checkout_id: id })).checkout.status, 'approved');
+  assert.equal(f.counters().fill, 0);
+  await f.call('accelerate_checkout_fill', { checkout_id: id, revision: quote.revision });
+  const repeated = (await f.tools.get('accelerate_checkout_fill')({ checkout_id: id, revision: quote.revision }, {})).structuredContent;
+  assert.equal(repeated.ok, false); assert.equal(f.counters().fill, 1);
+  assert.equal(f.counters().review_acknowledged, 1); assert.equal(f.counters().submit, 0);
+  await f.call('accelerate_checkout_cancel', { checkout_id: id });
+});
+test('v2 purchase still requires a fresh private decision and explicit submit after automatic fill', async () => {
+  const f = await fixture({ ACCELERATE_STARTER_PURPOSE: 'purchase', ACCELERATE_ENABLE_PURCHASE_SUBMIT: 'true' });
+  assert.equal(f.tools.has('accelerate_checkout_fill'), false); assert.equal(f.tools.has('accelerate_checkout_submit'), true);
+  const id = (await f.call('accelerate_checkout_start', { start_url: syntheticCheckoutUrl })).checkout.id;
+  await f.call('accelerate_checkout_request_payment', { checkout_id: id });
+  assert.equal(f.counters().fill, 0);
+  await f.call('accelerate_checkout_apply_details', { checkout_id: id, checkout_url: syntheticCheckoutUrl });
+  const quote = (await f.call('accelerate_checkout_request_approval', { checkout_id: id, checkout_url: syntheticCheckoutUrl, amount_cents: 100, currency: 'USD', checkout_total_selector: '#checkout-total', submit_selector: '#place-order' })).checkout;
+  const current = (await f.call('accelerate_checkout_status', { checkout_id: id })).checkout;
+  assert.equal(current.status, 'ready_for_submit'); assert.equal(current.purchase_approved, false);
+  const remaining = Date.parse(current.submit_expires_at) - Date.now();
+  assert.ok(remaining > 290000 && remaining <= 300000);
+  assert.equal(f.counters().fill, 1); assert.equal(f.counters().review_acknowledged, 1);
+  assert.equal(f.counters().submit, 0); assert.equal(f.counters().purchase_decision, 0);
+  const rejected = (await f.tools.get('accelerate_checkout_submit')({ checkout_id: id, revision: quote.revision }, {})).structuredContent;
+  assert.equal(rejected.ok, false); assert.equal(f.counters().submit, 0);
+  await f.call('accelerate_checkout_cancel', { checkout_id: id });
+});
+test('live setup requires a trusted backend module and preserves explicit custody selection', async () => {
+  await assert.rejects(configureStarter({ registerTool() {} }, { ACCELERATE_STARTER_MODE: 'live' }), /trusted absolute/);
+  await assert.rejects(configureStarter({ registerTool() {} }, { ACCELERATE_STARTER_MODE: 'unknown' }), /Unsupported/);
+  await assert.rejects(configureStarter({ registerTool() {} }, { ACCELERATE_CHECKOUT_PROFILE: 'unknown' }), /profile/);
+  await assert.rejects(configureStarter({ registerTool() {} }, { ACCELERATE_ENABLE_PURCHASE_SUBMIT: 'true' }), /purchase policy/);
+});