@weaccelerateinc/agent-sdk 0.0.0-stage → 0.10.3

package/starter/tests/starter.test.mjs

@@ -0,0 +1,256 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { mkdtemp, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createSyntheticHost, syntheticCheckoutUrl } from '../synthetic.mjs';
+import { configureStarter } from '../runtime.mjs';
+
+const event = (kind, checkout) => ({ version: 'v1', kind, checkout,
+  idempotency_key: 'accelerate-checkout-event:' + createHash('sha256')
+    .update(JSON.stringify(['v1', kind, checkout.id, ['approval_requested', 'review_ready'].includes(kind) ? checkout.revision : 0])).digest('hex') });
+async function prepared(purpose = 'sandbox_fill_only') {
+  const host = createSyntheticHost({ purpose }), context = await host.resolveContext();
+  const checkout = await host.withCheckoutCreation(context, async creation => {
+    const value = await host.client.checkouts.create({ ...context, start_url: syntheticCheckoutUrl,
+      idempotency_key: creation.idempotency_key, interaction_mode: 'chat', purpose, approval_policy: 'after_fill' });
+    await creation.persistCreated({ checkout_id: value.id, ...context }); return value;
+  });
+  const dispatch = (kind, value) => host.dispatchCheckoutEvent(context, event(kind, value));
+  const binding = Object.fromEntries(['customer_id', 'workspace_id', 'conversation_id'].map(key => [key, context[key]]));
+  const reachFill = async () => {
+    await dispatch('payment_requested', checkout);
+    await host.client.checkouts.applyDetails(checkout.id, { checkout_url: syntheticCheckoutUrl });
+    const quote = await host.client.checkouts.requestApproval(checkout.id, { checkout_url: syntheticCheckoutUrl,
+      amount_cents: 100, currency: 'USD', checkout_total_selector: '#checkout-total', submit_selector: '#place-order' });
+    await dispatch('approval_requested', quote);
+    return host.client.checkouts.fill(checkout.id, { revision: quote.revision });
+  };
+  return { host, context, checkout, dispatch, binding, reachFill };
+}
+
+test('default demo defers verification, verifies privately, fills, acknowledges safe review and cancels without approval or network', async t => {
+  const previous = globalThis.fetch; globalThis.fetch = () => assert.fail('Synthetic mode cannot use external fetch.');
+  t.after(() => { globalThis.fetch = previous; });
+  const { host, context, checkout, dispatch, binding, reachFill } = await prepared();
+  assert.equal(checkout.approval_policy, 'after_fill'); assert.equal(checkout.purchase_approved, false);
+  assert.equal(checkout.submit_allowed, false); assert.equal(checkout.status, 'wallet_required'); assert.equal(checkout.card, undefined);
+  await host.client.checkouts.browser(checkout.id, { operation: 'browser_snapshot', arguments: { filter: 'all' } });
+  assert.equal((await host.client.checkouts.get(checkout.id)).status, 'wallet_required');
+  assert.equal(host.counters().payment_requested, 0); assert.equal(host.counters().private_verification, 0);
+  await assert.rejects(dispatch('created', checkout));
+  await assert.rejects(host.dispatchCheckoutEvent(context, { ...event('payment_requested', checkout), idempotency_key: 'invalid' }));
+  const filled = await reachFill();
+  assert.equal(filled.status, 'ready_for_submit'); assert.equal(filled.purchase_approved, false);
+  assert.equal((await host.privateChat.chat.get(checkout.id, binding)).stage, 'review_delivery_required');
+  assert.equal(host.counters().review_acknowledged, 0);
+  await dispatch('review_ready', filled); await dispatch('review_ready', filled);
+  const reviewed = await host.privateChat.chat.get(checkout.id, binding);
+  assert.equal(reviewed.stage, 'review_delivered'); assert.equal(reviewed.review.approval_window_ms, 300000);
+  assert.ok(Date.parse(reviewed.review.expires_at) - Date.now() > 299000);
+  await assert.rejects(host.privateChat.chat.reply(checkout.id, { ...binding, message_id: 'no-approval-for-fill-only',
+    text: 'approve', sent_at: new Date().toISOString() }));
+  assert.equal(host.counters().purchase_decision, 0); assert.equal(host.counters().submit, 0);
+  assert.equal((await host.client.checkouts.cancel(checkout.id)).status, 'cancelled');
+  assert.deepEqual(host.counters(), { create: 1, browser: 1, payment_requested: 1, approval_requested: 1,
+    private_verification: 1, fill: 1, review: 1, review_sent: 1, review_acknowledged: 1,
+    purchase_decision: 0, submit: 0, cancel: 1, external: 0 });
+  await assert.rejects(host.withOwnedCheckout({ ...context, customer_id: 'another-customer' }, checkout.id, () => assert.fail('Wrong owner admitted.')));
+});
+
+test('review delivery failure retains the same event and retries image delivery without replaying fill', async () => {
+  const { host, checkout, dispatch, binding, reachFill } = await prepared();
+  const filled = await reachFill(), send = host.sendPrivateReview;
+  let borrowed;
+  host.sendPrivateReview = async (_context, message) => { borrowed = message.bytes; throw Error('SYNTHETIC_QUEUED_ONLY'); };
+  await assert.rejects(dispatch('review_ready', filled));
+  assert.ok(borrowed.every(byte => byte === 0));
+  assert.equal((await host.privateChat.chat.get(checkout.id, binding)).stage, 'review_delivery_required');
+  assert.equal(host.counters().review_acknowledged, 0); assert.equal(host.counters().fill, 1);
+  host.sendPrivateReview = send; await dispatch('review_ready', filled);
+  assert.equal(host.counters().review_acknowledged, 1); assert.equal(host.counters().fill, 1);
+  assert.equal(host.counters().submit, 0);
+});
+
+test('purchase profile waits the full five-minute receipt-bound window and requires a distinct final submit', async t => {
+  const originalNow = Date.now; let now = originalNow(); Date.now = () => now;
+  t.after(() => { Date.now = originalNow; });
+  const { host, checkout, dispatch, binding, reachFill } = await prepared('purchase');
+  const filled = await reachFill();
+  await assert.rejects(host.privateChat.chat.reply(checkout.id, { ...binding, message_id: 'too-early', text: 'approve', sent_at: new Date(now).toISOString() }));
+  await assert.rejects(host.client.checkouts.submit(checkout.id, { revision: filled.revision }), { code: 'submit_unavailable' });
+  now += 45000; await dispatch('review_ready', filled);
+  const reviewed = await host.privateChat.chat.get(checkout.id, binding);
+  assert.equal(reviewed.stage, 'approval_required'); assert.equal(Date.parse(reviewed.review.expires_at), now + 300000);
+  now += 299999;
+  const approved = await host.privateChat.chat.reply(checkout.id, { ...binding, message_id: 'private-decision', text: 'approve', sent_at: new Date(now).toISOString() });
+  assert.equal(approved.stage, 'approved_for_submit'); assert.equal(approved.checkout.purchase_approved, true);
+  assert.equal(host.counters().submit, 1); // Only the deliberately denied early request.
+  assert.equal((await host.client.checkouts.get(checkout.id)).status, 'ready_for_submit');
+  const submitted = await host.client.checkouts.submit(checkout.id, { revision: filled.revision });
+  assert.equal(submitted.status, 'submit_attempted'); assert.equal(submitted.payment_confirmed, false);
+  await assert.rejects(host.client.checkouts.submit(checkout.id, { revision: filled.revision }), { code: 'submit_unavailable' });
+});
+
+test('purchase decision at five minutes is expired, and a private decline cancels without submission', async t => {
+  const originalNow = Date.now; let now = originalNow(); Date.now = () => now;
+  t.after(() => { Date.now = originalNow; });
+  const expired = await prepared('purchase'), filled = await expired.reachFill();
+  await expired.dispatch('review_ready', filled); now += 300000;
+  await assert.rejects(expired.host.privateChat.chat.reply(expired.checkout.id, { ...expired.binding,
+    message_id: 'late-decision', text: 'approve', sent_at: new Date(now).toISOString() }));
+  assert.equal(expired.host.counters().purchase_decision, 0); assert.equal(expired.host.counters().submit, 0);
+  const declined = await prepared('purchase'), next = await declined.reachFill();
+  await declined.dispatch('review_ready', next); now++;
+  const closed = await declined.host.privateChat.chat.reply(declined.checkout.id, { ...declined.binding,
+    message_id: 'private-decline', text: 'decline', sent_at: new Date(now).toISOString() });
+  assert.equal(closed.checkout.status, 'cancelled'); assert.equal(declined.host.counters().submit, 0);
+});
+
+test('starter registers the supported managed review profile and never accepts model purchase policy', async () => {
+  const tools = new Map();
+  const configured = await configureStarter({ registerTool(name, config, callback) { tools.set(name, { config, callback }); } }, {});
+  assert.equal(configured.mode, 'synthetic'); assert.equal(tools.size, 8); assert.equal(tools.has('accelerate_checkout_submit'), false);
+  const call = async (name, args) => (await tools.get(name).callback(args, {})).structuredContent;
+  const created = await call('accelerate_checkout_start', { start_url: syntheticCheckoutUrl });
+  assert.equal(created.ok, true); assert.equal(created.checkout.approval_policy, 'after_fill');
+  const rejected = await call('accelerate_checkout_start', { start_url: syntheticCheckoutUrl, purpose: 'purchase' });
+  assert.equal(rejected.ok, false); assert.equal(rejected.error.code, 'invalid_input');
+  const purchaseTools = new Map();
+  await configureStarter({ registerTool(name, _config, callback) { purchaseTools.set(name, callback); } },
+    { ACCELERATE_STARTER_PURPOSE: 'purchase', ACCELERATE_ENABLE_PURCHASE_SUBMIT: 'true' });
+  assert.equal(purchaseTools.has('accelerate_checkout_submit'), true);
+  for (const env of [{ ACCELERATE_STARTER_PURPOSE: 'unknown' }, { ACCELERATE_ENABLE_PURCHASE_SUBMIT: 'true' },
+    { ACCELERATE_ENABLE_PURCHASE_SUBMIT: '1' }]) await assert.rejects(configureStarter({ registerTool() { assert.fail('Invalid policy exposed tools.'); } }, env));
+});
+
+test('real mode fails closed without authenticated hooks and an actual private review sender', async t => {
+  const directory = await mkdtemp(join(tmpdir(), 'accelerate-starter-host-'));
+  t.after(() => rm(directory, { recursive: true, force: true }));
+  const modulePath = join(directory, 'missing-private-sender.mjs');
+  await writeFile(modulePath, "export async function createTrustedHost(){return Object.fromEntries(['resolveContext','withOwnedCheckout','withCheckoutCreation','dispatchCheckoutEvent'].map(key=>[key,async()=>{}]));}\n");
+  const live = { ACCELERATE_STARTER_MODE: 'live', ACCELERATE_CONTEXT_MODULE: modulePath,
+    ACCELERATE_API_KEY: 'synthetic_not_real_key'.padEnd(48, 'x'), ACCELERATE_MERCHANT_ID: 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee',
+    ACCELERATE_BASE_URL: 'https://managed.example' };
+  for (const env of [{ ACCELERATE_STARTER_MODE: 'live' }, { ACCELERATE_STARTER_MODE: 'live', ACCELERATE_CONTEXT_MODULE: './relative.mjs' },
+    { ...live, ACCELERATE_CONTEXT_MODULE: new URL('../trusted-context.example.mjs', import.meta.url).pathname }, live,
+    { ACCELERATE_STARTER_MODE: 'unknown' }]) {
+    await assert.rejects(configureStarter({ registerTool() { assert.fail('Unverified live host cannot expose tools.'); } }, env));
+  }
+});
+
+test('a live host cannot acknowledge queued, downgraded or mismatched private review delivery', async t => {
+  const directory = await mkdtemp(join(tmpdir(), 'accelerate-starter-unconfirmed-'));
+  t.after(() => rm(directory, { recursive: true, force: true }));
+  const modulePath = join(directory, 'queued-host.mjs');
+  const context = { customer_id: 'fixture-customer', workspace_id: 'fixture-workspace',
+    conversation_id: 'fixture-conversation', phone_number: '+15555550123' };
+  await writeFile(modulePath, `const context=${JSON.stringify(context)};
+    export async function createTrustedHost(){return {
+      resolveContext:async()=>({...context}),
+      withOwnedCheckout:async(_context,id,work)=>work({checkout_id:id,...context}),
+      withCheckoutCreation:async()=>{throw Error('Unexpected creation.');},
+      dispatchCheckoutEvent:async()=>{},
+      sendPrivateReview:async()=>{throw Error('Queued delivery is not a receipt.');}
+    };}\n`);
+  const id = 'mcs_' + 'q'.repeat(43), now = Date.now();
+  const checkout = { id, status: 'ready_for_submit', revision: 2, expires_at: new Date(now + 900000).toISOString(),
+    submit_expires_at: new Date(now + 420000).toISOString(), purpose: 'sandbox_fill_only', approval_policy: 'after_fill',
+    purchase_approved: false, submit_allowed: false, retry_safe: false, payment_confirmed: false,
+    quote: { checkout_origin: 'https://demos.weaccelerate.com', amount_cents: 100, currency: 'USD' } };
+  const previous = globalThis.fetch, paths = [];
+  let scenario = 'queued';
+  globalThis.fetch = async url => {
+    const path = new URL(url).pathname; paths.push(path);
+    if (path === `/v1/checkouts/${id}/fill`) return Response.json(checkout);
+    assert.equal(path, `/v1/checkouts/${id}/private-chat/state`);
+    const value = { checkout: { ...checkout }, stage: 'review_delivery_required', handled: true, duplicate: false, cards: [], addresses: [],
+      approval: { revision: 2, ...checkout.quote }, review: { id: 'rvr_' + 'r'.repeat(43), delivered: false,
+        expires_at: checkout.submit_expires_at, approval_window_ms: 300000, delivery_expires_at: new Date(now + 60000).toISOString() } };
+    if (scenario !== 'queued') { value.stage = 'review_delivered'; value.review.delivered = true; }
+    if (scenario === 'legacy-window') { delete value.review.approval_window_ms; delete value.review.delivery_expires_at; }
+    if (scenario === 'wrong-purpose') { value.checkout.purpose = 'purchase'; value.checkout.submit_allowed = true; value.stage = 'approval_required'; }
+    if (scenario === 'wrong-quote') { value.checkout.quote = { ...checkout.quote, amount_cents: 200 }; value.approval.amount_cents = 200; }
+    return Response.json(value);
+  };
+  t.after(() => { globalThis.fetch = previous; });
+  const tools = new Map();
+  await configureStarter({ registerTool(name, _config, callback) { tools.set(name, callback); } }, {
+    ACCELERATE_STARTER_MODE: 'live', ACCELERATE_CONTEXT_MODULE: modulePath,
+    ACCELERATE_API_KEY: 'synthetic_not_real_key'.padEnd(48, 'x'), ACCELERATE_MERCHANT_ID: 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee',
+    ACCELERATE_BASE_URL: 'https://managed.example',
+  });
+  for (scenario of ['queued', 'legacy-window', 'wrong-purpose', 'wrong-quote']) {
+    paths.length = 0;
+    const result = (await tools.get('accelerate_checkout_fill')({ checkout_id: id, revision: 2 }, {})).structuredContent;
+    assert.equal(result.ok, false, scenario); assert.equal(result.error.code, 'checkout_event_unconfirmed', scenario); assert.equal(result.checkout.id, id);
+    assert.deepEqual(paths, [`/v1/checkouts/${id}/fill`, `/v1/checkouts/${id}/private-chat/state`]);
+  }
+  assert.equal(paths.some(path => /\/(?:submit|cancel)$/.test(path)), false);
+});
+
+test('durable review events accept reordered quote keys and reject changed quote or checkout before image delivery', async t => {
+  const directory = await mkdtemp(join(tmpdir(), 'accelerate-starter-durable-'));
+  t.after(() => rm(directory, { recursive: true, force: true }));
+  const modulePath = join(directory, 'durable-host.mjs');
+  const context = { customer_id: 'fixture-customer', workspace_id: 'fixture-workspace',
+    conversation_id: 'fixture-conversation', phone_number: '+15555550123' };
+  await writeFile(modulePath, `const context=${JSON.stringify(context)}; let scenario;
+    export function setScenario(value){scenario=value;}
+    export async function createTrustedHost({deliverReview}){return {
+      resolveContext:async()=>({...context}),
+      withOwnedCheckout:async(_context,id,work)=>work({checkout_id:id,...context}),
+      withCheckoutCreation:async()=>{throw Error('Unexpected creation.');},
+      dispatchCheckoutEvent:async(context,event)=>{
+        const durable=JSON.parse(JSON.stringify(event)),quote=durable.checkout.quote;
+        durable.checkout.quote={currency:quote.currency,amount_cents:quote.amount_cents,checkout_origin:quote.checkout_origin};
+        if(scenario==='changed-quote')durable.checkout.quote.amount_cents++;
+        if(scenario==='changed-id')durable.checkout.id='mcs_'+'z'.repeat(43);
+        await deliverReview(context,durable);
+      },
+      sendPrivateReview:async()=>({message_id:'durable-provider-receipt',sent_at:new Date().toISOString()})
+    };}\n`);
+  const module = await import(pathToFileURL(modulePath).href), id = 'mcs_' + 'd'.repeat(43), now = Date.now();
+  const checkout = { id, status: 'ready_for_submit', revision: 2, expires_at: new Date(now + 900000).toISOString(),
+    submit_expires_at: new Date(now + 420000).toISOString(), purpose: 'sandbox_fill_only', approval_policy: 'after_fill',
+    purchase_approved: false, submit_allowed: false, retry_safe: false, payment_confirmed: false,
+    quote: { checkout_origin: 'https://demos.weaccelerate.com', amount_cents: 100, currency: 'USD' } };
+  const review = { id: 'rvr_' + 'r'.repeat(43), delivered: false, expires_at: checkout.submit_expires_at,
+    approval_window_ms: 300000, delivery_expires_at: new Date(now + 60000).toISOString() };
+  let acknowledged = false, expiresAt = checkout.submit_expires_at;
+  const previous = globalThis.fetch, paths = [];
+  globalThis.fetch = async (url, request) => {
+    const path = new URL(url).pathname; paths.push(path);
+    if (path.endsWith('/fill')) return Response.json(checkout);
+    if (path.endsWith('/private-chat/review')) return new Response(Buffer.from([137,80,78,71,13,10,26,10,1]), { headers: {
+      'Content-Type': 'image/png', 'X-Accelerate-Review-Id': review.id, 'X-Accelerate-Review-Expires-At': review.expires_at,
+      'X-Accelerate-Review-Amount-Cents': '100', 'X-Accelerate-Review-Currency': 'USD',
+      'X-Accelerate-Review-Approval-Window-Ms': '300000', 'X-Accelerate-Review-Delivery-Expires-At': review.delivery_expires_at } });
+    if (path.endsWith('/private-chat/review-delivered')) {
+      const receipt = JSON.parse(request.body); acknowledged = true;
+      expiresAt = new Date(Date.parse(receipt.sent_at) + 300000).toISOString();
+    } else assert.ok(path.endsWith('/private-chat/state'));
+    return Response.json({ checkout: { ...checkout, submit_expires_at: expiresAt },
+      stage: acknowledged ? 'review_delivered' : 'review_delivery_required', handled: true, duplicate: false, cards: [], addresses: [],
+      approval: { revision: 2, ...checkout.quote }, review: { ...review, delivered: acknowledged, expires_at: expiresAt } });
+  };
+  t.after(() => { globalThis.fetch = previous; });
+  const tools = new Map();
+  await configureStarter({ registerTool(name, _config, callback) { tools.set(name, callback); } }, {
+    ACCELERATE_STARTER_MODE: 'live', ACCELERATE_CONTEXT_MODULE: modulePath,
+    ACCELERATE_API_KEY: 'synthetic_not_real_key'.padEnd(48, 'x'), ACCELERATE_MERCHANT_ID: 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee',
+    ACCELERATE_BASE_URL: 'https://managed.example',
+  });
+  for (const scenario of ['reordered', 'changed-quote', 'changed-id']) {
+    module.setScenario(scenario); paths.length = 0; acknowledged = false; expiresAt = checkout.submit_expires_at;
+    const result = (await tools.get('accelerate_checkout_fill')({ checkout_id: id, revision: 2 }, {})).structuredContent;
+    assert.equal(result.ok, scenario === 'reordered', scenario);
+    assert.equal(acknowledged, scenario === 'reordered', scenario);
+    assert.equal(paths.filter(path => path.endsWith('/private-chat/review')).length, scenario === 'reordered' ? 1 : 0);
+    if (scenario !== 'reordered') {
+      assert.equal(result.error.code, 'checkout_event_unconfirmed'); assert.equal(paths.length, 2);
+    }
+  }
+});

package/starter/trusted-context.example.mjs

@@ -0,0 +1,49 @@
+/**
+ * Real-mode contract ONLY. This deliberately cannot authenticate anyone.
+ * Replace with your existing authenticated backend and durable ownership store.
+ * Never turn MCP arguments/_meta into identity or use synthetic identities here.
+ */
+export async function createTrustedHost({ client, privateChat, deliverReview }) {
+  // Return these existing application hooks:
+  // resolveContext(extra) -> verified {customer_id,workspace_id,conversation_id,phone_number}
+  // withOwnedCheckout(context,id,work) -> work(savedBinding) under the owner lock
+  //   savedBinding is EXACT {checkout_id,customer_id,workspace_id,conversation_id,phone_number}.
+  // withCheckoutCreation(context,work) -> work({idempotency_key,persistCreated})
+  //   persistCreated(savedBinding) resolves only after durable ownership acceptance.
+  // Retain the unresolved-attempt fence if create/persist acknowledgement is lost.
+  // This starter sets verificationTiming:'on_payment'. Creating its browser
+  // does not dispatch an event or start private verification. The agent calls
+  // accelerate_checkout_request_payment only when the checkout needs payment.
+  // dispatchCheckoutEvent(context,event) durably accepts/deduplicates the safe
+  // payment_requested/approval_requested event. payment_requested invokes
+  // privateChat.chat.start; approval_requested invokes privateChat.chat.get.
+  // Render and privately deliver the prompt; recover via this durable outbox
+  // if acknowledgement is lost. Status tools never trigger prompt delivery.
+  // The bundled runtime selects profile:'managed_review_v1': on_payment,
+  // after_fill, and a full five minutes after confirmed review delivery.
+  // approval_requested prepares fresh CVV privately, without purchase approval.
+  // dispatchCheckoutEvent must durably deduplicate review_ready and invoke
+  // await deliverReview(context,event) from that same event worker. Resolve the
+  // event only AFTER the helper confirms the provider receipt and service ACK;
+  // preserve unresolved delivery work on failure. Retry this exact review event,
+  // never fill again. Already-acknowledged reviews do not send another image.
+  // sendPrivateReview(context,message) -> {message_id,sent_at} is REQUIRED.
+  // Authenticate the private destination from context. Upload message.bytes and
+  // send message.text TOGETHER, using message.idempotency_key. Honor its signal
+  // and delivery_expires_at. Return the actual provider-confirmed sent receipt;
+  // never synthesize sent_at or acknowledge a queued-only send. The SDK fetches
+  // and verifies the safe PNG, sends it through this hook, then wipes its bytes.
+  // Private replies must be routed through privateChat.chat.reply before any
+  // message/history/model persistence; OTP/CVV never enter model tool arguments.
+  // sandbox_fill_only sends an informational review and needs no purchase
+  // approval. The agent cancels that test after delivery; submit stays disabled.
+  // A qualified purchase waits for the private simple approve/decline decision;
+  // approval does not submit. Explicit server configuration exposes the separate
+  // agent submit tool. The filled page remains private throughout this interval.
+  // Fresh approval replies must carry authenticated provider sent_at and the
+  // reply target when present. Do not synthesize sent_at from receipt time.
+  // The separate on_start compatibility profile uses a created event instead.
+  // Do not log either client, raw messages, callbacks or private webhook bodies.
+  void client; void privateChat; void deliverReview;
+  throw Error('Implement the authenticated host contract before enabling real mode.');
+}