@noodleseed/agent-kit 0.13.0 → 0.15.0

package/skills/codex/examples/acme-tasks/noodle.json

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

package/skills/codex/examples/acme-tasks/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "acme-tasks",
+  "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/codex/examples/acme-tasks/src/helpers.ts

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

package/skills/codex/examples/acme-tasks/src/server.ts

@@ -0,0 +1,141 @@
+import { annotations, server, tool, toolForWidget, toolWithWidget, z } from '@noodleseed/one';
+
+// Acme Tasks is a fictional productivity app. It is a two-way (read + write) experience rather than a
+// top-of-funnel handoff: the top-3 prioritized user flows all complete in chat — Capture, Prioritize,
+// and Complete. It is the flagship for designing an app around its prioritized flows (see the README).
+//
+// Authoring notes:
+// - A tool `fulfil` is *recorded*, not run as live JS. Place inputs directly into an output string as
+//   `${input.x}` so they substitute at runtime; do not transform them (no arithmetic/filter on inputs).
+//   The seed list below is static data the runtime returns verbatim — the "today" view.
+// - A real deployment would connect the user's account with the end-user auth pattern (see the
+//   `customer-auth` example); this example keeps a seeded list so the focus stays on the flows.
+
+const today = [
+  {
+    id: 'email_vendor',
+    title: 'Email the vendor about the Q3 quote',
+    priority: 'high',
+    done: false,
+  },
+  { id: 'review_pr', title: 'Review the analytics pull request', priority: 'medium', done: false },
+  { id: 'book_offsite', title: 'Book flights for the team offsite', priority: 'low', done: false },
+] as const;
+
+const priority = z.enum(['high', 'medium', 'low']);
+
+// Tool annotations for host planners: listing is read-only; capture/complete/re-prioritize are local
+// non-destructive writes.
+const readOnly = annotations.readOnly();
+const localWrite = annotations.localAction({ destructive: false });
+
+const taskOutput = z.object({
+  id: z.string(),
+  title: z.string(),
+  priority,
+  done: z.boolean(),
+});
+
+export default server(
+  'acme_tasks',
+  {
+    title: 'Acme Tasks',
+    version: '1.0.0',
+    branding: {
+      name: 'Acme Tasks',
+      accent: '#7C3AED',
+      surface: '#F5F3FF',
+      surfaceDark: '#161228',
+      radius: 'lg',
+      density: 'comfortable',
+    },
+  },
+  [
+    // Flow 2 — Prioritize / Today: render the list so the human triages and the model can speak to it.
+    toolWithWidget('list_today', {
+      description: 'Show today’s Acme Tasks and render the task-list widget.',
+      annotations: readOnly,
+      input: z.object({ focus: z.string().default('today') }),
+      output: z.object({
+        status: z.string(),
+        focus: z.string(),
+        tasks: z.array(taskOutput),
+      }),
+      fulfil: ({ input }) => ({
+        status: `Acme Tasks for ${input.focus}: ${today.length} open items, highest priority first.`,
+        focus: input.focus,
+        tasks: today,
+      }),
+      widgetTitle: 'Today’s tasks',
+      widgetDescription: 'A prioritized task list: capture, re-prioritize, and complete in place.',
+      // ChatGPT host status copy (openai/toolInvocation/*) — required for widget-opening tools.
+      invoking: 'Loading your tasks…',
+      invoked: 'Tasks ready',
+      domain: 'https://tasks.acme.example',
+      view: {
+        component: 'task-list',
+        entry: './views/task-list.tsx',
+      },
+      csp: {
+        connectDomains: ['https://acme.example'],
+        resourceDomains: ['https://acme.example'],
+        frameDomains: ['https://acme.example'],
+      },
+    }),
+    // Flow 1 — Capture: add a task from natural language ("remind me to email the vendor").
+    tool('add_task', {
+      description: 'Capture a new Acme task with a title and priority.',
+      annotations: localWrite,
+      input: z.object({
+        title: z.string(),
+        priority: priority.default('medium'),
+      }),
+      output: z.object({
+        status: z.string(),
+        title: z.string(),
+        priority,
+      }),
+      fulfil: ({ input }) => ({
+        status: `Added “${input.title}” (${input.priority}).`,
+        title: input.title,
+        priority: input.priority,
+      }),
+    }),
+    // Flow 3 — Complete: mark a task done. Model-visible so the model can complete on request.
+    tool('complete_task', {
+      description: 'Mark an Acme task complete. Pass the task id and its title.',
+      annotations: localWrite,
+      input: z.object({
+        task: z.string(),
+        title: z.string().min(1),
+      }),
+      output: z.object({
+        status: z.string(),
+        task: z.string(),
+      }),
+      fulfil: ({ input }) => ({
+        status: `Completed “${input.title}”.`,
+        task: input.task,
+      }),
+    }),
+    // Flow 2 helper (widget-only): re-prioritize a task from the list widget.
+    toolForWidget('set_priority', {
+      description: 'Re-prioritize a task from the list widget.',
+      annotations: localWrite,
+      input: z.object({
+        task: z.string(),
+        priority,
+      }),
+      output: z.object({
+        status: z.string(),
+        task: z.string(),
+        priority,
+      }),
+      fulfil: ({ input }) => ({
+        status: `Set ${input.task} to ${input.priority} priority.`,
+        task: input.task,
+        priority: input.priority,
+      }),
+    }),
+  ],
+);

package/skills/codex/examples/acme-tasks/src/views/task-list.tsx

@@ -0,0 +1,177 @@
+import { useState } from 'react';
+import { useCallTool, useLayout, useToolInfo, useViewState } from '../helpers.js';
+import './widget-style.css';
+
+type Priority = 'high' | 'medium' | 'low';
+
+type Task = {
+  readonly id: string;
+  readonly title: string;
+  readonly priority: Priority;
+  readonly done: boolean;
+};
+
+const PRIORITIES: readonly Priority[] = ['high', 'medium', 'low'];
+
+function asToday(value: unknown) {
+  return value as { readonly status?: string; readonly tasks?: readonly Task[] } | undefined;
+}
+
+export default function TaskList() {
+  const { displayMode, theme } = useLayout();
+  const today = asToday(useToolInfo('list_today').structuredContent);
+  const addTask = useCallTool('add_task');
+  const completeTask = useCallTool('complete_task');
+  const setPriorityTool = useCallTool('set_priority');
+
+  const seeded = today?.tasks ?? [];
+  // Local, session-scoped state layered over the seeded list — the three flows write here and record
+  // the change through a tool call. Captured tasks live in `added` so the list updates in place.
+  const [added, setAdded] = useState<readonly Task[]>([]);
+  const [done, setDone] = useState<readonly string[]>([]);
+  const [priority, setPriority] = useState<Record<string, Priority>>({});
+  const [draft, setDraft] = useViewState('draft', '');
+  const [status, setStatus] = useState(today?.status ?? 'Capture, prioritize, and complete.');
+
+  const tasks: readonly Task[] = [...seeded, ...added];
+  const openCount = tasks.filter((task) => !done.includes(task.id)).length;
+
+  // Each flow updates local state optimistically, then records the change through a tool call. If the
+  // call fails, revert the optimistic change and surface a failure message instead of a false success.
+  async function capture() {
+    const title = draft.trim();
+    if (title.length === 0) return;
+    const id = `added_${added.length}`;
+    setAdded((current) => [...current, { id, title, priority: 'medium', done: false }]);
+    setDraft('');
+    try {
+      const result = await addTask.callTool({ title, priority: 'medium' });
+      const structured = result.structuredContent as { readonly status?: string } | undefined;
+      setStatus(structured?.status ?? `Added “${title}”.`);
+    } catch {
+      setAdded((current) => current.filter((task) => task.id !== id));
+      setStatus(`Couldn't add “${title}” — try again.`);
+    }
+  }
+
+  async function reprioritize(task: Task, next: Priority) {
+    const prev = priority[task.id];
+    setPriority((current) => ({ ...current, [task.id]: next }));
+    try {
+      const result = await setPriorityTool.callTool({ task: task.id, priority: next });
+      const structured = result.structuredContent as { readonly status?: string } | undefined;
+      setStatus(structured?.status ?? `Set ${task.title} to ${next}.`);
+    } catch {
+      setPriority((current) => {
+        const restored = { ...current };
+        if (prev === undefined) delete restored[task.id];
+        else restored[task.id] = prev;
+        return restored;
+      });
+      setStatus(`Couldn't re-prioritize ${task.title} — try again.`);
+    }
+  }
+
+  async function complete(task: Task) {
+    setDone((current) => [...current, task.id]);
+    try {
+      const result = await completeTask.callTool({ task: task.id, title: task.title });
+      const structured = result.structuredContent as { readonly status?: string } | undefined;
+      setStatus(structured?.status ?? `Completed “${task.title}”.`);
+    } catch {
+      setDone((current) => current.filter((id) => id !== task.id));
+      setStatus(`Couldn't complete “${task.title}” — try again.`);
+    }
+  }
+
+  return (
+    <main
+      className={`nw-shell${theme === 'dark' ? ' dark' : ''}`}
+      data-llm={`Acme Tasks: ${openCount} open of ${tasks.length}; ${done.length} completed this session`}
+    >
+      <section className="nw-card">
+        <header className="nw-header">
+          <span className="nw-icon" aria-hidden="true">
+            <CheckIcon />
+          </span>
+          <div className="nw-title-block">
+            <h1 className="nw-title">Acme Tasks</h1>
+            <p className="nw-subtitle" aria-live="polite">
+              {status}
+            </p>
+          </div>
+          <span className="nw-chip">
+            {displayMode === 'fullscreen' ? 'Fullscreen' : `${openCount} open`}
+          </span>
+        </header>
+
+        {/* Flow 1 — Capture */}
+        <div className="nw-capture">
+          <input
+            className="nw-input"
+            placeholder="Add a task…"
+            value={draft}
+            onChange={(event) => setDraft(event.currentTarget.value)}
+            onKeyDown={(event) => {
+              if (event.key === 'Enter') capture();
+            }}
+          />
+          <button
+            className="nw-button nw-button-primary"
+            type="button"
+            disabled={addTask.isPending}
+            onClick={capture}
+          >
+            Add
+          </button>
+        </div>
+
+        {/* Flow 2 — Prioritize, Flow 3 — Complete */}
+        <ul className="nw-list">
+          {tasks.map((task) => {
+            const isDone = done.includes(task.id);
+            const level = priority[task.id] ?? task.priority;
+            return (
+              <li className={`nw-task${isDone ? ' nw-task-done' : ''}`} key={task.id}>
+                <button
+                  aria-label={isDone ? 'Completed' : 'Complete task'}
+                  className={`nw-check${isDone ? ' nw-check-on' : ''}`}
+                  type="button"
+                  disabled={isDone}
+                  onClick={() => complete(task)}
+                >
+                  {isDone ? '✓' : ''}
+                </button>
+                <span className="nw-task-title">{task.title}</span>
+                <select
+                  aria-label="Priority"
+                  className={`nw-priority nw-priority-${level}`}
+                  value={level}
+                  disabled={isDone}
+                  onChange={(event) => reprioritize(task, event.currentTarget.value as Priority)}
+                >
+                  {PRIORITIES.map((entry) => (
+                    <option key={entry} value={entry}>
+                      {entry}
+                    </option>
+                  ))}
+                </select>
+              </li>
+            );
+          })}
+        </ul>
+        <p className="nw-note">
+          Two-way in chat: read your list, capture, re-prioritize, and complete.
+        </p>
+      </section>
+    </main>
+  );
+}
+
+function CheckIcon() {
+  return (
+    <svg viewBox="0 0 24 24" aria-hidden="true">
+      <path d="M4 12.5 9 17l11-11" />
+    </svg>
+  );
+}

package/skills/codex/examples/acme-tasks/src/views/widget-style.css

@@ -0,0 +1,227 @@
+: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: #f7f5ff;
+  --nw-text: #1c1830;
+  --nw-muted: #635d80;
+  --nw-border: #e2ddf5;
+  --nw-accent: #7c3aed;
+  --nw-accent-strong: #6d28d9;
+  --nw-accent-soft: #efe9ff;
+  --nw-high: #dc2626;
+  --nw-medium: #b45309;
+  --nw-low: #2563eb;
+  --nw-radius: 10px;
+  --nw-shadow: 0 18px 50px rgb(30 20 60 / 12%);
+}
+
+.dark,
+[data-theme="dark"] {
+  --nw-bg: #161228;
+  --nw-surface: #1d1735;
+  --nw-text: #f2eeff;
+  --nw-muted: #a99fce;
+  --nw-border: #342a54;
+  --nw-accent: #a78bfa;
+  --nw-accent-strong: #8b5cf6;
+  --nw-accent-soft: #2a2148;
+  --nw-high: #f87171;
+  --nw-medium: #fbbf24;
+  --nw-low: #60a5fa;
+  --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,
+input,
+select {
+  font: inherit;
+}
+
+.nw-shell {
+  min-height: 100vh;
+  padding: 14px;
+  background: var(--nw-bg);
+  color: var(--nw-text);
+}
+
+.nw-card {
+  max-width: 620px;
+  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: 2;
+  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-capture {
+  display: flex;
+  gap: 8px;
+  padding: 14px 16px 4px;
+}
+
+.nw-input {
+  flex: 1;
+  padding: 9px 12px;
+  border: 1px solid var(--nw-border);
+  border-radius: 10px;
+  background: var(--nw-bg);
+  color: var(--nw-text);
+}
+
+.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-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-list {
+  list-style: none;
+  margin: 0;
+  padding: 8px 16px 4px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.nw-task {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 12px;
+  border: 1px solid var(--nw-border);
+  border-radius: 12px;
+  background: var(--nw-bg);
+}
+
+.nw-task-title {
+  flex: 1;
+  min-width: 0;
+}
+
+.nw-task-done {
+  opacity: 0.55;
+}
+
+.nw-task-done .nw-task-title {
+  text-decoration: line-through;
+}
+
+.nw-check {
+  width: 22px;
+  height: 22px;
+  border: 1.5px solid var(--nw-border);
+  border-radius: 999px;
+  background: transparent;
+  color: #ffffff;
+  cursor: pointer;
+  flex: none;
+}
+
+.nw-check-on {
+  background: var(--nw-accent);
+  border-color: var(--nw-accent);
+}
+
+.nw-priority {
+  padding: 5px 8px;
+  border: 1px solid var(--nw-border);
+  border-radius: 8px;
+  background: var(--nw-bg);
+  color: var(--nw-text);
+  font-size: 12px;
+  font-weight: 600;
+}
+
+.nw-priority-high {
+  color: var(--nw-high);
+}
+
+.nw-priority-medium {
+  color: var(--nw-medium);
+}
+
+.nw-priority-low {
+  color: var(--nw-low);
+}
+
+.nw-note {
+  margin: 0;
+  padding: 8px 16px 16px;
+  font-size: 12px;
+  color: var(--nw-muted);
+}

package/skills/codex/examples/acme-tasks/test/server.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import app from '../src/server.js';
+
+describe('acme-tasks example', () => {
+  it('exports a Noodle server definition', () => {
+    expect(typeof app.toManifest).toBe('function');
+  });
+
+  it('exposes a tool for each of the top-3 prioritized flows', async () => {
+    // Capture → add_task, Prioritize → list_today (+ set_priority helper), Complete → complete_task.
+    const text = JSON.stringify(await app.toManifest());
+    expect(text).toContain('add_task');
+    expect(text).toContain('list_today');
+    expect(text).toContain('complete_task');
+    expect(text).toContain('set_priority');
+  });
+
+  it('seeds today’s list highest-priority first', async () => {
+    const text = JSON.stringify(await app.toManifest());
+    expect(text).toMatch(/"tasks":\[\{"id":"email_vendor".*"priority":"high"/);
+  });
+});

package/skills/codex/examples/acme-tasks/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/codex/examples/food-ordering/README.md

@@ -0,0 +1,82 @@
+# Food Ordering
+
+**Owns:** The flagship consumer ordering MCP App example: React view authoring, app-only helper tools,
+caller-scoped cart state handles, packaged image assets, checkout handoff policy, host actions,
+CSP/permissions metadata, and widget preview coverage.
+
+Food Ordering is a generic, synthetic version of a live marketplace ordering app. It lets a user search
+stores, browse menus, customize an item, build a multi-line cart, review the order, and hand off checkout to
+an allowlisted example domain. It does not use real restaurant APIs, real checkout, customer credentials, or
+private customer data.
+
+## What It Shows
+
+| Capability | Example |
+| :--- | :--- |
+| Public entry tool | `open_ordering` returns structured fallback content and renders the React widget |
+| App-only helper tools | `search_stores`, `load_menu`, `load_item`, `read_cart`, `sync_cart`, `prepare_checkout` |
+| Durable cart state | `server(..., { state: { handles: { cart } }, use: { state } })` with caller scope and revision checks |
+| React app runtime kit | `@noodleseed/one/react` supplies app flow, shell/nav/view, async state, form, quantity, choice, and handoff primitives |
+| Multi-step widget flow | One React shell navigates stores, menu, item customization, cart, review, and handoff views through `useAppFlow` |
+| Handoff | `handoff.allowedDomains` allows only `https://orders.example.com` checkout URLs |
+| Progressive enhancement | Non-Apps hosts still receive stores, featured items, and a readable fallback summary |
+
+## Local Author Loop
+
+```sh
+noodle validate
+noodle test
+noodle dev
+```
+
+In another terminal:
+
+```sh
+noodle tools list
+noodle tools call open_ordering --args '{"customer":"Asha","query":"noodles"}'
+noodle tools call summarize_ordering_options --args '{}'
+```
+
+For Apps metadata conformance, start `noodle dev`, copy the loopback MCP endpoint, then run:
+
+```sh
+npx @mcpjam/cli@latest apps conformance --url http://127.0.0.1:<port>/o/demo/food-ordering/mcp --quiet --format json
+```
+
+## Client Setup
+
+Use the CLI to print the exact setup flow for your MCP client:
+
+```sh
+noodle connect claude
+noodle connect chatgpt
+noodle connect inspector
+```
+
+## Deploy
+
+```sh
+noodle link --org demo --app food-ordering
+noodle deploy --access owner-only
+noodle open
+```
+
+Use `--access org-members` for an org-wide internal demo. This example has no connector secrets and does not
+include tokens, caller-key mechanisms, or `.env.noodle` values.
+
+## Demo Assets
+
+The packaged demo images live under `assets/` and are public web assets when deployed. The current app uses
+`assets/noodle-bowl.jpg` as the server branding image.
+
+Image sources:
+
+- `assets/noodle-bowl.jpg` — Unsplash photo
+  [`IRv8V9Hb8gI`](https://unsplash.com/photos/IRv8V9Hb8gI), downloaded from Unsplash.
+- `assets/lentil-soup.jpg` — Unsplash image
+  [`photo-1510431198580-7727c9fa1e3a`](https://images.unsplash.com/photo-1510431198580-7727c9fa1e3a), downloaded from Unsplash.
+- `assets/mint-lemonade.jpg` — Unsplash photo
+  [`X7Nx327NtuA`](https://unsplash.com/photos/X7Nx327NtuA) by Imad 786.
+
+Unsplash photos are free to use under the [Unsplash License](https://unsplash.com/license); attribution is
+not required, but source notes are kept here for provenance.

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

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