@noodleseed/agent-kit 0.14.0 → 0.15.0

package/skills/codex/examples/food-ordering/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "food-ordering",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run test/server.test.ts",
+    "validate": "noodle validate",
+    "dev": "noodle dev",
+    "deploy": "noodle deploy"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "latest",
+    "@noodleseed/one": "latest",
+    "@types/react": "latest",
+    "@types/react-dom": "latest",
+    "react": "latest",
+    "react-dom": "latest",
+    "vite": "latest",
+    "vitest": "latest"
+  }
+}

package/skills/codex/examples/food-ordering/src/helpers.ts

@@ -0,0 +1,34 @@
+import type { ServerDefinition } from '@noodleseed/one';
+
+export {
+  ActionBar,
+  AppShell,
+  AsyncBoundary,
+  ChoiceGroup,
+  createViewStore,
+  DataCard,
+  DataList,
+  Field,
+  HandoffButton,
+  QuantityStepper,
+  ShellNav,
+  StatusBadge,
+  SubmitButton,
+  View,
+  ViewStack,
+} from '@noodleseed/one/react';
+
+import { generateHelpers } from '@noodleseed/one/react';
+
+export type AppType = ServerDefinition;
+
+export const {
+  useCallTool,
+  useAppFlow,
+  useHandoff,
+  useLayout,
+  useOpenExternal,
+  useSendFollowUpMessage,
+  useToolInfo,
+  useViewState,
+} = generateHelpers<AppType>();

package/skills/codex/examples/food-ordering/src/server.ts

@@ -0,0 +1,412 @@
+import {
+  annotations,
+  asset,
+  connector,
+  resource,
+  server,
+  tool,
+  toolForWidget,
+  toolWithWidget,
+  widget,
+  z,
+} from '@noodleseed/one';
+
+const heroImage = asset('assets/noodle-bowl.jpg');
+
+const state = connector('noodle_state')
+  .version('1.0.0')
+  .operation('read_state', {
+    type: 'read',
+    input: {
+      handle: { type: 'string', required: true },
+      key: { type: 'string' },
+    },
+    output: {
+      value: { type: 'object', required: true },
+      revision: { type: 'integer', required: true },
+      status: { type: 'string', required: true },
+    },
+  })
+  .operation('patch_state', {
+    type: 'action',
+    input: {
+      handle: { type: 'string', required: true },
+      expectedRevision: { type: 'integer', required: true },
+      value: { type: 'object', required: true },
+    },
+    output: {
+      value: { type: 'object', required: true },
+      revision: { type: 'integer', required: true },
+      status: { type: 'string', required: true },
+    },
+  });
+
+const stores = [
+  {
+    id: 'harbor-noodles',
+    name: 'Harbor Noodles',
+    cuisine: 'Noodles',
+    address: '18 Pier Lane',
+    open: true,
+    etaMinutes: 24,
+    rating: 4.8,
+  },
+  {
+    id: 'garden-wraps',
+    name: 'Garden Wraps',
+    cuisine: 'Vegetarian',
+    address: '44 Market Street',
+    open: true,
+    etaMinutes: 18,
+    rating: 4.6,
+  },
+  {
+    id: 'midnight-tacos',
+    name: 'Midnight Tacos',
+    cuisine: 'Mexican',
+    address: '7 Station Road',
+    open: false,
+    etaMinutes: 35,
+    rating: 4.7,
+  },
+] as const;
+
+const menu = [
+  {
+    id: 'spicy_miso',
+    storeId: 'harbor-noodles',
+    category: 'Bowls',
+    name: 'Spicy Miso Bowl',
+    price: 16,
+    description: 'Miso broth, wheat noodles, chili crisp, egg, and greens.',
+    modifiers: ['extra_noodles', 'soft_egg', 'chili_crisp'],
+  },
+  {
+    id: 'ginger_tofu',
+    storeId: 'harbor-noodles',
+    category: 'Bowls',
+    name: 'Ginger Tofu Bowl',
+    price: 15,
+    description: 'Tofu, ginger broth, mushrooms, and scallions.',
+    modifiers: ['extra_tofu', 'brown_rice', 'no_mushroom'],
+  },
+  {
+    id: 'green_falafel',
+    storeId: 'garden-wraps',
+    category: 'Wraps',
+    name: 'Green Falafel Wrap',
+    price: 13,
+    description: 'Falafel, herbs, pickles, tahini, and crisp vegetables.',
+    modifiers: ['extra_tahini', 'add_fries', 'gluten_free_wrap'],
+  },
+  {
+    id: 'sweet_potato',
+    storeId: 'garden-wraps',
+    category: 'Plates',
+    name: 'Sweet Potato Plate',
+    price: 14,
+    description: 'Roasted sweet potato, grains, greens, and lemon yogurt.',
+    modifiers: ['vegan_yogurt', 'extra_greens', 'hot_sauce'],
+  },
+] as const;
+
+const cartLine = z.object({
+  itemId: z.string(),
+  quantity: z.number().int().min(1),
+  modifiers: z.array(z.string()).default([]),
+  note: z.string().optional(),
+});
+
+const cartInput = z.object({
+  selectedStoreId: z.string().optional(),
+  lines: z.array(cartLine).default([]),
+  customer: z.string().default('Guest'),
+  notes: z.string().optional(),
+  subtotal: z.number().default(0),
+  expectedRevision: z.number().int().min(0).default(0),
+});
+
+const storeShape = z.object({
+  id: z.string(),
+  name: z.string(),
+  cuisine: z.string(),
+  address: z.string(),
+  open: z.boolean(),
+  etaMinutes: z.number(),
+  rating: z.number(),
+});
+
+const menuItemShape = z.object({
+  id: z.string(),
+  storeId: z.string(),
+  category: z.string(),
+  name: z.string(),
+  price: z.number(),
+  description: z.string(),
+  modifiers: z.array(z.string()),
+});
+
+const cartOutput = z.object({
+  selectedStoreId: z.string().optional(),
+  lines: z.array(cartLine),
+  customer: z.string(),
+  notes: z.string().optional(),
+  subtotal: z.number(),
+  status: z.enum(['draft', 'review', 'handoff']),
+  checkoutUrl: z.string().optional(),
+});
+
+const cartStateSchema = z.object({
+  selectedStoreId: z.string().optional(),
+  lines: z.array(cartLine),
+  customer: z.string(),
+  notes: z.string().optional(),
+  subtotal: z.number(),
+  status: z.enum(['draft', 'review', 'handoff']),
+  checkoutUrl: z.string().optional(),
+});
+
+type CartLine = {
+  readonly itemId: string;
+  readonly quantity: number;
+  readonly modifiers: readonly string[];
+  readonly note?: string;
+};
+
+type CartInput = {
+  readonly selectedStoreId?: string;
+  readonly lines: readonly CartLine[];
+  readonly customer: string;
+  readonly notes?: string;
+  readonly subtotal: number;
+  readonly expectedRevision: number;
+};
+
+const readOnly = annotations.readOnly();
+const action = annotations.openAction({ destructive: false });
+
+function checkoutUrl(customer: string): string {
+  return `https://orders.example.com/checkout?customer=${encodeURIComponent(customer)}`;
+}
+
+function cartValue(input: CartInput, status: 'draft' | 'review' | 'handoff') {
+  return {
+    selectedStoreId: input.selectedStoreId,
+    lines: input.lines,
+    customer: input.customer,
+    notes: input.notes,
+    subtotal: input.subtotal,
+    status,
+    ...(status === 'handoff' ? { checkoutUrl: 'https://orders.example.com/checkout' } : {}),
+  };
+}
+
+export default server(
+  'food_ordering',
+  {
+    title: 'Food Ordering',
+    version: '1.0.0',
+    use: { state },
+    state: {
+      handles: {
+        cart: {
+          kind: 'cart',
+          version: 'v1',
+          scope: 'caller',
+          ttlSeconds: 7200,
+          schema: cartStateSchema,
+        },
+      },
+    },
+    branding: {
+      name: 'Food Ordering',
+      accent: '#0F8F5F',
+      surface: '#F7F7F5',
+      surfaceDark: '#111820',
+      logo: {
+        uri: heroImage,
+        alt: 'Food Ordering noodle bowl',
+      },
+      radius: 'lg',
+      density: 'comfortable',
+    },
+    handoff: {
+      allowedDomains: ['https://orders.example.com'],
+    },
+  },
+  [
+    toolWithWidget('open_ordering', {
+      description:
+        'Open a complete food-ordering widget with store discovery, menu browsing, cart review, and checkout handoff.',
+      annotations: readOnly,
+      input: z.object({
+        query: z.string().optional(),
+        customer: z.string().default('Guest'),
+      }),
+      output: z.object({
+        status: z.string(),
+        customer: z.string(),
+        stores: z.array(storeShape),
+        featuredItems: z.array(menuItemShape),
+        fallback: z.string(),
+      }),
+      fulfil: ({ input }) => ({
+        status: 'Ready to build a food order.',
+        customer: input.customer,
+        stores,
+        featuredItems: menu,
+        fallback: 'Open stores: Harbor Noodles (Noodles), Garden Wraps (Vegetarian).',
+      }),
+      widgetTitle: 'Food ordering',
+      domain: 'https://orders.example.com',
+      view: {
+        component: 'ordering-flow',
+        entry: './views/ordering-flow.tsx',
+      },
+      widgetDescription:
+        'A complete consumer ordering surface with app-only helper tools, cart state, and checkout handoff.',
+      csp: {
+        connectDomains: ['https://orders.example.com'],
+        resourceDomains: ['https://orders.example.com'],
+        frameDomains: ['https://orders.example.com'],
+      },
+      permissions: { clipboardWrite: {} },
+    }),
+    toolForWidget('search_stores', {
+      description: 'Filter synthetic restaurants for the ordering widget.',
+      annotations: readOnly,
+      input: z.object({
+        query: z.string().optional(),
+        openOnly: z.boolean().default(false),
+      }),
+      output: z.object({ stores: z.array(storeShape) }),
+      fulfil: () => ({ stores }),
+    }),
+    toolForWidget('load_menu', {
+      description: 'Load synthetic menu categories and items for one store.',
+      annotations: readOnly,
+      input: z.object({ storeId: z.string() }),
+      output: z.object({
+        storeId: z.string(),
+        stores: z.array(storeShape),
+        items: z.array(menuItemShape),
+      }),
+      fulfil: ({ input }) => ({ storeId: input.storeId, stores, items: menu }),
+    }),
+    toolForWidget('load_item', {
+      description: 'Load item details and modifier options for the ordering widget.',
+      annotations: readOnly,
+      input: z.object({ itemId: z.string() }),
+      output: z.object({ itemId: z.string(), items: z.array(menuItemShape) }),
+      fulfil: ({ input }) => ({ itemId: input.itemId, items: menu }),
+    }),
+    toolForWidget('read_cart', {
+      description: 'Read the caller-scoped ordering cart state.',
+      annotations: readOnly,
+      input: z.object({}),
+      output: z.object({
+        value: z.unknown(),
+        revision: z.number(),
+        status: z.string(),
+      }),
+      fulfil: ({ connectors }) => {
+        const state = connectors.state.readState({ handle: 'cart' });
+        return { value: state.value, revision: state.revision, status: state.status };
+      },
+    }),
+    toolForWidget('sync_cart', {
+      description: 'Patch the caller-scoped ordering cart with the widget cart mirror.',
+      annotations: action,
+      input: cartInput,
+      output: z.object({
+        cart: cartOutput,
+        revision: z.number(),
+        status: z.string(),
+      }),
+      fulfil: ({ input, connectors }) => {
+        const cart = cartValue(input, 'draft');
+        const state = connectors.state.patchState({
+          handle: 'cart',
+          expectedRevision: input.expectedRevision,
+          value: cart,
+        });
+        return { cart, revision: state.revision, status: state.status };
+      },
+    }),
+    toolForWidget('prepare_checkout', {
+      description: 'Prepare the caller-scoped cart for checkout handoff.',
+      annotations: action,
+      input: cartInput,
+      output: z.object({
+        cart: cartOutput,
+        revision: z.number(),
+        checkoutUrl: z.string(),
+      }),
+      fulfil: ({ input, connectors }) => {
+        const cart = cartValue(input, 'handoff');
+        const state = connectors.state.patchState({
+          handle: 'cart',
+          expectedRevision: input.expectedRevision,
+          value: cart,
+        });
+        return {
+          cart,
+          revision: state.revision,
+          checkoutUrl: cart.checkoutUrl ?? checkoutUrl(input.customer),
+        };
+      },
+    }),
+    tool('summarize_ordering_options', {
+      description: 'Summarize available stores and menu examples without opening the widget.',
+      annotations: readOnly,
+      input: z.object({}),
+      output: z.object({
+        stores: z.array(storeShape),
+        featuredItems: z.array(menuItemShape),
+      }),
+      fulfil: () => ({ stores, featuredItems: menu }),
+    }),
+    tool('show_capabilities', {
+      description: 'Return a concise summary for the standalone widget capability preview.',
+      annotations: readOnly,
+      input: z.object({}),
+      output: z.object({ status: z.string(), note: z.string() }),
+      fulfil: () => ({
+        status: 'Food Ordering widget capabilities are ready.',
+        note: 'Standalone preview covers React views, helper tools, cart state, handoff, CSP, and permissions.',
+      }),
+    }),
+    resource('food_ordering_guide', {
+      uri: 'docs://food-ordering',
+      title: 'Food Ordering widget guide',
+      description: 'Synthetic guide resource for the consumer ordering flagship.',
+      mimeType: 'text/markdown',
+      // Return the resource body directly; the runtime maps it into MCP `contents` using the
+      // resource's own uri + mimeType. Do not return a `{ contents: [...] }` wrapper — that double-wraps.
+      fulfil: () =>
+        [
+          '# Food Ordering Widget Guide',
+          '',
+          '- Demonstrates a multi-step ordering widget, app-only helper tools, typed cart state, and handoff.',
+          '- Store, menu, and checkout data are synthetic and contain no customer credentials.',
+          '- Checkout opens an allowlisted example URL; payment and final ordering remain out of scope.',
+        ].join('\n'),
+    }),
+    widget('capabilities_card', {
+      tool: 'show_capabilities',
+      title: 'Food Ordering capabilities',
+      domain: 'https://orders.example.com',
+      description: 'Standalone widget resource for previewing the ordering capability surface.',
+      view: {
+        component: 'capabilities-card',
+        entry: './views/capabilities-card.tsx',
+      },
+      csp: {
+        connectDomains: ['https://orders.example.com'],
+        resourceDomains: ['https://orders.example.com'],
+        frameDomains: ['https://orders.example.com'],
+      },
+      permissions: { clipboardWrite: {} },
+    }),
+  ],
+);

package/skills/codex/examples/food-ordering/src/views/capabilities-card.tsx

@@ -0,0 +1,155 @@
+import { useLayout, useOpenExternal, useSendFollowUpMessage, useToolInfo } from '../helpers.js';
+import './widget-style.css';
+
+const capabilities: readonly {
+  readonly name: string;
+  readonly description: string;
+}[] = [
+  {
+    name: 'React view resource',
+    description: 'Compiled widget HTML with a hydrated React entrypoint.',
+  },
+  {
+    name: 'Widget helper calls',
+    description: 'App-only tools route through the same host-mediated path.',
+  },
+  {
+    name: 'Durable cart state',
+    description: 'Caller-scoped cart records use Noodle state handles with revisions.',
+  },
+  {
+    name: 'External handoff',
+    description: 'Checkout opens through declared allowlisted domains.',
+  },
+  {
+    name: 'Model context',
+    description: 'Relevant UI state is mirrored through data-llm.',
+  },
+  {
+    name: 'CSP and permissions',
+    description: 'Resource metadata declares network and clipboard needs.',
+  },
+] as const;
+
+export default function CapabilitiesCard() {
+  const { theme } = useLayout();
+  const toolInfo = useToolInfo('show_capabilities');
+  const openExternal = useOpenExternal();
+  const sendFollowUpMessage = useSendFollowUpMessage();
+  const structured = toolInfo.structuredContent as
+    | { readonly status?: string; readonly note?: string }
+    | undefined;
+
+  return (
+    <main
+      className={`nw-shell${theme === 'dark' ? ' dark' : ''}`}
+      data-llm={`Food Ordering capabilities: ${capabilities.map((item) => item.name).join(', ')}`}
+    >
+      <section className="nw-card">
+        <header className="nw-header">
+          <span className="nw-icon" aria-hidden="true">
+            <PuzzleIcon />
+          </span>
+          <div className="nw-title-block">
+            <h1 className="nw-title">MCP capabilities</h1>
+            <p className="nw-subtitle">
+              {structured?.status ?? 'Food Ordering widget capabilities are ready.'}
+            </p>
+          </div>
+          <span className="nw-chip">Connected</span>
+        </header>
+        <div className="nw-body">
+          <p className="nw-section-title">Available features</p>
+          <ul className="nw-feature-list">
+            {capabilities.map((capability) => (
+              <li className="nw-feature" key={capability.name}>
+                <span className="nw-check" aria-hidden="true">
+                  <CheckIcon />
+                </span>
+                <span>
+                  <span className="nw-feature-name">{capability.name}</span>
+                  <span className="nw-feature-desc">{capability.description}</span>
+                </span>
+              </li>
+            ))}
+          </ul>
+          <div className="nw-actions">
+            <button
+              className="nw-button nw-button-primary"
+              type="button"
+              onClick={() =>
+                sendFollowUpMessage({
+                  prompt: 'Summarize what the Food Ordering MCP App widget demonstrates.',
+                })
+              }
+            >
+              <SparkIcon />
+              Ask assistant
+            </button>
+            <button
+              className="nw-button"
+              type="button"
+              onClick={() => openExternal('https://example.com/noodle-widget-docs')}
+            >
+              <ExternalIcon />
+              Open docs
+            </button>
+          </div>
+          {structured?.note ? <p className="nw-note">{structured.note}</p> : null}
+        </div>
+        <footer className="nw-footer">
+          <span className="nw-meta">
+            <ShieldIcon />
+            Secure widget surface
+          </span>
+          <span>v1.0.0</span>
+        </footer>
+      </section>
+    </main>
+  );
+}
+
+function PuzzleIcon() {
+  return (
+    <svg viewBox="0 0 24 24" aria-hidden="true">
+      <path d="M8 4h5v4h3a2 2 0 0 1 0 4h-3v3H9v-3H6a2 2 0 0 1 0-4h2V4Z" />
+      <path d="M13 15v5H4v-5" />
+      <path d="M13 20h7v-8" />
+    </svg>
+  );
+}
+
+function CheckIcon() {
+  return (
+    <svg viewBox="0 0 24 24" aria-hidden="true">
+      <path d="m6 12 4 4 8-8" />
+    </svg>
+  );
+}
+
+function SparkIcon() {
+  return (
+    <svg viewBox="0 0 24 24" aria-hidden="true">
+      <path d="m12 3 1.8 5.2L19 10l-5.2 1.8L12 17l-1.8-5.2L5 10l5.2-1.8L12 3Z" />
+    </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>
+  );
+}
+
+function ShieldIcon() {
+  return (
+    <svg viewBox="0 0 24 24" aria-hidden="true">
+      <path d="M12 3 5 6v5c0 4.4 2.8 8.3 7 10 4.2-1.7 7-5.6 7-10V6l-7-3Z" />
+      <path d="m9 12 2 2 4-4" />
+    </svg>
+  );
+}