@noodleseed/agent-kit 0.14.0 → 0.16.0

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

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

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

@@ -0,0 +1,20 @@
+{
+  "name": "acme-discovery",
+  "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-discovery/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-discovery/src/server.ts

@@ -0,0 +1,202 @@
+import { annotations, server, tool, toolForWidget, toolWithWidget, z } from '@noodleseed/one';
+
+// Acme Getaways is a fictional travel brand. This app is deliberately top-of-funnel: 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. Destinations are the partner's own
+// catalog (grounding) — the app never invents a place, price, or best-month.
+//
+// Authoring note: a tool `fulfil` is *recorded*, not run as live JS. Inputs flow through as
+// `${input.x}` substitutions when placed directly into an output string; do not transform them
+// (no URL-encoding, arithmetic, or filtering on an input value — those break substitution). The
+// curated catalog below is static data the runtime returns verbatim.
+
+const catalog = [
+  {
+    id: 'coral_bay',
+    name: 'Coral Bay',
+    region: 'Adriatic coast',
+    vibe: 'beach',
+    priceFrom: 890,
+    bestMonths: 'May–Sep',
+    why: 'Calm swimming coves and a walkable old town — easy for a relaxed first trip.',
+  },
+  {
+    id: 'monte_alto',
+    name: 'Monte Alto',
+    region: 'Northern Alps',
+    vibe: 'mountains',
+    priceFrom: 1120,
+    bestMonths: 'Dec–Mar',
+    why: 'Ski-in village with beginner slopes and long groomed runs.',
+  },
+  {
+    id: 'old_quarter',
+    name: 'Old Quarter',
+    region: 'Central Europe',
+    vibe: 'culture',
+    priceFrom: 640,
+    bestMonths: 'Apr–Oct',
+    why: 'Dense museum district and food halls, all reachable on foot.',
+  },
+  {
+    id: 'harbor_city',
+    name: 'Harbor City',
+    region: 'Pacific rim',
+    vibe: 'city',
+    priceFrom: 980,
+    bestMonths: 'Sep–Nov',
+    why: 'Waterfront nightlife and day-trip islands a short ferry away.',
+  },
+] as const;
+
+// A closed set of URL-safe month values. A `fulfil` cannot url-encode an input (recording would break
+// substitution), so the deep link carries `month` only if it is already safe — the model maps natural
+// phrasing ("early June") onto one of these when it fills the tool.
+const monthEnum = z
+  .enum([
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+    'July',
+    'August',
+    'September',
+    'October',
+    'November',
+    'December',
+  ])
+  .default('June');
+
+// The catalog ids are already url-safe slugs. Constrain the handoff `destination` to this closed set so
+// only a real, url-safe id can reach the deep link.
+const destinationId = z.enum(['coral_bay', 'monte_alto', 'old_quarter', 'harbor_city']);
+
+const discoverInput = z.object({
+  vibe: z.enum(['beach', 'mountains', 'culture', 'city']).default('beach'),
+  month: monthEnum,
+  travelers: z.number().int().min(1).default(2),
+});
+
+// Tool annotations for host planners: reads are read-only, the handoff opens an external link, and
+// shortlisting is a local non-destructive write.
+const readOnly = annotations.readOnly();
+const openLink = annotations.openAction();
+const localWrite = annotations.localAction({ destructive: false });
+
+const destinationOutput = z.object({
+  id: z.string(),
+  name: z.string(),
+  region: z.string(),
+  vibe: z.string(),
+  priceFrom: z.number(),
+  bestMonths: z.string(),
+  why: z.string(),
+});
+
+export default server(
+  'acme_discovery',
+  {
+    title: 'Acme Getaways',
+    version: '1.0.0',
+    branding: {
+      name: 'Acme Getaways',
+      accent: '#0EA5A4',
+      surface: '#F0FDFA',
+      surfaceDark: '#0B1B1B',
+      radius: 'lg',
+      density: 'comfortable',
+    },
+    // The only external destinations the app links out to — the compiler derives ChatGPT's
+    // redirect_domains from this so the handoff opens without a safe-link warning.
+    handoff: {
+      allowedDomains: ['https://book.acme.example', 'https://acme.example'],
+    },
+  },
+  [
+    toolWithWidget('discover_getaways', {
+      description:
+        'Suggest Acme Getaways destinations for a vibe and month and render a discovery carousel.',
+      annotations: readOnly,
+      input: discoverInput,
+      output: z.object({
+        status: z.string(),
+        vibe: z.string(),
+        month: z.string(),
+        travelers: z.number(),
+        options: z.array(destinationOutput),
+      }),
+      // The carousel presents Acme's curated catalog; the model narrates which fit the stated vibe.
+      // (A tool cannot filter on an input value — that is connector/flow work — so all are returned.)
+      fulfil: ({ input }) => ({
+        status: `Acme Getaways for a ${input.vibe} trip in ${input.month}, ${input.travelers} traveler(s).`,
+        vibe: input.vibe,
+        month: input.month,
+        travelers: input.travelers,
+        options: catalog,
+      }),
+      widgetTitle: 'Discover getaways',
+      // ChatGPT host status copy (openai/toolInvocation/*) — required for widget-opening tools.
+      invoking: 'Finding getaways…',
+      invoked: 'Getaways ready',
+      domain: 'https://getaways.acme.example',
+      view: {
+        component: 'discovery-carousel',
+        entry: './views/discovery-carousel.tsx',
+      },
+      widgetDescription:
+        'A top-of-funnel discovery carousel: pick a destination, then hand off to Acme to book.',
+      csp: {
+        connectDomains: ['https://acme.example'],
+        resourceDomains: ['https://acme.example'],
+        frameDomains: ['https://acme.example'],
+      },
+    }),
+    tool('create_handoff', {
+      description:
+        'Create the Acme booking deep link for a chosen destination, carrying the configured trip. ' +
+        'Pass the destination id (url-safe slug, e.g. "coral_bay") and its display name.',
+      annotations: openLink,
+      input: z.object({
+        destination: destinationId,
+        destinationName: z.string().min(1),
+        month: monthEnum,
+        travelers: z.number().int().min(1).default(2),
+      }),
+      output: z.object({
+        status: z.string(),
+        destination: z.string(),
+        summary: z.string(),
+        handoffUrl: z.string(),
+      }),
+      // Inline the inputs directly so they substitute at runtime; every value is already url-safe
+      // (id slug, month enum, integer), and `src=chatgpt` is the attribution the partner measures
+      // ChatGPT-sourced conversions on.
+      fulfil: ({ input }) => ({
+        status: `Ready to continue on Acme for ${input.destinationName}.`,
+        destination: input.destination,
+        summary: `${input.destinationName} · ${input.month} · ${input.travelers} traveler(s)`,
+        handoffUrl: `https://book.acme.example/plan?dest=${input.destination}&month=${input.month}&pax=${input.travelers}&src=chatgpt`,
+      }),
+    }),
+    toolForWidget('shortlist_getaway', {
+      description: 'Record the traveler’s shortlisted destination from the discovery widget.',
+      annotations: localWrite,
+      input: z.object({
+        destination: z.string(),
+        note: z.string().default(''),
+      }),
+      output: z.object({
+        status: z.string(),
+        destination: z.string(),
+        note: z.string(),
+      }),
+      fulfil: ({ input }) => ({
+        status: `Shortlisted ${input.destination}.`,
+        destination: input.destination,
+        note: input.note,
+      }),
+    }),
+  ],
+);

package/skills/claude-code/examples/acme-discovery/src/views/discovery-carousel.tsx

@@ -0,0 +1,155 @@
+import { useState } from 'react';
+import { useCallTool, useLayout, useOpenExternal, useToolInfo, useViewState } from '../helpers.js';
+import './widget-style.css';
+
+type Destination = {
+  readonly id: string;
+  readonly name: string;
+  readonly region: string;
+  readonly vibe: string;
+  readonly priceFrom: number;
+  readonly bestMonths: string;
+  readonly why: string;
+};
+
+function asDiscovery(value: unknown) {
+  return value as
+    | {
+        readonly status?: string;
+        readonly month?: string;
+        readonly travelers?: number;
+        readonly options?: readonly Destination[];
+      }
+    | undefined;
+}
+
+export default function DiscoveryCarousel() {
+  const { displayMode, theme } = useLayout();
+  const openExternal = useOpenExternal();
+  const discovery = asDiscovery(useToolInfo('discover_getaways').structuredContent);
+  const shortlist = useCallTool('shortlist_getaway');
+  const handoff = useCallTool('create_handoff');
+
+  const options = discovery?.options ?? [];
+  const month = discovery?.month ?? 'June';
+  const travelers = discovery?.travelers ?? 2;
+  const [chosen, setChosen] = useViewState('chosen', options[0]?.id ?? '');
+  const [status, setStatus] = useState(discovery?.status ?? 'Pick a getaway to continue.');
+  const selected = options.find((entry) => entry.id === chosen) ?? options[0];
+  const continueLabel = handoff.isPending
+    ? 'Opening Acme…'
+    : `Continue on Acme${selected ? ` · ${selected.name}` : ''}`;
+
+  async function shortlistDestination(destination: Destination) {
+    setChosen(destination.id);
+    try {
+      const result = await shortlist.callTool({ destination: destination.name });
+      const structured = result.structuredContent as { readonly status?: string } | undefined;
+      setStatus(structured?.status ?? `Shortlisted ${destination.name}.`);
+    } catch {
+      setStatus(`Couldn't shortlist ${destination.name} — try again.`);
+    }
+  }
+
+  async function continueOnAcme() {
+    if (selected === undefined) return;
+    // The handoff is the product: configure here, transact off-app. The deep link carries the trip.
+    // Only open the external target on a successful handoff; surface failures instead of failing silently.
+    try {
+      const result = await handoff.callTool({
+        destination: selected.id,
+        destinationName: selected.name,
+        month,
+        travelers,
+      });
+      const structured = result.structuredContent as { readonly handoffUrl?: string } | undefined;
+      if (structured?.handoffUrl) openExternal(structured.handoffUrl);
+      else setStatus('Continue on Acme is unavailable right now — try again.');
+    } catch {
+      setStatus('Continue on Acme failed — try again.');
+    }
+  }
+
+  return (
+    <main
+      className={`nw-shell${theme === 'dark' ? ' dark' : ''}`}
+      data-llm={`Acme Getaways discovery: ${options.length} options for ${month}, ${travelers} traveler(s); shortlisted ${selected?.name ?? 'none'}`}
+    >
+      <section className="nw-card">
+        <header className="nw-header">
+          <span className="nw-icon" aria-hidden="true">
+            <CompassIcon />
+          </span>
+          <div className="nw-title-block">
+            <h1 className="nw-title">Acme Getaways</h1>
+            <p className="nw-subtitle" aria-live="polite">
+              {status}
+            </p>
+          </div>
+          <span className="nw-chip">
+            {displayMode === 'fullscreen' ? 'Fullscreen' : 'Discover'}
+          </span>
+        </header>
+
+        <div className="nw-carousel">
+          {options.map((entry) => (
+            <article
+              className={`nw-dest${entry.id === chosen ? ' nw-dest-active' : ''}`}
+              key={entry.id}
+            >
+              <div className="nw-dest-head">
+                <span className="nw-dest-name">{entry.name}</span>
+                <span className="nw-price">from ${entry.priceFrom}</span>
+              </div>
+              <p className="nw-dest-region">
+                {entry.region} · best {entry.bestMonths}
+              </p>
+              {/* Grounded copy: the "why" comes from Acme's catalog, not invented at runtime. */}
+              <p className="nw-dest-why">{entry.why}</p>
+              <button
+                aria-pressed={entry.id === chosen}
+                className="nw-button nw-button-ghost"
+                type="button"
+                onClick={() => shortlistDestination(entry)}
+              >
+                {entry.id === chosen ? 'Shortlisted' : 'Shortlist'}
+              </button>
+            </article>
+          ))}
+        </div>
+
+        <div className="nw-actions">
+          <button
+            className="nw-button nw-button-primary"
+            type="button"
+            disabled={selected === undefined || handoff.isPending}
+            onClick={continueOnAcme}
+          >
+            <ExternalIcon />
+            {continueLabel}
+          </button>
+        </div>
+        <p className="nw-note">Booking and payment happen on acme.example — never inside chat.</p>
+      </section>
+    </main>
+  );
+}
+
+function CompassIcon() {
+  return (
+    <svg viewBox="0 0 24 24" aria-hidden="true">
+      <circle cx="12" cy="12" r="9" />
+      <path d="m15.5 8.5-2 5-5 2 2-5 5-2Z" />
+    </svg>
+  );
+}
+
+function ExternalIcon() {
+  return (
+    <svg viewBox="0 0 24 24" aria-hidden="true">
+      <path d="M14 4h6v6" />
+      <path d="m20 4-9 9" />
+      <path d="M20 14v5a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1V5a1 1 0 0 1 1-1h5" />
+    </svg>
+  );
+}

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

@@ -0,0 +1,207 @@
+: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: #f4fbfa;
+  --nw-text: #10201f;
+  --nw-muted: #5b6b6a;
+  --nw-border: #d4e6e4;
+  --nw-accent: #0ea5a4;
+  --nw-accent-strong: #0f766e;
+  --nw-accent-soft: #e6faf8;
+  --nw-radius: 10px;
+  --nw-shadow: 0 18px 50px rgb(15 40 40 / 12%);
+}
+
+.dark,
+[data-theme="dark"] {
+  --nw-bg: #0b1b1b;
+  --nw-surface: #102624;
+  --nw-text: #eafaf8;
+  --nw-muted: #9fb6b3;
+  --nw-border: #244341;
+  --nw-accent: #2dd4bf;
+  --nw-accent-strong: #14b8a6;
+  --nw-accent-soft: #0f3835;
+  --nw-shadow: 0 18px 50px rgb(0 0 0 / 30%);
+}
+
+* {
+  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: 720px;
+  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: 26px;
+  height: 26px;
+  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-carousel {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
+  gap: 12px;
+  padding: 16px;
+}
+
+.nw-dest {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px;
+  border: 1px solid var(--nw-border);
+  border-radius: 12px;
+  background: var(--nw-bg);
+}
+
+.nw-dest-active {
+  border-color: var(--nw-accent);
+  box-shadow: 0 0 0 1px var(--nw-accent);
+}
+
+.nw-dest-head {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 8px;
+}
+
+.nw-dest-name {
+  font-weight: 700;
+}
+
+.nw-price {
+  color: var(--nw-accent-strong);
+  font-size: 12px;
+  font-weight: 600;
+}
+
+.nw-dest-region {
+  margin: 0;
+  font-size: 12px;
+  color: var(--nw-muted);
+}
+
+.nw-dest-why {
+  margin: 0;
+  font-size: 13px;
+  flex: 1;
+}
+
+.nw-actions {
+  display: flex;
+  gap: 8px;
+  padding: 0 16px 12px;
+}
+
+.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-ghost {
+  align-self: flex-start;
+  padding: 6px 12px;
+  font-size: 13px;
+}
+
+.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: 0 16px 16px;
+  font-size: 12px;
+  color: var(--nw-muted);
+}

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

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import app from '../src/server.js';
+
+describe('acme-discovery example', () => {
+  it('exports a Noodle server definition', () => {
+    expect(typeof app.toManifest).toBe('function');
+  });
+
+  it('declares the off-app handoff domain the deep link lands on', async () => {
+    // Top-of-funnel: the only external target is Acme's booking site, declared once at the server.
+    const manifest = await app.toManifest();
+    expect(JSON.stringify(manifest)).toContain('https://book.acme.example');
+  });
+
+  it('exposes the discovery tool and the handoff tool', async () => {
+    const manifest = await app.toManifest();
+    const text = JSON.stringify(manifest);
+    // The discovery tool renders the carousel; the handoff tool emits the deep link; the widget-only
+    // helper records a shortlist.
+    expect(text).toContain('discover_getaways');
+    expect(text).toContain('create_handoff');
+    expect(text).toContain('shortlist_getaway');
+  });
+});

package/skills/claude-code/examples/acme-discovery/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'] },
+});