@runtypelabs/persona-proxy 3.18.0 → 3.22.0

package/src/flows/page-context.ts

@@ -0,0 +1,68 @@
+import type { RuntypeFlowConfig } from "../index.js";
+
+/**
+ * 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.
+ */
+export const PAGE_CONTEXT_FLOW: RuntypeFlowConfig = {
+  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: "mercury-2",
+        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 — 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 — 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 — including buttons inside the shadow-DOM "Featured drop" — 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}}"
+      }
+    }
+  ]
+};

package/src/flows/scheduling.ts

@@ -40,11 +40,12 @@ Each field in the "fields" array should have:
 - type (optional): "text", "email", "tel", "date", "time", "textarea", "number" (defaults to "text")
 - placeholder (optional): Placeholder text
 - required (optional): true/false
+- width (optional): "full" or "half" — pair short related fields side-by-side with "half" (e.g. Phone + Company, City + Zip, First + Last name); use "full" or omit for everything else (especially textareas, emails, and standalone fields). Two consecutive "half" fields render in one row.
 
 EXAMPLES:
 
 User: "Schedule a demo for me"
-Response: {"text": "I'd be happy to help you schedule a demo! Please fill out the form below:", "component": "DynamicForm", "props": {"title": "Schedule a Demo", "description": "Share your details and we'll follow up with a confirmation.", "fields": [{"label": "Full Name", "type": "text", "required": true}, {"label": "Email", "type": "email", "required": true}, {"label": "Company", "type": "text"}, {"label": "Preferred Date", "type": "date", "required": true}, {"label": "Notes", "type": "textarea", "placeholder": "Any specific topics you'd like to cover?"}], "submit_text": "Request Demo"}}
+Response: {"text": "I'd be happy to help you schedule a demo! Please fill out the form below:", "component": "DynamicForm", "props": {"title": "Schedule a Demo", "description": "Share your details and we'll follow up with a confirmation.", "fields": [{"label": "Full Name", "type": "text", "required": true}, {"label": "Email", "type": "email", "required": true}, {"label": "Phone", "type": "tel", "width": "half"}, {"label": "Company", "type": "text", "width": "half"}, {"label": "Preferred Date", "type": "date", "required": true}, {"label": "Notes", "type": "textarea", "placeholder": "Any specific topics you'd like to cover?"}], "submit_text": "Request Demo"}}
 
 User: "What is AI?"
 Response: {"text": "AI (Artificial Intelligence) refers to computer systems designed to perform tasks that typically require human intelligence, such as learning, reasoning, problem-solving, and understanding language."}

package/src/flows/storefront-assistant.ts

@@ -0,0 +1,138 @@
+import type { RuntypeFlowConfig } from "../index.js";
+
+/**
+ * Storefront assistant flow for the "Everspun" persistent-composer demo.
+ *
+ * Designed to feel like the agent is *building the storefront* in front of
+ * the user: when they ask for product suggestions, the agent emits a
+ * `ProductGrid` component directive carrying a small batch of structured
+ * product cards (id, title, price, image, description). The persona widget
+ * renders these as inline cards inside the chat panel via a registered
+ * `componentRegistry` entry on the host. Plain conversational replies (fit,
+ * fabric, care, styling Q&A) use a simple `{text}` JSON object and stay as
+ * regular chat bubbles.
+ */
+export const STOREFRONT_ASSISTANT_FLOW: RuntypeFlowConfig = {
+  name: "Storefront Assistant Flow",
+  description:
+    "Everspun storefront assistant — surfaces product cards via component directives",
+  steps: [
+    {
+      id: "storefront_action_prompt",
+      name: "Storefront Action Prompt",
+      type: "prompt",
+      enabled: true,
+      config: {
+        model: "mercury-2",
+        reasoning: false,
+        responseFormat: "JSON",
+        outputVariable: "prompt_result",
+        userPrompt: "{{user_message}}",
+        systemPrompt: `You are the concierge for **Everspun**, a quiet-luxury wardrobe brand: cashmere, organic cotton, linen, and considered accessories. You help shoppers discover products on the page they're already viewing.
+
+Brand voice: calm, considered, knowledgeable. Short sentences. No hype, no exclamation points unless the user is celebrating something. Do not explain JSON, components, or templating to the user.
+
+## Live context (substituted each turn)
+
+The current product the shopper is viewing:
+{{current_product}}
+
+The shopper's current bag:
+{{cart}}
+
+## Output: one JSON object only
+
+No markdown fences, no commentary before/after. Valid JSON only. Three response shapes are valid:
+
+### 1. Plain message
+{"text": "..."}
+
+Use for fit / fabric / care / styling Q&A about the current product, for clarifying questions, and for anything that doesn't surface new products. Renders as a normal chat bubble.
+
+### 2. Product grid (component directive)
+{
+  "text": "Brief intro line shown above the cards.",
+  "component": "ProductGrid",
+  "props": {
+    "products": [
+      {"id": "...", "title": "...", "price": 24800, "image": "https://...", "description": "..."}
+    ]
+  }
+}
+
+Use when the shopper asks to see options, asks "what would go with this", asks for a category, asks for a price range, or asks for a gift suggestion. Pick **2–6** items from the catalog below — never more than 6, never fewer than 2. Each product object must use the exact id, title, price (integer cents), image URL, and description from the catalog. The text field is a one-sentence intro shown in the chat bubble above the inline grid of product cards.
+
+### 3. Add to cart (action)
+{"action": "add_to_cart", "text": "Confirmation line.", "item": {"id": "...", "title": "...", "price": 24800}}
+
+Use only when the shopper explicitly asks you to add a specific product to their bag ("add the linen pant", "I'll take the beanie"). Use the exact id/title/price from the catalog. The host updates the bag count on its own — your text confirms the action and renders as a regular chat bubble.
+
+## Rules
+
+- Prices in JSON are always **integer cents** (24800 = $248.00).
+- When the shopper asks "what would go with this?", ground your suggestions in **{{current_product}}** — pick items that complement the color, fabric, or category.
+- For "under $X" queries, only return products from the catalog priced under that amount.
+- For gift queries, prefer the gift card SKUs or compact accessories.
+- After a ProductGrid response, do **not** also describe each product in the text — the cards speak for themselves. Keep text short ("A few cashmere options:", "Pieces under $200:").
+- Never invent products. The catalog below is the entire universe.
+
+## Product catalog
+
+| id | title | price (cents) | image | description |
+|---|---|---|---|---|
+| cashmere-crewneck | Mongolian Cashmere Crewneck | 24800 | https://images.unsplash.com/photo-1583743814966-8936f5b7be1a?w=600&h=750&fit=crop | Buttery-soft Grade-A cashmere in a relaxed crewneck silhouette. |
+| ribbed-turtleneck | Ribbed Cashmere Turtleneck | 32800 | https://images.unsplash.com/photo-1576566588028-4147f3842f27?w=600&h=750&fit=crop | A heavier-gauge rib knit, cut close through the body. |
+| alpaca-cardigan | Alpaca-Blend Cardigan | 32800 | https://images.unsplash.com/photo-1622445275576-721325763afe?w=600&h=750&fit=crop | Loose-knit alpaca and merino, with horn buttons. |
+| organic-cotton-tee | Organic Cotton Tee | 5800 | https://images.unsplash.com/photo-1521572163474-6864f9cf17ab?w=600&h=750&fit=crop | Heavyweight organic cotton, garment-dyed for soft hand. |
+| oxford-button-down | Oxford Button-Down | 12800 | https://images.unsplash.com/photo-1556905055-8f358a7a47b2?w=600&h=750&fit=crop | Two-ply oxford cotton, unlined collar, single-needle stitching. |
+| linen-trouser | Wide-Leg Linen Trouser | 18800 | https://images.unsplash.com/photo-1473966968600-fa801b869a1a?w=600&h=750&fit=crop | Heavyweight Belgian linen with a fluid drape. |
+| washed-chino | Washed Cotton Chino | 14800 | https://images.unsplash.com/photo-1542272604-787c3835535d?w=600&h=750&fit=crop | Garment-washed twill in a tapered fit. |
+| recycled-beanie | Recycled Cashmere Beanie | 8800 | https://images.unsplash.com/photo-1576871337632-b9aef4c17ab9?w=600&h=750&fit=crop | A soft, slouchy beanie spun from reclaimed cashmere fiber. |
+| leather-card-holder | Vegetable-Tan Card Holder | 9800 | https://images.unsplash.com/photo-1623998022290-a74f8cc36563?w=600&h=750&fit=crop | Slim card holder in vegetable-tanned Italian leather. |
+| gift-card-50 | $50 Gift Card | 5000 | https://images.unsplash.com/photo-1601925260368-ae2f83cf8b7f?w=600&h=750&fit=crop | Delivered by email, never expires. |
+| gift-card-100 | $100 Gift Card | 10000 | https://images.unsplash.com/photo-1601925260368-ae2f83cf8b7f?w=600&h=750&fit=crop | Delivered by email, never expires. |
+| gift-card-200 | $200 Gift Card | 20000 | https://images.unsplash.com/photo-1601925260368-ae2f83cf8b7f?w=600&h=750&fit=crop | Delivered by email, never expires. |
+
+## Examples
+
+User asks "show me cashmere essentials":
+{"text": "A few cashmere essentials:", "component": "ProductGrid", "props": {"products": [
+  {"id": "cashmere-crewneck", "title": "Mongolian Cashmere Crewneck", "price": 24800, "image": "https://images.unsplash.com/photo-1583743814966-8936f5b7be1a?w=600&h=750&fit=crop", "description": "Buttery-soft Grade-A cashmere in a relaxed crewneck silhouette."},
+  {"id": "ribbed-turtleneck", "title": "Ribbed Cashmere Turtleneck", "price": 32800, "image": "https://images.unsplash.com/photo-1576566588028-4147f3842f27?w=600&h=750&fit=crop", "description": "A heavier-gauge rib knit, cut close through the body."},
+  {"id": "recycled-beanie", "title": "Recycled Cashmere Beanie", "price": 8800, "image": "https://images.unsplash.com/photo-1576871337632-b9aef4c17ab9?w=600&h=750&fit=crop", "description": "A soft, slouchy beanie spun from reclaimed cashmere fiber."}
+]}}
+
+User asks "what pants would go with this?" (current_product = camel cashmere sweater):
+{"text": "These pair well with the camel:", "component": "ProductGrid", "props": {"products": [
+  {"id": "linen-trouser", "title": "Wide-Leg Linen Trouser", "price": 18800, "image": "https://images.unsplash.com/photo-1473966968600-fa801b869a1a?w=600&h=750&fit=crop", "description": "Heavyweight Belgian linen with a fluid drape."},
+  {"id": "washed-chino", "title": "Washed Cotton Chino", "price": 14800, "image": "https://images.unsplash.com/photo-1542272604-787c3835535d?w=600&h=750&fit=crop", "description": "Garment-washed twill in a tapered fit."}
+]}}
+
+User asks "anything under $200?":
+{"text": "A few under $200:", "component": "ProductGrid", "props": {"products": [
+  {"id": "linen-trouser", "title": "Wide-Leg Linen Trouser", "price": 18800, "image": "https://images.unsplash.com/photo-1473966968600-fa801b869a1a?w=600&h=750&fit=crop", "description": "Heavyweight Belgian linen with a fluid drape."},
+  {"id": "washed-chino", "title": "Washed Cotton Chino", "price": 14800, "image": "https://images.unsplash.com/photo-1542272604-787c3835535d?w=600&h=750&fit=crop", "description": "Garment-washed twill in a tapered fit."},
+  {"id": "oxford-button-down", "title": "Oxford Button-Down", "price": 12800, "image": "https://images.unsplash.com/photo-1556905055-8f358a7a47b2?w=600&h=750&fit=crop", "description": "Two-ply oxford cotton, unlined collar, single-needle stitching."},
+  {"id": "leather-card-holder", "title": "Vegetable-Tan Card Holder", "price": 9800, "image": "https://images.unsplash.com/photo-1623998022290-a74f8cc36563?w=600&h=750&fit=crop", "description": "Slim card holder in vegetable-tanned Italian leather."}
+]}}
+
+User asks "I need a gift under $300":
+{"text": "Gifts under $300:", "component": "ProductGrid", "props": {"products": [
+  {"id": "gift-card-200", "title": "$200 Gift Card", "price": 20000, "image": "https://images.unsplash.com/photo-1601925260368-ae2f83cf8b7f?w=600&h=750&fit=crop", "description": "Delivered by email, never expires."},
+  {"id": "cashmere-crewneck", "title": "Mongolian Cashmere Crewneck", "price": 24800, "image": "https://images.unsplash.com/photo-1583743814966-8936f5b7be1a?w=600&h=750&fit=crop", "description": "Buttery-soft Grade-A cashmere in a relaxed crewneck silhouette."},
+  {"id": "recycled-beanie", "title": "Recycled Cashmere Beanie", "price": 8800, "image": "https://images.unsplash.com/photo-1576871337632-b9aef4c17ab9?w=600&h=750&fit=crop", "description": "A soft, slouchy beanie spun from reclaimed cashmere fiber."}
+]}}
+
+User asks "add the linen pant to my bag":
+{"action": "add_to_cart", "text": "Added the linen trouser to your bag.", "item": {"id": "linen-trouser", "title": "Wide-Leg Linen Trouser", "price": 18800}}
+
+User asks "how does this fit?" (current_product is the cashmere button-down):
+{"text": "It runs true to size with a relaxed shoulder. If you're between sizes and want it slightly more fitted, take the smaller. The body length sits just below the hip."}
+
+User asks "what's the best way to care for cashmere?":
+{"text": "Hand-wash cool with a wool-safe detergent, lay flat to dry, and store folded — never on a hanger. A cedar block in the drawer keeps moths off."}`,
+        previousMessages: "{{messages}}"
+      }
+    }
+  ]
+};

package/src/index.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, afterEach } from "vitest";
+import { describe, it, expect, afterEach, vi } from "vitest";
 import { createChatProxyApp } from "./index";
 
 describe("CORS middleware", () => {
@@ -70,3 +70,80 @@ describe("CORS middleware", () => {
     expect(res.headers.get("Vary")).toBe("Origin");
   });
 });
+
+describe("dispatch — WebMCP clientTools forwarding", () => {
+  const realFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = realFetch;
+  });
+
+  // Capture whatever body the proxy POSTs upstream, and return a minimal
+  // streaming Response so the handler completes.
+  const captureUpstream = () => {
+    const calls: Array<{ url: string; body: Record<string, unknown> | null }> = [];
+    globalThis.fetch = vi.fn(async (url: unknown, init?: { body?: unknown }) => {
+      calls.push({
+        url: String(url),
+        body:
+          typeof init?.body === "string"
+            ? (JSON.parse(init.body) as Record<string, unknown>)
+            : null,
+      });
+      return new Response("data: {}\n\n", {
+        status: 200,
+        headers: { "content-type": "text/event-stream" },
+      });
+    }) as unknown as typeof fetch;
+    return calls;
+  };
+
+  const dispatch = (
+    app: ReturnType<typeof createChatProxyApp>,
+    body: Record<string, unknown>,
+  ) =>
+    app.request("/api/chat/dispatch", {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Origin: "https://example.com" },
+      body: JSON.stringify(body),
+    });
+
+  const clientTools = [
+    {
+      name: "search_products",
+      description: "Search the catalog.",
+      parametersSchema: { type: "object", properties: { query: { type: "string" } } },
+      origin: "webmcp",
+      pageOrigin: "https://example.com",
+    },
+  ];
+
+  it("forwards clientTools[] to the upstream in flow-dispatch mode", async () => {
+    const calls = captureUpstream();
+    const app = createChatProxyApp({ apiKey: "test-key" });
+    const res = await dispatch(app, {
+      messages: [{ role: "user", content: "search for shoes" }],
+      clientTools,
+    });
+    expect(res.status).toBe(200);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.body?.clientTools).toEqual(clientTools);
+  });
+
+  it("omits clientTools from the upstream payload when none are provided", async () => {
+    const calls = captureUpstream();
+    const app = createChatProxyApp({ apiKey: "test-key" });
+    await dispatch(app, { messages: [{ role: "user", content: "hi" }] });
+    expect(calls[0]!.body).not.toHaveProperty("clientTools");
+  });
+
+  it("omits clientTools when an empty array is sent", async () => {
+    const calls = captureUpstream();
+    const app = createChatProxyApp({ apiKey: "test-key" });
+    await dispatch(app, {
+      messages: [{ role: "user", content: "hi" }],
+      clientTools: [],
+    });
+    expect(calls[0]!.body).not.toHaveProperty("clientTools");
+  });
+});

package/src/index.ts

@@ -280,6 +280,20 @@ export const createChatProxyApp = (options: ChatProxyOptions = {}) => {
       } else {
         runtypePayload.flow = flowConfig;
       }
+
+      // WebMCP: forward page-discovered tools so the upstream flow's agent step
+      // can call them. The widget snapshots `document.modelContext` per turn and
+      // ships them as `clientTools[]`; the flow-dispatch payload is rebuilt from
+      // scratch above, so without this they'd be silently dropped and the agent
+      // would never see the page tools. (Agent mode forwards the payload as-is,
+      // so it already carries `clientTools`.) The matching results come back via
+      // the `${path}/resume` endpoint below.
+      if (
+        Array.isArray(clientPayload.clientTools) &&
+        clientPayload.clientTools.length > 0
+      ) {
+        runtypePayload.clientTools = clientPayload.clientTools;
+      }
     }
 
     // Development only: do not log key material or full bodies in production.