@noodleseed/agent-kit 0.14.0 → 0.16.0

package/skills/claude-code/examples/acme-bistro/noodle.json

@@ -0,0 +1,5 @@
+{
+  "entrypoint": "src/server.ts",
+  "name": "acme-bistro",
+  "template": "widget"
+}

package/skills/claude-code/examples/acme-bistro/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "acme-bistro",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "validate": "noodle validate",
+    "dev": "noodle dev",
+    "deploy": "noodle deploy"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "latest",
+    "@noodleseed/one": "latest",
+    "react": "latest",
+    "react-dom": "latest",
+    "vite": "latest",
+    "vitest": "latest"
+  }
+}

package/skills/claude-code/examples/acme-bistro/src/helpers.ts

@@ -0,0 +1,7 @@
+import type { ServerDefinition } from '@noodleseed/one';
+import { generateHelpers } from '@noodleseed/one/react';
+
+export type AppType = ServerDefinition;
+
+export const { useCallTool, useLayout, useOpenExternal, useToolInfo, useViewState } =
+  generateHelpers<AppType>();

package/skills/claude-code/examples/acme-bistro/src/server.ts

@@ -0,0 +1,149 @@
+import { annotations, server, tool, toolForWidget, toolWithWidget, z } from '@noodleseed/one';
+
+// Acme Bistro is a fictional restaurant. This app is deliberately END-TO-END: the customer browses the
+// menu and builds the order in chat, and the order completes in chat — only *payment* hands off, via a
+// checkout deep link (the card never touches the app). It is the flagship for the end-to-end pattern.
+//
+// Authoring notes:
+// - A tool `fulfil` is *recorded*, not run as live JS. Inline inputs directly as `${input.x}` into
+//   output strings; do not transform them (no arithmetic/encode/filter) or substitution breaks. The
+//   cart total is summed in the widget (live React), not in a `fulfil`. The menu below is static data.
+
+const menu = [
+  { id: 'stone_pizza', name: 'Stone-baked Margherita', price: 14, kind: 'Mains' },
+  { id: 'roast_bowl', name: 'Harvest Roast Bowl', price: 13, kind: 'Mains' },
+  { id: 'house_salad', name: 'House Garden Salad', price: 11, kind: 'Starters' },
+  { id: 'lemon_tart', name: 'Lemon Tart', price: 8, kind: 'Desserts' },
+  { id: 'sparkling', name: 'Sparkling Water', price: 4, kind: 'Drinks' },
+] as const;
+
+const itemId = z.enum(['stone_pizza', 'roast_bowl', 'house_salad', 'lemon_tart', 'sparkling']);
+
+const menuItemOutput = z.object({
+  id: z.string(),
+  name: z.string(),
+  price: z.number(),
+  kind: z.string(),
+});
+
+// Tool annotations for host planners: the menu read is read-only; cart edits are local writes; checkout
+// opens an external (payment) link.
+const readOnly = annotations.readOnly();
+const localWrite = annotations.localAction({ destructive: false });
+const openLink = annotations.openAction();
+
+export default server(
+  'acme_bistro',
+  {
+    title: 'Acme Bistro',
+    version: '1.0.0',
+    branding: {
+      name: 'Acme Bistro',
+      accent: '#B91C1C',
+      surface: '#FEF3F2',
+      surfaceDark: '#1A1211',
+      radius: 'lg',
+      density: 'comfortable',
+    },
+    // Payment is the only off-app step; the compiler derives ChatGPT redirect_domains from this so the
+    // signed checkout link opens without a safe-link warning. The card never reaches this app.
+    handoff: {
+      allowedDomains: ['https://pay.acme.example', 'https://acme.example'],
+    },
+  },
+  [
+    toolWithWidget('show_menu', {
+      description: 'Show the Acme Bistro menu and render the ordering widget.',
+      annotations: readOnly,
+      input: z.object({ customer: z.string().default('Guest') }),
+      output: z.object({
+        status: z.string(),
+        customer: z.string(),
+        items: z.array(menuItemOutput),
+      }),
+      fulfil: ({ input }) => ({
+        status: `Acme Bistro menu is ready for ${input.customer}. Build the order here; pay at checkout.`,
+        customer: input.customer,
+        items: menu,
+      }),
+      widgetTitle: 'Order at Acme Bistro',
+      widgetDescription: 'Browse the menu, build an order in chat, and hand off to pay.',
+      invoking: 'Loading the menu…',
+      invoked: 'Menu ready',
+      domain: 'https://order.acme.example',
+      view: {
+        component: 'menu-cart',
+        entry: './views/menu-cart.tsx',
+      },
+      csp: {
+        connectDomains: ['https://acme.example'],
+        resourceDomains: ['https://acme.example'],
+        frameDomains: ['https://acme.example'],
+      },
+    }),
+    // Widget-only cart edits — the model fills the item from natural language ("add two margheritas").
+    toolForWidget('add_to_cart', {
+      description: 'Add a menu item to the Acme Bistro order from the widget.',
+      annotations: localWrite,
+      input: z.object({
+        customer: z.string().default('Guest'),
+        item: itemId.default('stone_pizza'),
+        quantity: z.number().int().min(1).default(1),
+        notes: z.string().default(''),
+      }),
+      output: z.object({
+        status: z.string(),
+        item: z.string(),
+        quantity: z.number(),
+        notes: z.string(),
+      }),
+      fulfil: ({ input }) => ({
+        status: `Added ${input.quantity} × ${input.item} for ${input.customer}.`,
+        item: input.item,
+        quantity: input.quantity,
+        notes: input.notes,
+      }),
+    }),
+    toolForWidget('remove_from_cart', {
+      description: 'Remove a menu item from the Acme Bistro order.',
+      annotations: localWrite,
+      input: z.object({
+        customer: z.string().default('Guest'),
+        item: itemId.default('stone_pizza'),
+      }),
+      output: z.object({
+        status: z.string(),
+        item: z.string(),
+      }),
+      fulfil: ({ input }) => ({
+        status: `Removed ${input.item} for ${input.customer}.`,
+        item: input.item,
+      }),
+    }),
+    // The only handoff: payment. The widget computes the total (live React) and passes a url-safe cart
+    // token + total; the card is entered on Acme's PCI-scoped checkout, never in chat.
+    tool('create_checkout', {
+      description:
+        'Create the Acme Bistro payment checkout link for the current order. Pass a url-safe cart token ' +
+        'and the numeric total computed in the widget. Payment happens off-app; the card never reaches this app.',
+      annotations: openLink,
+      input: z.object({
+        customer: z.string().default('Guest'),
+        cartToken: z.string().default('cart'),
+        total: z.number().min(0).default(0),
+      }),
+      output: z.object({
+        status: z.string(),
+        summary: z.string(),
+        checkoutUrl: z.string(),
+      }),
+      // Do not place a literal `$` immediately before a token (`$${input.total}`) — it collides with the
+      // `${…}` substitution syntax and leaves the token unresolved. Keep the amount token standalone.
+      fulfil: ({ input }) => ({
+        status: `Ready to pay for ${input.customer}'s order.`,
+        summary: `${input.customer}'s Acme Bistro order · ${input.total} USD`,
+        checkoutUrl: `https://pay.acme.example/checkout?cart=${input.cartToken}&total=${input.total}&src=chatgpt`,
+      }),
+    }),
+  ],
+);

package/skills/claude-code/examples/acme-bistro/src/views/menu-cart.tsx

@@ -0,0 +1,159 @@
+import { useMemo, useState } from 'react';
+import { useCallTool, useLayout, useOpenExternal, useToolInfo, useViewState } from '../helpers.js';
+import './widget-style.css';
+
+type MenuItem = {
+  readonly id: string;
+  readonly name: string;
+  readonly price: number;
+  readonly kind: string;
+};
+
+function asMenu(value: unknown) {
+  return value as
+    | { readonly status?: string; readonly customer?: string; readonly items?: readonly MenuItem[] }
+    | undefined;
+}
+
+export default function MenuCart() {
+  const { displayMode, theme } = useLayout();
+  const openExternal = useOpenExternal();
+  const menuResult = asMenu(useToolInfo('show_menu').structuredContent);
+  const addToCart = useCallTool('add_to_cart');
+  const removeFromCart = useCallTool('remove_from_cart');
+  const checkout = useCallTool('create_checkout');
+
+  const items = menuResult?.items ?? [];
+  const [customer] = useViewState('customer', menuResult?.customer ?? 'Guest');
+  // Cart is session-local (id → quantity); the total is summed here in live React, not in a recorded fulfil.
+  const [cart, setCart] = useState<Record<string, number>>({});
+  const [status, setStatus] = useState(
+    menuResult?.status ?? 'Build your order, then check out to pay.',
+  );
+
+  const total = useMemo(
+    () => items.reduce((sum, item) => sum + item.price * (cart[item.id] ?? 0), 0),
+    [items, cart],
+  );
+  const lineCount = Object.values(cart).reduce((n, q) => n + q, 0);
+
+  async function add(item: MenuItem) {
+    setCart((current) => ({ ...current, [item.id]: (current[item.id] ?? 0) + 1 }));
+    const result = await addToCart.callTool({ customer, item: item.id, quantity: 1 });
+    const structured = result.structuredContent as { readonly status?: string } | undefined;
+    setStatus(structured?.status ?? `Added ${item.name}.`);
+  }
+
+  async function remove(item: MenuItem) {
+    setCart((current) => {
+      const next = { ...current };
+      const q = (next[item.id] ?? 0) - 1;
+      if (q <= 0) delete next[item.id];
+      else next[item.id] = q;
+      return next;
+    });
+    await removeFromCart.callTool({ customer, item: item.id });
+  }
+
+  async function payNow() {
+    if (lineCount === 0) return;
+    // The only handoff: payment. A url-safe cart token + the numeric total go to Acme's PCI checkout.
+    const cartToken = items
+      .filter((item) => cart[item.id])
+      .map((item) => `${item.id}x${cart[item.id]}`)
+      .join('-');
+    const result = await checkout.callTool({ customer, cartToken, total });
+    const structured = result.structuredContent as { readonly checkoutUrl?: string } | undefined;
+    if (structured?.checkoutUrl) openExternal(structured.checkoutUrl);
+  }
+
+  return (
+    <main
+      className={`nw-shell${theme === 'dark' ? ' dark' : ''}`}
+      data-llm={`Acme Bistro order for ${customer}: ${lineCount} item(s), total $${total}`}
+    >
+      <section className="nw-card">
+        <header className="nw-header">
+          <span className="nw-icon" aria-hidden="true">
+            <PlateIcon />
+          </span>
+          <div className="nw-title-block">
+            <h1 className="nw-title">Acme Bistro</h1>
+            <p className="nw-subtitle">{status}</p>
+          </div>
+          <span className="nw-chip">
+            {displayMode === 'fullscreen' ? 'Fullscreen' : `${lineCount} in cart`}
+          </span>
+        </header>
+
+        <ul className="nw-menu">
+          {items.map((item) => (
+            <li className="nw-row" key={item.id}>
+              <span className="nw-row-main">
+                <span className="nw-name">{item.name}</span>
+                <span className="nw-kind">{item.kind}</span>
+              </span>
+              <span className="nw-price">${item.price}</span>
+              <span className="nw-qty">
+                <button
+                  aria-label={`Remove one ${item.name}`}
+                  className="nw-step"
+                  type="button"
+                  disabled={!cart[item.id]}
+                  onClick={() => remove(item)}
+                >
+                  −
+                </button>
+                <span className="nw-count">{cart[item.id] ?? 0}</span>
+                <button
+                  aria-label={`Add one ${item.name}`}
+                  className="nw-step"
+                  type="button"
+                  onClick={() => add(item)}
+                >
+                  +
+                </button>
+              </span>
+            </li>
+          ))}
+        </ul>
+
+        <footer className="nw-footer">
+          <span className="nw-total">
+            Total <strong>${total}</strong>
+          </span>
+          <button
+            className="nw-button nw-button-primary"
+            type="button"
+            disabled={lineCount === 0 || checkout.isPending}
+            onClick={payNow}
+          >
+            <CardIcon />
+            {checkout.isPending ? 'Opening checkout…' : 'Check out & pay'}
+          </button>
+        </footer>
+        <p className="nw-note">
+          Payment happens on acme.example — your card is never entered in chat.
+        </p>
+      </section>
+    </main>
+  );
+}
+
+function PlateIcon() {
+  return (
+    <svg viewBox="0 0 24 24" aria-hidden="true">
+      <circle cx="12" cy="12" r="9" />
+      <circle cx="12" cy="12" r="4" />
+    </svg>
+  );
+}
+
+function CardIcon() {
+  return (
+    <svg viewBox="0 0 24 24" aria-hidden="true">
+      <rect x="3" y="5" width="18" height="14" rx="2" />
+      <path d="M3 10h18" />
+    </svg>
+  );
+}

package/skills/claude-code/examples/acme-bistro/src/views/widget-style.css

@@ -0,0 +1,228 @@
+:root {
+  color-scheme: light dark;
+  font-family:
+    Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  --nw-bg: #ffffff;
+  --nw-surface: #fdf4f3;
+  --nw-text: #1f1413;
+  --nw-muted: #7a5f5c;
+  --nw-border: #efd9d6;
+  --nw-accent: #b91c1c;
+  --nw-accent-strong: #991b1b;
+  --nw-accent-soft: #fdeae8;
+  --nw-radius: 10px;
+  --nw-shadow: 0 18px 50px rgb(60 20 20 / 12%);
+}
+
+.dark,
+[data-theme="dark"] {
+  --nw-bg: #1a1211;
+  --nw-surface: #241816;
+  --nw-text: #f8ecea;
+  --nw-muted: #c3a29e;
+  --nw-border: #43302d;
+  --nw-accent: #f87171;
+  --nw-accent-strong: #ef4444;
+  --nw-accent-soft: #3a1f1d;
+  --nw-shadow: 0 18px 50px rgb(0 0 0 / 32%);
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  background: var(--nw-bg);
+  color: var(--nw-text);
+}
+
+button {
+  font: inherit;
+}
+
+.nw-shell {
+  min-height: 100vh;
+  padding: 14px;
+  background: var(--nw-bg);
+  color: var(--nw-text);
+}
+
+.nw-card {
+  max-width: 560px;
+  margin: 0 auto;
+  background: var(--nw-surface);
+  border: 1px solid var(--nw-border);
+  border-radius: var(--nw-radius);
+  box-shadow: var(--nw-shadow);
+  overflow: hidden;
+}
+
+.nw-header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 16px;
+  border-bottom: 1px solid var(--nw-border);
+}
+
+.nw-icon svg {
+  width: 24px;
+  height: 24px;
+  fill: none;
+  stroke: var(--nw-accent);
+  stroke-width: 1.7;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+.nw-title-block {
+  flex: 1;
+  min-width: 0;
+}
+
+.nw-title {
+  margin: 0;
+  font-size: 17px;
+  font-weight: 700;
+}
+
+.nw-subtitle {
+  margin: 2px 0 0;
+  font-size: 13px;
+  color: var(--nw-muted);
+}
+
+.nw-chip {
+  padding: 4px 10px;
+  border-radius: 999px;
+  background: var(--nw-accent-soft);
+  color: var(--nw-accent-strong);
+  font-size: 12px;
+  font-weight: 600;
+}
+
+.nw-menu {
+  list-style: none;
+  margin: 0;
+  padding: 8px 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.nw-row {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 10px 0;
+  border-bottom: 1px dashed var(--nw-border);
+}
+
+.nw-row-main {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+.nw-name {
+  font-weight: 600;
+}
+
+.nw-kind {
+  font-size: 12px;
+  color: var(--nw-muted);
+}
+
+.nw-price {
+  color: var(--nw-accent-strong);
+  font-weight: 600;
+  font-size: 13px;
+}
+
+.nw-qty {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.nw-step {
+  width: 26px;
+  height: 26px;
+  border: 1px solid var(--nw-border);
+  border-radius: 8px;
+  background: var(--nw-bg);
+  color: var(--nw-text);
+  cursor: pointer;
+}
+
+.nw-step:disabled {
+  opacity: 0.4;
+  cursor: default;
+}
+
+.nw-count {
+  min-width: 16px;
+  text-align: center;
+  font-variant-numeric: tabular-nums;
+}
+
+.nw-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 12px 16px 4px;
+}
+
+.nw-total {
+  font-size: 14px;
+  color: var(--nw-muted);
+}
+
+.nw-total strong {
+  color: var(--nw-text);
+  font-size: 16px;
+}
+
+.nw-button {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 9px 14px;
+  border: 1px solid var(--nw-border);
+  border-radius: 10px;
+  background: var(--nw-bg);
+  color: var(--nw-text);
+  cursor: pointer;
+}
+
+.nw-button svg {
+  width: 16px;
+  height: 16px;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.7;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+.nw-button-primary {
+  background: var(--nw-accent);
+  border-color: var(--nw-accent);
+  color: #ffffff;
+  font-weight: 600;
+}
+
+.nw-button-primary:disabled {
+  opacity: 0.6;
+  cursor: default;
+}
+
+.nw-note {
+  margin: 0;
+  padding: 8px 16px 16px;
+  font-size: 12px;
+  color: var(--nw-muted);
+}

package/skills/claude-code/examples/acme-bistro/test/server.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import app from '../src/server.js';
+
+describe('acme-bistro example', () => {
+  it('exports a Noodle server definition', () => {
+    expect(typeof app.toManifest).toBe('function');
+  });
+
+  it('declares the payment-only handoff domain', async () => {
+    // End-to-end: the order completes in chat; only payment hands off to Acme's checkout.
+    const text = JSON.stringify(await app.toManifest());
+    expect(text).toContain('https://pay.acme.example');
+  });
+
+  it('exposes the menu widget, cart helpers, and checkout tool', async () => {
+    const text = JSON.stringify(await app.toManifest());
+    expect(text).toContain('show_menu');
+    expect(text).toContain('add_to_cart');
+    expect(text).toContain('create_checkout');
+  });
+});

package/skills/claude-code/examples/acme-bistro/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+// Local config so `npm test` (vitest run) discovers this example's own tests instead of inheriting a
+// parent monorepo config's include globs.
+export default defineConfig({
+  test: { include: ['test/**/*.test.ts'] },
+});

package/skills/claude-code/examples/acme-discovery/README.md

@@ -0,0 +1,85 @@
+# Acme Getaways — top-of-funnel discovery → handoff
+
+A Noodle MCP App for **Acme Getaways**, a fictional travel brand. It is the flagship for the
+**top-of-funnel discovery → handoff** pattern: discovery and configuration happen inside ChatGPT; the
+booking/transaction happens off-app on Acme's own site, reached through a signed, attributable handoff
+deep link. It pairs a `toolWithWidget` discovery carousel with a model-visible `create_handoff` tool and
+server-level `handoff.allowedDomains`.
+
+Capability slots: top-of-funnel funnel discipline, discovery carousel widget, `create_handoff` deep-link
+handoff with attribution, `handoff.allowedDomains`, and a worked **design-first** artifact (the UX spec +
+wireframe below). It shows the "design the experience, then build it" flow the `noodle-seed` skill's
+`references/experience-design.md` teaches.
+
+## Design spec (write this before the code)
+
+- **Funnel boundary** — Discover and shortlist a getaway in ChatGPT. Booking, payment, and the account
+  live on `acme.example`, reached only after the handoff. No payment or per-user auth in chat.
+- **Personas** — the undecided browser ("somewhere warm in June?"), the near-decided planner (has a vibe
+  and month, wants options and a fast handoff).
+- **Top-3 prioritized user flows**
+  1. **Discover** — "warm beach trip in June for 2" → `discover_getaways` renders the carousel.
+  2. **Shortlist** — pick a destination in the widget → `shortlist_getaway` (widget-only) records it.
+  3. **Handoff** — "Continue on Acme" → `create_handoff` emits the deep link → opens off-app.
+- **Tools** — `discover_getaways` (model-visible, renders the widget), `create_handoff` (model-visible,
+  emits the deep link), `shortlist_getaway` (widget-only helper, hidden from the model).
+- **Widgets + display modes** — `DiscoveryCarousel` as an inline card that expands to fullscreen for
+  browsing. No picture-in-picture (nothing is live/ongoing).
+- **Grounding sources** — the destination catalog in `src/server.ts` is Acme's own data; the widget never
+  invents a place, price, or best-month.
+- **Handoff domains** — `https://book.acme.example`, `https://acme.example` (the server
+  `handoff.allowedDomains`; the deep link carries `dest`, `month`, `pax`, and `src=chatgpt` for
+  attribution).
+
+## Wireframe (one screen, then the off-app destination)
+
+The carousel screen is in-app (solid frame); the booking screen is off-app (dashed frame) and reached
+only after the handoff — it is Acme's own page, never wireframed as if it were in chat.
+
+```html
+<div class="phone">                                  <!-- in-app: solid frame -->
+  <div class="chatgpt-header">ChatGPT · Acme Getaways</div>
+  <div class="msg user">somewhere warm in June, 2 of us</div>
+  <div class="tool-call">discover_getaways { vibe: "beach", month: "June", travelers: 2 }</div>
+  <div class="wcard">
+    <div class="wcard-head">DiscoveryCarousel</div>   <!-- component name = code + spec -->
+    <div class="wcard-body">
+      <div class="dest">Coral Bay · from $890 · best May–Sep  [Shortlist]</div>
+      <div class="dest">Harbor City · from $980 · best Sep–Nov [Shortlist]</div>
+      <a class="cta">Continue on Acme · Coral Bay</a>   <!-- one primary action -->
+    </div>
+  </div>
+</div>
+<div class="phone offapp">                            <!-- off-app: dashed frame -->
+  <div class="browser-header">book.acme.example/plan?dest=coral_bay&month=June&pax=2&src=chatgpt</div>
+  <div class="offapp-body">Acme booking — payment & account live here.</div>
+</div>
+```
+
+## Local author loop
+
+```sh
+noodle validate
+noodle test
+noodle dev
+```
+
+In another terminal:
+
+```sh
+noodle tools list
+noodle tools call discover_getaways --args '{"vibe":"beach","month":"June","travelers":2}'
+noodle tools call create_handoff --args '{"destination":"coral_bay","destinationName":"Coral Bay","month":"June","travelers":2}'
+noodle check --target chatgpt
+```
+
+## Deploy
+
+```sh
+noodle link --org demo --app acme-discovery
+noodle deploy --access owner-only
+noodle open
+```
+
+This example has no connector secrets and does not include tokens, caller-key mechanisms, or
+`.env.noodle` values. All destinations, prices, and URLs are fictional.