@runtypelabs/persona-proxy 3.22.0 → 3.31.0

package/src/flows/webmcp-storefront.ts

@@ -0,0 +1,63 @@
+import type { RuntypeFlowConfig } from "../index.js";
+
+/**
+ * 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.
+ */
+export const WEBMCP_STOREFRONT_FLOW: RuntypeFlowConfig = {
+  name: "WebMCP Storefront Flow",
+  description:
+    "Switchback running-store assistant — 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 — 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 — 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 — 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.
+- Tool results include product \`imageUrl\` and \`imageAlt\`. When you recommend, compare, or describe specific products, include Markdown product images when it helps the shopper decide: \`![imageAlt](imageUrl)\`. Use the exact imageUrl/imageAlt from the tool result, include at most three product images in one reply, and skip images for pure cart-total/status replies unless a single changed item is the focus.
+
+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}}"
+      }
+    }
+  ]
+};

package/src/index.test.ts

@@ -71,6 +71,101 @@ describe("CORS middleware", () => {
   });
 });
 
+describe("CORS preview origins", () => {
+  const savedNodeEnv = process.env.NODE_ENV;
+  const savedVercelEnv = process.env.VERCEL_ENV;
+  const savedPattern = process.env.PREVIEW_ORIGIN_PATTERN;
+
+  afterEach(() => {
+    process.env.NODE_ENV = savedNodeEnv;
+    if (savedVercelEnv === undefined) delete process.env.VERCEL_ENV;
+    else process.env.VERCEL_ENV = savedVercelEnv;
+    if (savedPattern === undefined) delete process.env.PREVIEW_ORIGIN_PATTERN;
+    else process.env.PREVIEW_ORIGIN_PATTERN = savedPattern;
+  });
+
+  const preflight = (app: ReturnType<typeof createChatProxyApp>, origin: string) =>
+    app.request("/api/chat/dispatch", { method: "OPTIONS", headers: { Origin: origin } });
+
+  it("reflects a *.vercel.app preview origin not in the allowlist (default pattern)", async () => {
+    process.env.NODE_ENV = "production";
+    delete process.env.VERCEL_ENV;
+    const app = createChatProxyApp({ allowedOrigins: ["https://good.com"] });
+    const res = await preflight(app, "https://persona-git-feature-x-runtype.vercel.app");
+    expect(res.status).toBe(204);
+    expect(res.headers.get("Access-Control-Allow-Origin")).toBe(
+      "https://persona-git-feature-x-runtype.vercel.app"
+    );
+  });
+
+  it("does not match preview-apex look-alikes", async () => {
+    process.env.NODE_ENV = "production";
+    delete process.env.VERCEL_ENV;
+    const app = createChatProxyApp({ allowedOrigins: ["https://good.com"] });
+    // Apex spoofed as a deeper subdomain of an attacker domain.
+    const spoof = await preflight(app, "https://x.vercel.app.evil.com");
+    expect(spoof.status).toBe(403);
+    // Hyphen instead of dot before the apex.
+    const hyphen = await preflight(app, "https://evil-vercel.app");
+    expect(hyphen.status).toBe(403);
+  });
+
+  it("allows extra preview domains via PREVIEW_ORIGIN_PATTERN env", async () => {
+    process.env.NODE_ENV = "production";
+    delete process.env.VERCEL_ENV;
+    process.env.PREVIEW_ORIGIN_PATTERN = "^https://[a-z0-9-]+\\.preview\\.example\\.com$";
+    const app = createChatProxyApp({ allowedOrigins: ["https://good.com"] });
+    const res = await preflight(app, "https://pr-42.preview.example.com");
+    expect(res.status).toBe(204);
+    expect(res.headers.get("Access-Control-Allow-Origin")).toBe(
+      "https://pr-42.preview.example.com"
+    );
+  });
+
+  it("still rejects a non-preview, non-allowlisted origin in production", async () => {
+    process.env.NODE_ENV = "production";
+    delete process.env.VERCEL_ENV;
+    const app = createChatProxyApp({ allowedOrigins: ["https://good.com"] });
+    const res = await preflight(app, "https://evil.com");
+    expect(res.status).toBe(403);
+  });
+
+  it("disables preview reflection with previewOriginPattern: false", async () => {
+    process.env.NODE_ENV = "production";
+    delete process.env.VERCEL_ENV;
+    const app = createChatProxyApp({
+      allowedOrigins: ["https://good.com"],
+      previewOriginPattern: false,
+    });
+    const res = await preflight(app, "https://persona-git-feature-x-runtype.vercel.app");
+    expect(res.status).toBe(403);
+  });
+
+  it("honors a custom previewOriginPattern", async () => {
+    process.env.NODE_ENV = "production";
+    delete process.env.VERCEL_ENV;
+    const app = createChatProxyApp({
+      allowedOrigins: ["https://good.com"],
+      previewOriginPattern: /^https:\/\/preview\.example\.com$/,
+    });
+    const ok = await preflight(app, "https://preview.example.com");
+    expect(ok.status).toBe(204);
+    expect(ok.headers.get("Access-Control-Allow-Origin")).toBe("https://preview.example.com");
+    // The default *.vercel.app no longer applies once a custom pattern is set.
+    const vercel = await preflight(app, "https://persona-git-x-runtype.vercel.app");
+    expect(vercel.status).toBe(403);
+  });
+
+  it("reflects any origin when the proxy itself is a Vercel preview runtime", async () => {
+    process.env.NODE_ENV = "production";
+    process.env.VERCEL_ENV = "preview";
+    const app = createChatProxyApp({ allowedOrigins: ["https://good.com"] });
+    const res = await preflight(app, "https://anything.example.org");
+    expect(res.status).toBe(204);
+    expect(res.headers.get("Access-Control-Allow-Origin")).toBe("https://anything.example.org");
+  });
+});
+
 describe("dispatch — WebMCP clientTools forwarding", () => {
   const realFetch = globalThis.fetch;
 

package/src/index.ts

@@ -40,6 +40,17 @@ export 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;
   /**
@@ -74,6 +85,56 @@ const getRuntimeEnv = (): RuntimeEnv | undefined => {
 const isDevelopmentRuntime = (): boolean =>
   getRuntimeEnv()?.NODE_ENV === "development";
 
+/**
+ * True when this proxy is itself running as a Vercel **preview** deployment
+ * (`VERCEL_ENV === "preview"`). Vercel sets `NODE_ENV=production` for both
+ * production and preview, so `isDevelopmentRuntime()` can't distinguish them —
+ * `VERCEL_ENV` is the only signal. Preview deployments get per-branch, dynamic
+ * URLs (`*-git-<branch>-<team>.vercel.app`) that can't be enumerated in a
+ * static `allowedOrigins` list, so for CORS we treat a preview runtime like
+ * development and reflect the caller's origin. Safe when `process` is missing.
+ */
+const isVercelPreviewRuntime = (): boolean =>
+  getRuntimeEnv()?.VERCEL_ENV === "preview";
+
+/**
+ * Default origin pattern treated as a Vercel preview/app origin: any
+ * `https://<sub>.vercel.app`. When a *production* proxy is called by a static
+ * preview site (a different, dynamic `*.vercel.app` origin), the origin won't be
+ * in `allowedOrigins`; matching this pattern lets the proxy reflect it so
+ * per-branch preview sites work without enumerating their URLs. To allow other
+ * preview domains, supply your own pattern via the `previewOriginPattern` option
+ * or the `PREVIEW_ORIGIN_PATTERN` env regex; disable with
+ * `previewOriginPattern: false`.
+ *
+ * The `$`-anchored apex prevents look-alikes like `https://x.vercel.app.evil.com`
+ * from matching.
+ */
+const DEFAULT_PREVIEW_ORIGIN_PATTERN = /^https:\/\/[a-z0-9-]+\.vercel\.app$/i;
+
+/**
+ * Resolve the preview-origin pattern from options/env. Precedence:
+ * explicit `options.previewOriginPattern` (a `RegExp`, or `false` to disable) →
+ * `PREVIEW_ORIGIN_PATTERN` env (compiled as a `RegExp`; ignored if invalid) →
+ * {@link DEFAULT_PREVIEW_ORIGIN_PATTERN}.
+ */
+const resolvePreviewOriginPattern = (
+  option: RegExp | false | undefined
+): RegExp | null => {
+  if (option === false) return null;
+  if (option instanceof RegExp) return option;
+  const envPattern = getRuntimeEnv()?.PREVIEW_ORIGIN_PATTERN;
+  if (envPattern) {
+    try {
+      return new RegExp(envPattern);
+    } catch {
+      // Invalid env regex — fall back to the default rather than throwing at
+      // app-construction time.
+    }
+  }
+  return DEFAULT_PREVIEW_ORIGIN_PATTERN;
+};
+
 const DEFAULT_FLOW: RuntypeFlowConfig = {
   name: "Streaming Prompt Flow",
   description: "Streaming chat generated by the widget",
@@ -84,7 +145,7 @@ const DEFAULT_FLOW: RuntypeFlowConfig = {
       type: "prompt",
       enabled: true,
       config: {
-        model: "mercury-2",
+        model: "nemotron-3-ultra-550b-a55b",
         responseFormat: "markdown",
         outputVariable: "prompt_result",
         userPrompt: "{{user_message}}",
@@ -101,11 +162,20 @@ const DEFAULT_FLOW: RuntypeFlowConfig = {
 };
 
 const withCors =
-  (allowedOrigins: string[] | undefined) =>
+  (allowedOrigins: string[] | undefined, previewOriginPattern: RegExp | null) =>
     async (c: Context, next: () => Promise<void>) => {
       const origin = c.req.header("origin");
       const isDevelopment = isDevelopmentRuntime();
-      
+      // A request is preview-allowed when either the proxy itself is a Vercel
+      // preview deployment (reflect any caller, like dev) or the caller's origin
+      // matches the configured preview pattern (e.g. a `*.vercel.app` preview
+      // site calling a production proxy). Both reflect the actual origin.
+      const isPreviewOrigin = Boolean(
+        origin &&
+          (isVercelPreviewRuntime() ||
+            (previewOriginPattern !== null && previewOriginPattern.test(origin)))
+      );
+
       // Determine the CORS origin to allow
       let corsOrigin: string;
       if (!allowedOrigins || allowedOrigins.length === 0) {
@@ -118,6 +188,10 @@ const withCors =
         // In development, allow the actual origin even if not in the list
         // This helps with local development where ports might vary
         corsOrigin = origin;
+      } else if (isPreviewOrigin && origin) {
+        // Vercel preview deployment (or a configured preview origin): reflect the
+        // dynamic per-branch origin that can't be enumerated in allowedOrigins.
+        corsOrigin = origin;
       } else {
         // Production: origin not allowed - reject by not setting CORS headers
         // Return error for preflight, or continue without CORS headers
@@ -152,7 +226,10 @@ export const createChatProxyApp = (options: ChatProxyOptions = {}) => {
   const feedbackPath = options.feedbackPath ?? "/api/feedback";
   const upstream = options.upstreamUrl ?? DEFAULT_ENDPOINT;
 
-  app.use("*", withCors(options.allowedOrigins));
+  const previewOriginPattern = resolvePreviewOriginPattern(
+    options.previewOriginPattern
+  );
+  app.use("*", withCors(options.allowedOrigins, previewOriginPattern));
 
   // Feedback endpoint for collecting upvote/downvote data
   app.post(feedbackPath, async (c) => {