@weaccelerateinc/agent-sdk 0.0.0-stage → 0.11.0

package/partner.d.ts

@@ -0,0 +1,27 @@
+import type { AccelerateClient } from './index.js';
+import type { AcceleratePrivateChatClient } from './private-chat.js';
+import type { BrowserConnector } from './browser-connector.js';
+import type { DurableCheckoutHost, HostPersistence } from './host-adapter.js';
+import type { ManagedCheckoutToolsOptions, ManagedMcpServer } from './managed-mcp.js';
+import type { PrivateCheckoutIngress, PrivateMessagingAdapter, AuthenticatedPrivateMessage } from './private-ingress.js';
+export interface PartnerCheckoutOptions<Extra = unknown, Request = unknown> {
+  client: AccelerateClient;
+  privateChat: AcceleratePrivateChatClient;
+  persistence: HostPersistence;
+  resolveContext: ManagedCheckoutToolsOptions<Extra>['resolveContext'];
+  browserConnector: BrowserConnector;
+  authenticate(request: Request, body: Uint8Array): Promise<AuthenticatedPrivateMessage | { kind: 'ignore' }>;
+  messaging: PrivateMessagingAdapter;
+  admitOrdinaryMessage(event: { binding: import('./host-adapter.js').HostOwner; message_id: string; text: string }): Promise<void>;
+  dispatchSafeProgress(progress: import('./private-chat.js').PrivateChatProgress & { binding: import('./host-adapter.js').HostOwner; checkout_id: string }): Promise<void>;
+  /** Explicitly select v2 for backend fill immediately after private CVV; legacy callers retain v1. */
+  profile?: 'managed_review_v1' | 'managed_review_v2';
+  purpose?: 'sandbox_fill_only' | 'purchase';
+  enableSubmit?: boolean;
+}
+/** Registers only canonical safe tools; private ingress must run before AI/history. */
+export function registerPartnerCheckoutTools<Extra = unknown, Request = unknown>(server: ManagedMcpServer<Extra>, options: PartnerCheckoutOptions<Extra, Request>): Readonly<{
+  tools: readonly unknown[];
+  host: DurableCheckoutHost<Extra>;
+  privateIngress: PrivateCheckoutIngress<Request>;
+}>;

package/partner.js

@@ -0,0 +1,53 @@
+import { registerManagedCheckoutTools } from './managed-mcp.js';
+import { createDurableCheckoutHost } from './host-adapter.js';
+import { createPrivateCheckoutIngress } from './private-ingress.js';
+
+/** Compose the supported existing-browser profile. All callbacks are trusted
+ * backend dependencies; none are model inputs or automatically authenticated. */
+export function registerPartnerCheckoutTools(server, options = {}) {
+  const { client, privateChat, persistence, resolveContext, browserConnector, authenticate,
+    messaging, admitOrdinaryMessage, dispatchSafeProgress,
+    purpose = 'sandbox_fill_only', enableSubmit = false, profile = 'managed_review_v1' } = options;
+  if (!['managed_review_v1', 'managed_review_v2'].includes(profile)) throw Error('Unsupported partner checkout profile.');
+  if (browserConnector?.contract !== 'accelerate_existing_browser_v1' || !privateChat?.chat) {
+    throw Error('An existing-browser connector and private chat client are required.');
+  }
+  // Accelerate never sends the final click. A purchase needs the customer's own browser host to do it once.
+  if (purpose === 'purchase' && (typeof browserConnector.performFinalClick !== 'function' || typeof browserConnector.prepareFinalClick !== 'function')) {
+    throw Error('Purchase requires a connector whose host implements performFinalClick: the customer\u2019s own browser performs the final click.');
+  }
+  const host = createDurableCheckoutHost({ persistence, resolveContext });
+  // Keep the filled browser until explicit cancel or separately authorized
+  // submit. Review delivery can be recovered without repeating the fill.
+  const ingress = createPrivateCheckoutIngress({ host, privateChat, messaging, authenticate,
+    admitOrdinaryMessage, dispatchSafeProgress, browserConnector });
+  const tools = registerManagedCheckoutTools(server, { client, resolveContext: host.resolveContext,
+    withCheckoutCreation: host.withCheckoutCreation,
+    withOwnedCheckout: async (context, id, work, operation) => {
+      const result = await host.withOwnedCheckout(context, id, work, operation);
+      if (['accelerate_checkout_status', 'accelerate_checkout_cancel'].includes(operation?.operation) && result.checkout?.diagnostics?.cleanup_status === 'confirmed') {
+        // MCP already asked the connector for independent cleanup proof.
+        await host.confirmBrowserCleanup(context, id);
+      }
+      return result;
+    },
+    dispatchCheckoutEvent: async (context, event) => {
+      await host.dispatchCheckoutEvent(context, event);
+      await ingress.drain(context);
+      if (event.kind !== 'review_ready') return;
+      const state = await privateChat.chat.get(event.checkout.id, {
+        customer_id: context.customer_id, workspace_id: context.workspace_id, conversation_id: context.conversation_id,
+      });
+      if (state.checkout.id !== event.checkout.id || state.checkout.revision !== event.checkout.revision ||
+        state.checkout.purpose !== purpose || state.checkout.status !== 'ready_for_submit' ||
+        state.checkout.approval_policy !== 'after_fill' || !state.checkout.quote || !event.checkout.quote ||
+        !['checkout_origin', 'amount_cents', 'currency'].every(key => state.checkout.quote[key] === event.checkout.quote[key]) ||
+        state.review?.delivered !== true || state.review.approval_window_ms !== 300000 ||
+        !(purpose === 'sandbox_fill_only' ? state.stage === 'review_delivered' : ['approval_required', 'approved_for_submit'].includes(state.stage))) {
+        throw Error('Private review delivery is unconfirmed.');
+      }
+    },
+    browserConnector, browserMode: 'customer_backend_trusted', profile, purpose, enableSubmit,
+  });
+  return Object.freeze({ tools, host, privateIngress: ingress });
+}

package/postgres-host.d.ts

@@ -0,0 +1,14 @@
+import type { HostPersistence } from './host-adapter.js';
+export const checkoutHostMigrationSql: string;
+export interface CheckoutHostPostgresClient {
+  query(sql: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[]; rowCount?: number | null }>;
+  release(destroy?: boolean): void;
+  on?(event: 'error', listener: () => void): unknown;
+  removeListener?(event: 'error', listener: () => void): unknown;
+}
+export function createPostgresCheckoutPersistence(options: {
+  pool: { connect(): Promise<CheckoutHostPostgresClient> };
+  encryptionKey: Buffer | string;
+  namespace?: string;
+  lockTimeoutMs?: number;
+}): Readonly<HostPersistence & { initialize(): Promise<void> }>;

package/postgres-host.js

@@ -0,0 +1,102 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+
+export const checkoutHostMigrationSql = `CREATE TABLE IF NOT EXISTS accelerate_partner_checkout_host (
+  namespace text NOT NULL, owner_key text NOT NULL, payload bytea NOT NULL,
+  updated_at timestamptz NOT NULL DEFAULT clock_timestamp(), PRIMARY KEY(namespace,owner_key)
+)`;
+const unavailable = () => Error('Durable checkout host storage is unavailable.');
+const check = value => { if (!value) throw unavailable(); };
+const sizeLimit = 1024 * 1024;
+/** Encrypted, independently committed records under a session advisory lock.
+ * The caller supplies its existing pg Pool. No credentials or schema changes
+ * are inferred from MCP arguments; initialize() is an explicit operator step. */
+export function createPostgresCheckoutPersistence({ pool, encryptionKey, namespace = 'accelerate-partner-v1', lockTimeoutMs = 10000 } = {}) {
+  let key;
+  try {
+    key = Buffer.isBuffer(encryptionKey) ? Buffer.from(encryptionKey) : Buffer.from(encryptionKey ?? '', 'base64url');
+    check(key.length === 32 && (Buffer.isBuffer(encryptionKey) || key.toString('base64url') === encryptionKey) &&
+      pool && typeof pool.connect === 'function' && /^[A-Za-z0-9_.:-]{1,100}$/.test(namespace) &&
+      Number.isInteger(lockTimeoutMs) && lockTimeoutMs > 0 && lockTimeoutMs <= 30000);
+  } catch { key?.fill(0); throw unavailable(); }
+  const aad = owner => Buffer.from(JSON.stringify(['accelerate-partner-host-v1', namespace, owner]));
+  const seal = (record, owner) => {
+    let plain;
+    try {
+      plain = Buffer.from(JSON.stringify(record)); check(plain.length > 0 && plain.length <= sizeLimit);
+      const iv = randomBytes(12), cipher = createCipheriv('aes-256-gcm', key, iv); cipher.setAAD(aad(owner));
+      const encrypted = Buffer.concat([cipher.update(plain), cipher.final()]);
+      return Buffer.concat([Buffer.from([1]), iv, cipher.getAuthTag(), encrypted]);
+    } finally { plain?.fill(0); }
+  };
+  const open = (payload, owner) => {
+    let plain;
+    try {
+      check(Buffer.isBuffer(payload) && payload.length > 29 && payload.length <= sizeLimit + 29 && payload[0] === 1);
+      const cipher = createDecipheriv('aes-256-gcm', key, payload.subarray(1, 13));
+      cipher.setAAD(aad(owner)); cipher.setAuthTag(payload.subarray(13, 29));
+      plain = Buffer.concat([cipher.update(payload.subarray(29)), cipher.final()]);
+      return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(plain));
+    } finally { plain?.fill(0); }
+  };
+  return Object.freeze({
+    async initialize() {
+      let client, failed = false;
+      try { client = await pool.connect(); await client.query(checkoutHostMigrationSql); }
+      catch { failed = true; throw unavailable(); }
+      finally { client?.release(failed); }
+    },
+    async withLock(owner, work) {
+      let client, held = false, failed = false, callbackStarted = false, output, callbackError, callbackFailed = false;
+      const onError = () => { failed = true; };
+      try {
+        check(typeof owner === 'string' && /^accelerate-partner-host:[a-f0-9]{64}$/.test(owner) && typeof work === 'function');
+        client = await pool.connect(); client.on?.('error', onError);
+        const started = performance.now();
+        do {
+          check(!failed);
+          const value = await client.query('SELECT pg_try_advisory_lock(hashtextextended($1,0)) AS held', [namespace + ':' + owner]);
+          held = value.rows?.[0]?.held === true;
+          if (held) break;
+          check(performance.now() - started < lockTimeoutMs);
+          await new Promise(resolve => setTimeout(resolve, 25));
+        } while (!held);
+        const guard = () => check(held && !failed);
+        const access = Object.freeze({
+          async load() {
+            try {
+              guard(); const result = await client.query('SELECT payload FROM accelerate_partner_checkout_host WHERE namespace=$1 AND owner_key=$2', [namespace, owner]); guard();
+              check(Array.isArray(result.rows) && result.rows.length <= 1);
+              return result.rows.length ? open(result.rows[0].payload, owner) : undefined;
+            } catch { failed = true; throw unavailable(); }
+          },
+          async commit(record) {
+            guard(); let payload;
+            try {
+              payload = seal(record, owner);
+              // Deliberately no enclosing BEGIN: this commit must survive a
+              // later remote failure in the owner callback.
+              const result = await client.query(`INSERT INTO accelerate_partner_checkout_host(namespace,owner_key,payload)
+                VALUES($1,$2,$3) ON CONFLICT(namespace,owner_key) DO UPDATE SET payload=EXCLUDED.payload,updated_at=clock_timestamp()`, [namespace, owner, payload]);
+              guard(); check(result.rowCount === 1);
+            } catch { failed = true; throw unavailable(); } finally { payload?.fill(0); }
+          },
+        });
+        callbackStarted = true;
+        try { output = await work(access); } catch (error) { callbackError = error; callbackFailed = true; }
+        guard();
+      } catch { failed = true; throw unavailable(); }
+      finally {
+        if (client) {
+          if (held) try {
+            const result = await client.query('SELECT pg_advisory_unlock(hashtextextended($1,0)) AS released', [namespace + ':' + owner]);
+            if (result.rows?.[0]?.released !== true) failed = true;
+          } catch { failed = true; }
+          held = false; client.removeListener?.('error', onError); client.release(failed);
+        }
+      }
+      check(callbackStarted && !failed);
+      if (callbackFailed) throw callbackError;
+      return output;
+    },
+  });
+}

package/private-chat.d.ts

@@ -0,0 +1,104 @@
+import type { AccelerateClientOptions, AccelerateEnvironment, Checkout, CheckoutId, RequestOptions } from './index.js';
+
+/** All values must come from authenticated server/webhook context, never model arguments. */
+export interface PrivateChatBinding {
+  customer_id: string;
+  workspace_id: string;
+  conversation_id: string;
+}
+export interface PrivateChatReply extends PrivateChatBinding {
+  /** Provider-authenticated message ID. Reuse on delivery retries; never derive from message text. */
+  message_id: string;
+  /** Transient raw reply, including OTP/CVV. This field is cleared after the operation, including errors. */
+  text: string;
+  /** Authenticated provider timestamp; required for after_fill purchase approval. */
+  sent_at?: string;
+  reply_to_message_id?: string;
+}
+export interface PrivateChatState {
+  checkout: Checkout;
+  stage: 'not_started' | 'identity_required' | 'otp_required' | 'selection_required' | 'preparing_checkout' | 'approval_required' | 'cvv_required' | 'verified' | 'review_delivery_required' | 'review_delivered' | 'approved_for_submit' | 'closed';
+  /** true means consume the incoming message before AI/history/analytics, even when malformed. */
+  handled: boolean;
+  /** Provider message ID was previously processed. No external operation was repeated. */
+  duplicate: boolean;
+  cards: Array<{ choice: number; last4: string | null; brand: string | null }>;
+  addresses: Array<{ choice: number; label: string | null; city?: string | null; state?: string | null; postal_code_mask?: string | null }>;
+  identity_field?: 'first_name' | 'last_name' | 'email';
+  /** Fixed feedback for an incomplete wallet selection; never contains the customer's reply. */
+  selection_error?: 'invalid_choice' | 'address_required';
+  /** Frozen quote. Legacy before_fill includes a typed code; after_fill uses a delivered private review and simple decision. */
+  approval?: { revision: number; checkout_origin: string; amount_cents: number; currency: 'USD'; approval_code?: string };
+  review?: { id: string; expires_at: string; delivered: boolean;
+    /** Qualified post-fill policy: a full five minutes starts at the provider-confirmed prompt timestamp. */
+    approval_window_ms?: 300000;
+    /** Image and exact-total prompt must be confirmed sent before this deadline. */
+    delivery_expires_at?: string };
+}
+export interface PrivateChatPresentationOptions {
+  /** Provider-authenticated stable ID; delivery retries must reuse it. Never pass reply text. */
+  messageId: string;
+}
+export interface PrivateChatPrompt {
+  /** Fixed local wording plus the validated masked wallet/quote metadata. */
+  text: string;
+  /** Deterministic provider delivery key. Original identifiers are hashed, not exposed. */
+  idempotency_key: string;
+}
+export interface PrivateChatProgress extends PrivateChatPrompt {
+  stage: 'preparing_checkout' | 'verified' | 'approved_for_submit' | 'closed';
+}
+/** Revalidates safe state. Returns undefined for ordinary unhandled messages. Does not authenticate webhooks. */
+export function renderPrivateChatState(state: PrivateChatState, options: PrivateChatPresentationOptions): PrivateChatPrompt | undefined;
+/** Fixed server-authored event; caller retains durable stage-transition/delivery dedupe and ownership checks. */
+export function privateChatProgress(state: PrivateChatState, options: PrivateChatPresentationOptions): PrivateChatProgress | undefined;
+export interface PrivateReviewImage {
+  bytes: Buffer;
+  review_id: string;
+  expires_at: string;
+  amount_cents: number;
+  currency: 'USD';
+  approval_window_ms?: 300000;
+  delivery_expires_at?: string;
+}
+export interface PrivateReviewSend {
+  /** Transient safe PNG. Upload while this callback runs; the SDK wipes it afterwards. */
+  bytes: Buffer;
+  contentType: 'image/png';
+  /** Send this exact final-total question with the image in the same private message. */
+  text: string;
+  idempotency_key: string;
+  delivery_expires_at: string;
+  signal: AbortSignal;
+}
+/** Fetch, verify, render, send and acknowledge a private review. The host must
+ * authenticate the customer destination and obtain the receipt from its actual
+ * provider; neither destination nor receipt may come from model arguments.
+ * Requires the managed_review_v1 five-minute proof on state, image and delivery
+ * acknowledgement. Rejects missing/short legacy windows without falling back.
+ * The acknowledged deadline must equal the provider's sent_at plus 300000 ms.
+ * Keeps bytes transient and wipes them on success, timeout and errors. */
+export function deliverPrivateCheckoutReview(options: {
+  client: AcceleratePrivateChatClient;
+  state: PrivateChatState;
+  binding: PrivateChatBinding;
+  messageId: string;
+  send(message: PrivateReviewSend): Promise<{ message_id: string; sent_at: string }>;
+  signal?: AbortSignal;
+}): Promise<PrivateChatState>;
+/** Use only in a private ingress handler, before message persistence, queues and model calls. */
+export class AcceleratePrivateChatClient {
+  /** Server environment factory; same configuration/defaults as the ordinary client, private methods only. */
+  static fromEnv(env?: AccelerateEnvironment): AcceleratePrivateChatClient;
+  constructor(options: AccelerateClientOptions);
+  readonly chat: {
+    start(id: CheckoutId, input: PrivateChatBinding, options?: RequestOptions): Promise<PrivateChatState>;
+    get(id: CheckoutId, input: PrivateChatBinding, options?: RequestOptions): Promise<PrivateChatState>;
+    reply(id: CheckoutId, input: PrivateChatReply, options?: RequestOptions): Promise<PrivateChatState>;
+    cancel(id: CheckoutId, input: PrivateChatBinding, options?: RequestOptions): Promise<PrivateChatState>;
+    /** Private sender only. RAM-only safe PNG; never expose as a model tool or public URL. Clear bytes after upload. */
+    review(id: CheckoutId, input: PrivateChatBinding, options?: RequestOptions): Promise<PrivateReviewImage>;
+    /** Call only after screenshot and exact-total prompt were confirmed sent together by the provider. */
+    reviewDelivered(id: CheckoutId, input: PrivateChatBinding & { review_id: string; message_id: string; sent_at: string }, options?: RequestOptions): Promise<PrivateChatState>;
+  };
+}