@weaccelerateinc/agent-sdk 0.0.0-stage → 0.11.0

package/linq-messaging.js

@@ -0,0 +1,123 @@
+import { AccelerateError } from './index.js';
+import { authenticatedCheckoutContext } from './host-adapter.js';
+
+const HANDLE = /^[A-Za-z0-9_-]{1,500}$/;
+const MESSAGE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/;
+const maximumReviewImageBytes = 8 * 1024 * 1024;
+const check = condition => { if (!condition) throw new AccelerateError('request_failed'); };
+const phone = value => typeof value === 'string' && /^\+[1-9][\d ()-]+$/.test(value) ? value.replace(/[ ()-]/g, '') : undefined;
+function receipt(value, chatId, expectedId) {
+  check(value && value.chat_id === chatId && value.is_from_me === true && MESSAGE.test(value.id) && (!expectedId || value.id === expectedId));
+  if (!['sent', 'delivered', 'read'].includes(value.delivery_status)) return undefined;
+  check(typeof value.sent_at === 'string' && Number.isFinite(Date.parse(value.sent_at)) && Date.parse(value.sent_at) <= Date.now());
+  return { message_id: value.id, sent_at: new Date(value.sent_at).toISOString() };
+}
+async function wait(ms, signal) {
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(done, ms);
+    function done() { signal?.removeEventListener('abort', abort); resolve(); }
+    function abort() { clearTimeout(timer); signal?.removeEventListener('abort', abort); reject(new AccelerateError('request_cancelled')); }
+    signal?.addEventListener('abort', abort, { once: true }); if (signal?.aborted) abort();
+  });
+}
+function boundedSignal(signal, expiresAt) {
+  const remaining = expiresAt === undefined ? 45000 : Date.parse(expiresAt) - Date.now(); check(Number.isFinite(remaining) && remaining > 0);
+  const timeout = AbortSignal.timeout(Math.min(45000, remaining));
+  return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+function prompt(message) {
+  check(message && typeof message.text === 'string' && message.text.length > 0 && message.text.length <= 10000 && typeof message.idempotency_key === 'string' && /^[A-Za-z0-9_.:-]{1,200}$/.test(message.idempotency_key));
+}
+
+/** Native Linq transport. Inject the installed @linqapp/sdk client configured
+ * with its server-only credential; the SDK does not install or own that key. */
+export function createLinqMessagingAdapter({ client, sendingPhone, resolveDestination, fetchImpl = globalThis.fetch } = {}) {
+  check(typeof client?.chats?.retrieve === 'function' && typeof client?.chats?.messages?.send === 'function' && typeof client?.messages?.retrieve === 'function' && typeof client?.attachments?.create === 'function' && /^\+[1-9]\d{6,14}$/.test(sendingPhone) && typeof resolveDestination === 'function' && typeof fetchImpl === 'function');
+  const destination = async (input, signal) => {
+    const context = authenticatedCheckoutContext(input), chatId = await resolveDestination(context);
+    check(typeof chatId === 'string' && HANDLE.test(chatId) && chatId !== 'pending' && context.phone_number !== sendingPhone);
+    signal.throwIfAborted();
+    const chat = await client.chats.retrieve(chatId, { signal, maxRetries: 0, timeout: 5000 });
+    check(chat?.id === chatId && chat.is_group === false && Array.isArray(chat.handles) && chat.handles.length === 2);
+    const own = chat.handles.filter(handle => handle.is_me === true), recipient = chat.handles.filter(handle => handle.is_me === false);
+    check(own.length === 1 && recipient.length === 1 && phone(own[0].handle) === sendingPhone && phone(recipient[0].handle) === context.phone_number && chat.handles.every(handle => handle.left_at == null && !['left', 'removed'].includes(handle.status)));
+    return chatId;
+  };
+  const send = async (chatId, message, signal, expiresAt) => {
+    signal.throwIfAborted();
+    const sent = await client.chats.messages.send(chatId, { message }, { signal, maxRetries: 0, timeout: 15000 });
+    check(sent?.chat_id === chatId && MESSAGE.test(sent?.message?.id));
+    const expectedId = sent.message.id;
+    // The send envelope proves this is our send; retrieval independently checks
+    // direction. Neither API's queue timestamp can arm purchase approval.
+    let current = { ...sent.message, chat_id: chatId, is_from_me: true };
+    for (let attempt = 0; attempt < 12; attempt++) {
+      signal.throwIfAborted(); check(expiresAt === undefined || Date.parse(expiresAt) > Date.now());
+      const confirmed = receipt(current, chatId, expectedId);
+      if (confirmed) return confirmed;
+      check(current.delivery_status !== 'failed');
+      await wait(1000, signal);
+      current = await client.messages.retrieve(expectedId, { signal, maxRetries: 0, timeout: 5000 });
+    }
+    throw new AccelerateError('request_failed');
+  };
+  return Object.freeze({
+    async sendText(context, message, options = {}) {
+      try {
+        prompt(message); const signal = boundedSignal(options.signal), chatId = await destination(context, signal);
+        return await send(chatId, { parts: [{ type: 'text', value: message.text }], idempotency_key: message.idempotency_key }, signal);
+      } catch { throw new AccelerateError('request_failed'); }
+    },
+    async sendReview(context, message) {
+      let uploadCopy;
+      try {
+        prompt(message);
+        check(Buffer.isBuffer(message.bytes) && message.bytes.length > 8 && message.bytes.length <= maximumReviewImageBytes && message.bytes.subarray(0, 8).equals(Buffer.from([137,80,78,71,13,10,26,10])) && message.contentType === 'image/png' && message.signal instanceof AbortSignal);
+        const signal = boundedSignal(message.signal, message.delivery_expires_at), chatId = await destination(context, signal);
+        const attachment = await client.attachments.create({ filename: 'accelerate-payment-review.png', content_type: 'image/png', size_bytes: message.bytes.length }, { signal, maxRetries: 0, timeout: 10000 });
+        let url; try { url = new URL(attachment.upload_url); } catch { check(false); }
+        check(url.protocol === 'https:' && !url.username && !url.password && attachment.http_method === 'PUT' && HANDLE.test(attachment.attachment_id) && attachment.required_headers && typeof attachment.required_headers === 'object' && Object.entries(attachment.required_headers).every(([key, value]) => typeof key === 'string' && typeof value === 'string'));
+        signal.throwIfAborted(); uploadCopy = Buffer.from(message.bytes);
+        const uploaded = await fetchImpl(url, { method: 'PUT', redirect: 'error', cache: 'no-store', credentials: 'omit', referrerPolicy: 'no-referrer', signal, headers: attachment.required_headers, body: uploadCopy });
+        try { await uploaded.body?.cancel(); } catch {}
+        check(uploaded.ok && !uploaded.redirected); signal.throwIfAborted();
+        return await send(chatId, { parts: [{ type: 'media', attachment_id: attachment.attachment_id }, { type: 'text', value: message.text }], idempotency_key: message.idempotency_key }, signal, message.delivery_expires_at);
+      } catch { throw new AccelerateError('request_failed'); }
+      finally { uploadCopy?.fill(0); }
+    },
+  });
+}
+
+/** Signature/OIDC verification and identity resolution are host dependencies.
+ * Never treat provider sender text, chat ID or a successful JSON parse as auth. */
+export function createLinqWebhookAuthenticator({ verifyWebhook, resolveIdentity, retrieveChat } = {}) {
+  check(typeof verifyWebhook === 'function' && typeof resolveIdentity === 'function' && typeof retrieveChat === 'function');
+  return async (request, rawBody) => {
+    let decoded;
+    try {
+      check(rawBody instanceof Uint8Array && rawBody.byteLength <= 262144 && await verifyWebhook(request, rawBody) === true);
+      decoded = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(rawBody));
+      if (decoded?.event_type !== 'message.received') return { kind: 'ignore' };
+      const data = decoded.data;
+      check(data && MESSAGE.test(data.id) && ['inbound', 'outbound'].includes(data.direction) && HANDLE.test(data.chat?.id) && data.sender_handle && typeof data.sender_handle.handle === 'string' && Array.isArray(data.parts) && data.parts.length <= 100);
+      if (data.direction !== 'inbound' || data.sender_handle.is_me === true) return { kind: 'ignore' };
+      const senderPhone = phone(data.sender_handle.handle); check(senderPhone && /^\+[1-9]\d{6,14}$/.test(senderPhone));
+      let isGroup = data.chat.is_group;
+      if (typeof isGroup !== 'boolean') { const chat = await retrieveChat(data.chat.id); check(chat?.id === data.chat.id && typeof chat.is_group === 'boolean'); isGroup = chat.is_group; }
+      check(isGroup === false);
+      const context = authenticatedCheckoutContext(await resolveIdentity({ phone_number: senderPhone, chat_id: data.chat.id }));
+      check(context.phone_number === senderPhone);
+      const parts = data.parts.map(part => { check(part && typeof part.type === 'string' && (part.value === undefined || typeof part.value === 'string')); return part; });
+      const text = parts.filter(part => ['text', 'link'].includes(part.type)).map(part => part.value ?? '').join('\n').trim(); check(text.length <= 2000);
+      const result = { authenticated: true, direct: true, context, message_id: data.id, text };
+      // Historical/reconciled deliveries cannot approve a current payment.
+      if (!data.reconciled_at && data.sent_at != null) { check(typeof data.sent_at === 'string' && Number.isFinite(Date.parse(data.sent_at))); result.sent_at = new Date(data.sent_at).toISOString(); }
+      if (data.reply_to?.message_id !== undefined) { check(MESSAGE.test(data.reply_to.message_id)); result.reply_to_message_id = data.reply_to.message_id; }
+      return result;
+    } catch { throw new AccelerateError('permission_denied'); }
+    finally {
+      if (Array.isArray(decoded?.data?.parts)) for (const part of decoded.data.parts) { if (part && typeof part === 'object' && Object.hasOwn(part, 'value')) part.value = ''; }
+      decoded = undefined;
+    }
+  };
+}

package/managed-mcp.d.ts

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