@runtypelabs/persona-proxy 3.19.0 → 3.26.0

package/dist/index.d.cts

@@ -61,6 +61,53 @@ declare const BAKERY_ASSISTANT_FLOW: RuntypeFlowConfig;
  */
 declare const STOREFRONT_ASSISTANT_FLOW: RuntypeFlowConfig;
 
+/**
+ * WebMCP storefront flow for the "Switchback" trail/road running demo
+ * (`examples/embedded-app/webmcp-demo.html`).
+ *
+ * Unlike the other example flows, this agent owns **no** tools of its own. The
+ * demo page registers its tools on `document.modelContext` via WebMCP
+ * (`search_products`, `view_product`, `add_to_cart`, `remove_from_cart`,
+ * `apply_promo`); the widget snapshots them every turn and the proxy forwards
+ * them on the dispatch payload as `clientTools[]`. The Runtype runtime threads
+ * those into this prompt step's tool set, so the model calls them by name and
+ * the widget executes them **on the page**, posting results back via `/resume`.
+ *
+ * That means the agent definition that drives the WebMCP demo lives entirely in
+ * this repo — no hosted Runtype agent / client token required. The flow just
+ * needs a tool-capable model and a system prompt that knows how to shop the
+ * (page-provided) catalog.
+ *
+ * Model: `nemotron-3-ultra-550b-a55b`. WebMCP depends on the model
+ * emitting **native** tool calls (each surfaces as a `step_await` the widget
+ * resumes), so a tool-reliable model is required here. `responseFormat` is
+ * markdown (not JSON) so the model is free to interleave tool calls with a
+ * natural-language summary instead of being constrained to a JSON envelope.
+ */
+declare const WEBMCP_STOREFRONT_FLOW: RuntypeFlowConfig;
+
+/**
+ * Page-aware shopping assistant that can both *describe* and *act on* the page.
+ *
+ * It returns a small JSON envelope (like the shopping / storefront / bakery flows):
+ * a `text` field — markdown shown in the chat bubble — plus, when the shopper asks to
+ * add something, an `add_to_cart` action carrying the product's stable handle. The
+ * widget's flexible JSON stream parser renders `text`; the action manager parses the
+ * envelope and dispatches the action to the host's `addToCartHandler`.
+ *
+ * It is used by the smart-dom-reader demo to show two things at once:
+ *   1. a shadow-DOM-aware context provider feeds real page content (including products
+ *      inside shadow roots) into the prompt, grouped by on-page section; and
+ *   2. the assistant can drive the page across that same shadow boundary — the host's
+ *      handler resolves a `product` handle to a light-DOM *or* shadow-DOM button.
+ *
+ * The host injects `{{pageContext}}` via `inputs` — the widget's `contextProviders`
+ * output, moved from `payload.context` into `inputs` by a `requestMiddleware` so the
+ * proxy forwards it upstream. Each product line in that context carries a
+ * `product=<id>` handle the model copies verbatim into an `add_to_cart` action.
+ */
+declare const PAGE_CONTEXT_FLOW: RuntypeFlowConfig;
+
 /**
  * Stripe checkout helpers using the REST API
  * This approach works on all platforms including Cloudflare Workers, Vercel Edge, etc.
@@ -127,6 +174,17 @@ type ChatProxyOptions = {
     apiKey?: string;
     path?: string;
     allowedOrigins?: string[];
+    /**
+     * Reflect any request origin matching this pattern, in addition to the exact
+     * `allowedOrigins` list. Intended for Vercel **preview** deployments, whose
+     * URLs are per-branch and dynamic (`*-git-<branch>-<team>.vercel.app`) and so
+     * can't be enumerated. Defaults to `https://*.vercel.app`
+     * ({@link DEFAULT_PREVIEW_ORIGIN_PATTERN}); pass a custom `RegExp`, set the
+     * `PREVIEW_ORIGIN_PATTERN` env var, or pass `false` to disable. Independent of
+     * the `VERCEL_ENV === "preview"` runtime check, which always reflects the
+     * caller's origin when the proxy itself is a preview deployment.
+     */
+    previewOriginPattern?: RegExp | false;
     flowId?: string;
     flowConfig?: RuntypeFlowConfig;
     /**
@@ -149,4 +207,4 @@ type ChatProxyOptions = {
 declare const createChatProxyApp: (options?: ChatProxyOptions) => Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
 declare const createVercelHandler: (options?: ChatProxyOptions) => (req: Request) => Response | Promise<Response>;
 
-export { BAKERY_ASSISTANT_FLOW, COMPONENT_FLOW, CONVERSATIONAL_FLOW, type ChatProxyOptions, type CheckoutItem, type CheckoutSessionResponse, type CreateCheckoutSessionOptions, FORM_DIRECTIVE_FLOW, type FeedbackHandler, type FeedbackPayload, type RuntypeFlowConfig, type RuntypeFlowStep, SHOPPING_ASSISTANT_FLOW, SHOPPING_ASSISTANT_METADATA_FLOW, STOREFRONT_ASSISTANT_FLOW, createChatProxyApp, createCheckoutSession, createVercelHandler, createChatProxyApp as default };
+export { BAKERY_ASSISTANT_FLOW, COMPONENT_FLOW, CONVERSATIONAL_FLOW, type ChatProxyOptions, type CheckoutItem, type CheckoutSessionResponse, type CreateCheckoutSessionOptions, FORM_DIRECTIVE_FLOW, type FeedbackHandler, type FeedbackPayload, PAGE_CONTEXT_FLOW, type RuntypeFlowConfig, type RuntypeFlowStep, SHOPPING_ASSISTANT_FLOW, SHOPPING_ASSISTANT_METADATA_FLOW, STOREFRONT_ASSISTANT_FLOW, WEBMCP_STOREFRONT_FLOW, createChatProxyApp, createCheckoutSession, createVercelHandler, createChatProxyApp as default };

package/dist/index.d.ts

@@ -61,6 +61,53 @@ declare const BAKERY_ASSISTANT_FLOW: RuntypeFlowConfig;
  */
 declare const STOREFRONT_ASSISTANT_FLOW: RuntypeFlowConfig;
 
+/**
+ * WebMCP storefront flow for the "Switchback" trail/road running demo
+ * (`examples/embedded-app/webmcp-demo.html`).
+ *
+ * Unlike the other example flows, this agent owns **no** tools of its own. The
+ * demo page registers its tools on `document.modelContext` via WebMCP
+ * (`search_products`, `view_product`, `add_to_cart`, `remove_from_cart`,
+ * `apply_promo`); the widget snapshots them every turn and the proxy forwards
+ * them on the dispatch payload as `clientTools[]`. The Runtype runtime threads
+ * those into this prompt step's tool set, so the model calls them by name and
+ * the widget executes them **on the page**, posting results back via `/resume`.
+ *
+ * That means the agent definition that drives the WebMCP demo lives entirely in
+ * this repo — no hosted Runtype agent / client token required. The flow just
+ * needs a tool-capable model and a system prompt that knows how to shop the
+ * (page-provided) catalog.
+ *
+ * Model: `nemotron-3-ultra-550b-a55b`. WebMCP depends on the model
+ * emitting **native** tool calls (each surfaces as a `step_await` the widget
+ * resumes), so a tool-reliable model is required here. `responseFormat` is
+ * markdown (not JSON) so the model is free to interleave tool calls with a
+ * natural-language summary instead of being constrained to a JSON envelope.
+ */
+declare const WEBMCP_STOREFRONT_FLOW: RuntypeFlowConfig;
+
+/**
+ * Page-aware shopping assistant that can both *describe* and *act on* the page.
+ *
+ * It returns a small JSON envelope (like the shopping / storefront / bakery flows):
+ * a `text` field — markdown shown in the chat bubble — plus, when the shopper asks to
+ * add something, an `add_to_cart` action carrying the product's stable handle. The
+ * widget's flexible JSON stream parser renders `text`; the action manager parses the
+ * envelope and dispatches the action to the host's `addToCartHandler`.
+ *
+ * It is used by the smart-dom-reader demo to show two things at once:
+ *   1. a shadow-DOM-aware context provider feeds real page content (including products
+ *      inside shadow roots) into the prompt, grouped by on-page section; and
+ *   2. the assistant can drive the page across that same shadow boundary — the host's
+ *      handler resolves a `product` handle to a light-DOM *or* shadow-DOM button.
+ *
+ * The host injects `{{pageContext}}` via `inputs` — the widget's `contextProviders`
+ * output, moved from `payload.context` into `inputs` by a `requestMiddleware` so the
+ * proxy forwards it upstream. Each product line in that context carries a
+ * `product=<id>` handle the model copies verbatim into an `add_to_cart` action.
+ */
+declare const PAGE_CONTEXT_FLOW: RuntypeFlowConfig;
+
 /**
  * Stripe checkout helpers using the REST API
  * This approach works on all platforms including Cloudflare Workers, Vercel Edge, etc.
@@ -127,6 +174,17 @@ type ChatProxyOptions = {
     apiKey?: string;
     path?: string;
     allowedOrigins?: string[];
+    /**
+     * Reflect any request origin matching this pattern, in addition to the exact
+     * `allowedOrigins` list. Intended for Vercel **preview** deployments, whose
+     * URLs are per-branch and dynamic (`*-git-<branch>-<team>.vercel.app`) and so
+     * can't be enumerated. Defaults to `https://*.vercel.app`
+     * ({@link DEFAULT_PREVIEW_ORIGIN_PATTERN}); pass a custom `RegExp`, set the
+     * `PREVIEW_ORIGIN_PATTERN` env var, or pass `false` to disable. Independent of
+     * the `VERCEL_ENV === "preview"` runtime check, which always reflects the
+     * caller's origin when the proxy itself is a preview deployment.
+     */
+    previewOriginPattern?: RegExp | false;
     flowId?: string;
     flowConfig?: RuntypeFlowConfig;
     /**
@@ -149,4 +207,4 @@ type ChatProxyOptions = {
 declare const createChatProxyApp: (options?: ChatProxyOptions) => Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
 declare const createVercelHandler: (options?: ChatProxyOptions) => (req: Request) => Response | Promise<Response>;
 
-export { BAKERY_ASSISTANT_FLOW, COMPONENT_FLOW, CONVERSATIONAL_FLOW, type ChatProxyOptions, type CheckoutItem, type CheckoutSessionResponse, type CreateCheckoutSessionOptions, FORM_DIRECTIVE_FLOW, type FeedbackHandler, type FeedbackPayload, type RuntypeFlowConfig, type RuntypeFlowStep, SHOPPING_ASSISTANT_FLOW, SHOPPING_ASSISTANT_METADATA_FLOW, STOREFRONT_ASSISTANT_FLOW, createChatProxyApp, createCheckoutSession, createVercelHandler, createChatProxyApp as default };
+export { BAKERY_ASSISTANT_FLOW, COMPONENT_FLOW, CONVERSATIONAL_FLOW, type ChatProxyOptions, type CheckoutItem, type CheckoutSessionResponse, type CreateCheckoutSessionOptions, FORM_DIRECTIVE_FLOW, type FeedbackHandler, type FeedbackPayload, PAGE_CONTEXT_FLOW, type RuntypeFlowConfig, type RuntypeFlowStep, SHOPPING_ASSISTANT_FLOW, SHOPPING_ASSISTANT_METADATA_FLOW, STOREFRONT_ASSISTANT_FLOW, WEBMCP_STOREFRONT_FLOW, createChatProxyApp, createCheckoutSession, createVercelHandler, createChatProxyApp as default };

package/dist/index.js

@@ -13,7 +13,7 @@ var CONVERSATIONAL_FLOW = {
       type: "prompt",
       enabled: true,
       config: {
-        model: "mercury-2",
+        model: "nemotron-3-ultra-550b-a55b",
         responseFormat: "markdown",
         outputVariable: "prompt_result",
         userPrompt: "{{user_message}}",
@@ -35,7 +35,7 @@ var FORM_DIRECTIVE_FLOW = {
       type: "prompt",
       enabled: true,
       config: {
-        model: "mercury-2",
+        model: "nemotron-3-ultra-550b-a55b",
         reasoning: false,
         responseFormat: "JSON",
         outputVariable: "prompt_result",
@@ -96,7 +96,7 @@ var SHOPPING_ASSISTANT_FLOW = {
       type: "prompt",
       enabled: true,
       config: {
-        model: "mercury-2",
+        model: "nemotron-3-ultra-550b-a55b",
         reasoning: false,
         responseFormat: "JSON",
         outputVariable: "prompt_result",
@@ -169,7 +169,7 @@ var SHOPPING_ASSISTANT_METADATA_FLOW = {
       type: "prompt",
       enabled: true,
       config: {
-        model: "mercury-2",
+        model: "nemotron-3-ultra-550b-a55b",
         reasoning: false,
         responseFormat: "JSON",
         outputVariable: "prompt_result",
@@ -253,7 +253,7 @@ var COMPONENT_FLOW = {
       type: "prompt",
       enabled: true,
       config: {
-        model: "mercury-2",
+        model: "nemotron-3-ultra-550b-a55b",
         reasoning: false,
         responseFormat: "JSON",
         outputVariable: "prompt_result",
@@ -307,7 +307,7 @@ var BAKERY_ASSISTANT_FLOW = {
       type: "prompt",
       enabled: true,
       config: {
-        model: "mercury-2",
+        model: "nemotron-3-ultra-550b-a55b",
         reasoning: false,
         responseFormat: "JSON",
         outputVariable: "prompt_result",
@@ -426,7 +426,7 @@ var STOREFRONT_ASSISTANT_FLOW = {
       type: "prompt",
       enabled: true,
       config: {
-        model: "mercury-2",
+        model: "nemotron-3-ultra-550b-a55b",
         reasoning: false,
         responseFormat: "JSON",
         outputVariable: "prompt_result",
@@ -540,6 +540,91 @@ User asks "what's the best way to care for cashmere?":
   ]
 };
 
+// src/flows/webmcp-storefront.ts
+var WEBMCP_STOREFRONT_FLOW = {
+  name: "WebMCP Storefront Flow",
+  description: "Switchback running-store assistant \u2014 drives page-provided WebMCP tools (clientTools[])",
+  steps: [
+    {
+      id: "webmcp_storefront_prompt",
+      name: "WebMCP Storefront Prompt",
+      type: "prompt",
+      enabled: true,
+      config: {
+        model: "nemotron-3-ultra-550b-a55b",
+        reasoning: false,
+        responseFormat: "markdown",
+        outputVariable: "prompt_result",
+        userPrompt: "{{user_message}}",
+        systemPrompt: `You are the shopping assistant for **Switchback**, a trail & road running store. You help shoppers find gear, inspect products, and manage their cart.
+
+Brand voice: friendly, outdoorsy, concise. Knowledgeable about running shoes, apparel, and trail gear. No hype, no emoji. Keep replies short \u2014 a sentence or two around the actions you take.
+
+## Your tools come from the page
+
+This storefront exposes its own tools to you (search the catalog, view a product, add/remove from the cart, apply a promo code). Always **use the tools** to act on the catalog and cart \u2014 never invent products, SKUs, prices, or cart contents from memory.
+
+Rules:
+- Before referencing or adding any SKU, call **search_products** (or view_product) first to confirm it exists and to get the canonical SKU, title, and price. Do not guess SKUs.
+- When the shopper asks to add, remove, or change the cart, call the matching tool. The page renders the cart \u2014 after a cart change, confirm what changed and the running total from the tool's result, briefly.
+- If the shopper asks to add two (or more) specific items "at the same time" / "both", emit the add_to_cart calls together in one turn so they batch.
+- Only apply a promo code the shopper actually gives you; if it's rejected, say so and suggest they double-check the code.
+- If a tool reports an item wasn't found or isn't in the cart, relay that plainly and offer to search.
+
+After your tool calls resolve, summarize the outcome in plain language (what you found, what's in the cart, the total). Do not describe tools, JSON, SKUs, or the WebMCP mechanism to the shopper.`,
+        previousMessages: "{{messages}}"
+      }
+    }
+  ]
+};
+
+// src/flows/page-context.ts
+var PAGE_CONTEXT_FLOW = {
+  name: "Page Context Assistant Flow",
+  description: "Page-aware assistant that answers about the current page and can add its products to the cart.",
+  steps: [
+    {
+      id: "page_context_prompt",
+      name: "Prompt",
+      type: "prompt",
+      enabled: true,
+      config: {
+        model: "nemotron-3-ultra-550b-a55b",
+        responseFormat: "JSON",
+        outputVariable: "prompt_result",
+        userPrompt: "{{user_message}}",
+        systemPrompt: `You are a helpful shopping assistant embedded on a web page. Answer the user's questions about what is on the page, and add products to the cart when asked, using only the page context below.
+
+The context is collected live from the DOM and is grouped by on-page section (for example "Everyday picks" and "Featured drop"). It includes elements inside shadow roots that a basic page reader would miss \u2014 so trust it as the source of truth for what the shopper can see. Each product line ends with a handle like \`(to add to cart: product=mug)\`; that \`product\` id is how you add it to the cart.
+
+## Output: one JSON object only
+
+No markdown fences, no commentary before or after. Valid JSON only. Two response shapes are valid:
+
+### 1. Plain answer
+{"text": "...markdown..."}
+
+Use for any question about the page \u2014 what's for sale, what's in a section, prices, comparisons. The \`text\` is markdown and renders as a normal chat bubble.
+
+### 2. Add to cart
+{"action": "add_to_cart", "product": "<id>", "text": "Confirmation line."}
+
+Use only when the shopper explicitly asks to add a specific product ("add the mug", "I'll take the headphones"). Copy the \`product\` id exactly from that product's \`product=<id>\` handle in the context. The host clicks the matching Add-to-cart button \u2014 including buttons inside the shadow-DOM "Featured drop" \u2014 and updates the cart count itself; your \`text\` just confirms it and renders as a normal chat bubble.
+
+## Rules
+
+- Only mention products, prices, and sections that appear in the page context. If something is not there, say you do not see it on this page.
+- Never invent a \`product\` id. Use only the ids present in the context handles. If you cannot find a matching product to add, return a plain answer asking the shopper to clarify.
+- Be concise. Keep \`text\` short and use markdown where it helps.
+
+## Page context
+{{pageContext}}`,
+        previousMessages: "{{messages}}"
+      }
+    }
+  ]
+};
+
 // src/utils/stripe.ts
 var STRIPE_API_VERSION = "2026-03-25.dahlia";
 function parseStripeApiErrorBody(body) {
@@ -652,6 +737,24 @@ var isDevelopmentRuntime = () => {
   var _a;
   return ((_a = getRuntimeEnv()) == null ? void 0 : _a.NODE_ENV) === "development";
 };
+var isVercelPreviewRuntime = () => {
+  var _a;
+  return ((_a = getRuntimeEnv()) == null ? void 0 : _a.VERCEL_ENV) === "preview";
+};
+var DEFAULT_PREVIEW_ORIGIN_PATTERN = /^https:\/\/[a-z0-9-]+\.vercel\.app$/i;
+var resolvePreviewOriginPattern = (option) => {
+  var _a;
+  if (option === false) return null;
+  if (option instanceof RegExp) return option;
+  const envPattern = (_a = getRuntimeEnv()) == null ? void 0 : _a.PREVIEW_ORIGIN_PATTERN;
+  if (envPattern) {
+    try {
+      return new RegExp(envPattern);
+    } catch {
+    }
+  }
+  return DEFAULT_PREVIEW_ORIGIN_PATTERN;
+};
 var DEFAULT_FLOW = {
   name: "Streaming Prompt Flow",
   description: "Streaming chat generated by the widget",
@@ -662,7 +765,7 @@ var DEFAULT_FLOW = {
       type: "prompt",
       enabled: true,
       config: {
-        model: "mercury-2",
+        model: "nemotron-3-ultra-550b-a55b",
         responseFormat: "markdown",
         outputVariable: "prompt_result",
         userPrompt: "{{user_message}}",
@@ -677,9 +780,12 @@ var DEFAULT_FLOW = {
     }
   ]
 };
-var withCors = (allowedOrigins) => async (c, next) => {
+var withCors = (allowedOrigins, previewOriginPattern) => async (c, next) => {
   const origin = c.req.header("origin");
   const isDevelopment = isDevelopmentRuntime();
+  const isPreviewOrigin = Boolean(
+    origin && (isVercelPreviewRuntime() || previewOriginPattern !== null && previewOriginPattern.test(origin))
+  );
   let corsOrigin;
   if (!allowedOrigins || allowedOrigins.length === 0) {
     corsOrigin = origin || "*";
@@ -687,6 +793,8 @@ var withCors = (allowedOrigins) => async (c, next) => {
     corsOrigin = origin || "*";
   } else if (isDevelopment && origin) {
     corsOrigin = origin;
+  } else if (isPreviewOrigin && origin) {
+    corsOrigin = origin;
   } else {
     if (c.req.method === "OPTIONS") {
       return c.json({ error: "CORS policy violation: origin not allowed" }, 403);
@@ -714,7 +822,10 @@ var createChatProxyApp = (options = {}) => {
   const path = (_a = options.path) != null ? _a : DEFAULT_PATH;
   const feedbackPath = (_b = options.feedbackPath) != null ? _b : "/api/feedback";
   const upstream = (_c = options.upstreamUrl) != null ? _c : DEFAULT_ENDPOINT;
-  app.use("*", withCors(options.allowedOrigins));
+  const previewOriginPattern = resolvePreviewOriginPattern(
+    options.previewOriginPattern
+  );
+  app.use("*", withCors(options.allowedOrigins, previewOriginPattern));
   app.post(feedbackPath, async (c) => {
     var _a2, _b2, _c2;
     let payload;
@@ -819,6 +930,9 @@ var createChatProxyApp = (options = {}) => {
       } else {
         runtypePayload.flow = flowConfig;
       }
+      if (Array.isArray(clientPayload.clientTools) && clientPayload.clientTools.length > 0) {
+        runtypePayload.clientTools = clientPayload.clientTools;
+      }
     }
     if (isDevelopment) {
       console.log(`
@@ -916,9 +1030,11 @@ export {
   COMPONENT_FLOW,
   CONVERSATIONAL_FLOW,
   FORM_DIRECTIVE_FLOW,
+  PAGE_CONTEXT_FLOW,
   SHOPPING_ASSISTANT_FLOW,
   SHOPPING_ASSISTANT_METADATA_FLOW,
   STOREFRONT_ASSISTANT_FLOW,
+  WEBMCP_STOREFRONT_FLOW,
   createChatProxyApp,
   createCheckoutSession,
   createVercelHandler,