@noodleseed/agent-kit 0.13.0 → 0.15.0

package/skills/codex/examples/food-ordering/vitest.config.ts

@@ -0,0 +1,30 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@noodleseed/one': new URL('../../packages/authoring/src/index.ts', import.meta.url).pathname,
+      '@noodle-borg/capabilities': new URL(
+        '../../packages/capabilities/src/index.ts',
+        import.meta.url,
+      ).pathname,
+      '@noodle-borg/compiler': new URL('../../packages/compiler/src/index.ts', import.meta.url)
+        .pathname,
+      '@noodle-borg/compute': new URL('../../packages/compute/src/index.ts', import.meta.url)
+        .pathname,
+      '@noodle-borg/connector-defs': new URL(
+        '../../packages/connector-defs/src/index.ts',
+        import.meta.url,
+      ).pathname,
+      '@noodle-borg/connector-http': new URL(
+        '../../packages/connector-http/src/index.ts',
+        import.meta.url,
+      ).pathname,
+      '@noodle-borg/runtime': new URL('../../packages/runtime/src/index.ts', import.meta.url)
+        .pathname,
+    },
+  },
+  test: {
+    include: ['test/**/*.test.ts'],
+  },
+});

package/skills/codex/examples/hello/README.md

@@ -0,0 +1,13 @@
+# hello — minimal TypeScript quickstart
+
+The smallest deployable Noodle app: a single `greet` tool authored in TypeScript with no
+connectors, secrets, flows, widgets, or handoff policy. It still uses the current server options form
+so new authors see where server-level branding belongs. Use it to smoke the author loop
+(`noodle validate` / `noodle dev`) or a first deploy.
+
+```sh
+noodle dev examples/hello/src/server.ts --app hello
+noodle deploy examples/hello/src/server.ts --org acme --app hello
+```
+
+It is also the fixture for `pnpm smoke:dev` and the e2e harness, so keep its tool surface stable.

package/skills/codex/examples/hello/noodle.json

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

package/skills/codex/examples/hello/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "hello",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "validate": "noodle validate",
+    "dev": "noodle dev",
+    "deploy": "noodle deploy"
+  },
+  "devDependencies": {
+    "@noodleseed/one": "latest",
+    "vitest": "latest"
+  }
+}

package/skills/codex/examples/hello/src/server.ts

@@ -0,0 +1,29 @@
+import { server, tool, z } from '@noodleseed/one';
+
+export default server(
+  'hello',
+  {
+    title: 'Hello',
+    version: '1.0.0',
+    branding: {
+      name: 'Hello',
+      accent: '#1D9E75',
+      radius: 'md',
+      density: 'comfortable',
+    },
+  },
+  [
+    tool('greet', {
+      description: 'Greet someone by name.',
+      input: z.object({
+        name: z.string(),
+      }),
+      output: z.object({
+        message: z.string(),
+      }),
+      fulfil: ({ input }) => {
+        return { message: `Hello, ${input.name}!` };
+      },
+    }),
+  ],
+);

package/skills/codex/examples/hello/test/server.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from 'vitest';
+import app from '../src/server.js';
+
+describe('hello example', () => {
+  it('exports a Noodle server definition', () => {
+    expect(typeof app.toManifest).toBe('function');
+  });
+});

package/skills/codex/examples/weather/README.md

@@ -0,0 +1,54 @@
+# Weather Briefing
+
+A single declarative tool that shows the runtime's breadth working together, with **no auth and no API
+keys**. The `weather_briefing` tool takes a city name and runs a **three-step flow**:
+
+Capability slots: HTTP connector authoring, ordered fulfilment flows, query/response mapping, and sandboxed
+compute.
+
+1. **`geo.search`** → geocode the city to coordinates (Open-Meteo Geocoding API)
+2. **`forecast.current`** → fetch current weather for those coordinates (Open-Meteo Forecast API)
+3. **`brief.summarize`** → derive a human-readable briefing in a **WASM/QuickJS compute sandbox**
+
+It exercises, in one TypeScript-authored app:
+
+- **Server-level branding** with semantic tokens carried through the runtime artifact for any generated
+  app surface.
+- **Ordered flow execution** with outputs threaded between steps (`${steps.geo.latitude}` → next step).
+- **Two HTTP connectors on two different hosts**, each with its own egress allowlist.
+- **Query parameters** (`query: [...]`) and a constant query baked into the path (`?current_weather=true`).
+- **Deep response mapping** with the `${...}` language (`${response.results[0].latitude}`,
+  `${response.current_weather.temperature}`).
+- **Sandboxed compute** (no network/fs/env/clock) turning raw numbers into conditions + advice.
+- **Typed input/output schemas** emitted as JSON Schema 2020-12.
+
+## Run it locally
+
+From the repo root, with the workspace built (`pnpm build`):
+
+```bash
+: # 1. boot the local loopback dev server
+node packages/cli/dist/cli.js dev examples/weather/src/server.ts --app weather
+
+: # 2. in another shell, call the printed local endpoint
+URL=http://127.0.0.1:<port>/o/local/weather/dev/mcp
+curl -s "$URL" \
+  -H 'content-type: application/json' \
+  -H 'accept: application/json, text/event-stream' \
+  -H 'mcp-protocol-version: 2025-11-25' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"weather_briefing","arguments":{"city":"Paris"}}}'
+```
+
+Example result (live data, abbreviated):
+
+```json
+{
+  "place": "Paris", "country": "France",
+  "temperature_c": 25.1, "windspeed_kmh": 8.3,
+  "conditions": "overcast",
+  "headline": "Paris, France: 25°C, overcast.",
+  "advice": "Comfortable conditions — no special prep needed."
+}
+```
+
+Try other cities (`Reykjavik`, `Singapore`, `Denver`) to see the conditions and advice change.

package/skills/codex/examples/weather/noodle.json

@@ -0,0 +1,4 @@
+{
+  "entrypoint": "src/server.ts",
+  "name": "weather"
+}

package/skills/codex/examples/weather/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "weather",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "validate": "noodle validate",
+    "dev": "noodle dev",
+    "deploy": "noodle deploy"
+  },
+  "devDependencies": {
+    "@noodleseed/one": "latest",
+    "vitest": "latest"
+  }
+}

package/skills/codex/examples/weather/src/server.ts

@@ -0,0 +1,190 @@
+import { connector, server, tool, z } from '@noodleseed/one';
+
+// The same Weather Briefing server, authored in TypeScript with the Noodle authoring SDK.
+//
+// The SDK owns the *manifest*: the tool, its Zod-typed input/output schemas, and the flow — which you
+// write as ordinary code in `fulfil` and the SDK records symbolically into ordered steps.
+//
+// HTTP and compute connectors are authored here too, so the public developer entrypoint is one
+// self-contained server.ts. The SDK still compiles this to internal manifest/catalog data for the runtime.
+
+const geocoding = connector('open_meteo_geocoding')
+  .version('1.0.0')
+  .http({
+    baseUrl: 'https://geocoding-api.open-meteo.com',
+    allowedOrigins: ['https://geocoding-api.open-meteo.com'],
+    operations: {
+      search: {
+        type: 'read',
+        method: 'GET',
+        path: '/v1/search',
+        query: ['name'],
+        input: { name: { type: 'string', required: true } },
+        output: {
+          latitude: { type: 'number', required: true },
+          longitude: { type: 'number', required: true },
+          place: { type: 'string' },
+          country: { type: 'string' },
+        },
+        response: {
+          latitude: '${response.results[0].latitude}',
+          longitude: '${response.results[0].longitude}',
+          place: '${response.results[0].name}',
+          country: '${response.results[0].country}',
+        },
+      },
+    },
+  });
+
+const forecast = connector('open_meteo_forecast')
+  .version('1.0.0')
+  .http({
+    baseUrl: 'https://api.open-meteo.com',
+    allowedOrigins: ['https://api.open-meteo.com'],
+    operations: {
+      current: {
+        type: 'read',
+        method: 'GET',
+        path: '/v1/forecast?current_weather=true',
+        query: ['latitude', 'longitude'],
+        input: {
+          latitude: { type: 'number', required: true },
+          longitude: { type: 'number', required: true },
+        },
+        output: {
+          temperature: { type: 'number' },
+          windspeed: { type: 'number' },
+          weathercode: { type: 'number' },
+        },
+        response: {
+          temperature: '${response.current_weather.temperature}',
+          windspeed: '${response.current_weather.windspeed}',
+          weathercode: '${response.current_weather.weathercode}',
+        },
+      },
+    },
+  });
+
+const brief = connector('weather_brief')
+  .version('1.0.0')
+  .compute('summarize', {
+    type: 'read',
+    input: {
+      place: { type: 'string', required: true },
+      country: { type: 'string' },
+      temperature: { type: 'number', required: true },
+      windspeed: { type: 'number', required: true },
+      weathercode: { type: 'number', required: true },
+    },
+    output: {
+      conditions: { type: 'string', required: true },
+      headline: { type: 'string', required: true },
+      advice: { type: 'string', required: true },
+    },
+    // A real function — type-checked here, serialized to source and run in the sandbox. It must be
+    // self-contained: no imports, no closure over outer variables, synchronous.
+    run: (input) => {
+      const codes: Record<number, string> = {
+        0: 'clear sky',
+        1: 'mainly clear',
+        2: 'partly cloudy',
+        3: 'overcast',
+        45: 'fog',
+        48: 'depositing rime fog',
+        51: 'light drizzle',
+        53: 'moderate drizzle',
+        55: 'dense drizzle',
+        61: 'slight rain',
+        63: 'moderate rain',
+        65: 'heavy rain',
+        71: 'slight snow',
+        73: 'moderate snow',
+        75: 'heavy snow',
+        77: 'snow grains',
+        80: 'slight rain showers',
+        81: 'moderate rain showers',
+        82: 'violent rain showers',
+        85: 'slight snow showers',
+        86: 'heavy snow showers',
+        95: 'thunderstorm',
+        96: 'thunderstorm with hail',
+        99: 'thunderstorm with heavy hail',
+      };
+      const code = Number(input.weathercode);
+      const conditions = codes[code] || 'unknown conditions';
+      const temp = Math.round(Number(input.temperature));
+      const wind = Math.round(Number(input.windspeed));
+      const where = input.country ? `${input.place}, ${input.country}` : input.place;
+      const headline = `${where}: ${temp}°C, ${conditions}.`;
+      const tips: string[] = [];
+      if (temp <= 0) tips.push("bundle up, it's freezing");
+      else if (temp <= 10) tips.push('wear a warm coat');
+      else if (temp >= 28) tips.push("stay hydrated, it's hot");
+      if (code >= 95) tips.push('thunderstorms expected — seek shelter');
+      else if (code >= 71 && code <= 86 && code !== 80 && code !== 81 && code !== 82)
+        tips.push('snow — dress warm and tread carefully');
+      else if (code >= 51 && code <= 82) tips.push('bring an umbrella');
+      if (wind >= 30) tips.push('expect strong winds');
+      const advice = tips.length
+        ? `${tips.join('; ')}.`
+        : 'Comfortable conditions — no special prep needed.';
+      return { conditions, headline, advice };
+    },
+  });
+
+export default server(
+  'weather_briefing',
+  {
+    title: 'Weather Briefing',
+    version: '1.0.0',
+    use: { geo: geocoding, forecast, brief },
+    branding: {
+      name: 'Weather Briefing',
+      accent: '#0284C7',
+      radius: 'md',
+      density: 'comfortable',
+    },
+  },
+  [
+    tool('weather_briefing', {
+      description:
+        'Look up a city, fetch its current weather, and return a human-readable briefing. Runs a ' +
+        'three-step flow: geocode the city, fetch the forecast, then derive the briefing in a sandboxed compute step.',
+      input: z.object({
+        city: z.string(),
+      }),
+      output: z.object({
+        place: z.string(),
+        country: z.string(),
+        temperature_c: z.number(),
+        windspeed_kmh: z.number(),
+        conditions: z.string(),
+        headline: z.string(),
+        advice: z.string(),
+      }),
+      fulfil: ({ input, connectors }) => {
+        const located = connectors.geo.search({ name: input.city });
+        const weather = connectors.forecast.current({
+          latitude: located.latitude,
+          longitude: located.longitude,
+        });
+        const briefing = connectors.brief.summarize({
+          place: located.place,
+          country: located.country,
+          temperature: weather.temperature,
+          windspeed: weather.windspeed,
+          weathercode: weather.weathercode,
+        });
+        return {
+          place: located.place,
+          country: located.country,
+          temperature_c: weather.temperature,
+          windspeed_kmh: weather.windspeed,
+          conditions: briefing.conditions,
+          headline: briefing.headline,
+          advice: briefing.advice,
+        };
+      },
+    }),
+  ],
+);

package/skills/codex/examples/weather/test/server.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from 'vitest';
+import app from '../src/server.js';
+
+describe('weather example', () => {
+  it('exports a Noodle server definition', () => {
+    expect(typeof app.toManifest).toBe('function');
+  });
+});

package/skills/codex/references/chatgpt-compliance.md

@@ -0,0 +1,63 @@
+# ChatGPT App compliance (pre-submission)
+
+`noodle check --target chatgpt` verifies the *metadata* prerequisites; app-store submission also faces a
+human review against OpenAI’s Apps SDK UX principles. Run this checklist against the built app before
+submitting, and render it as an audit table in the design wireframe (`design/wireframe.html` in the
+`acme-*` examples) so partners and reviewers see it up front.
+
+## Contents
+
+- Metadata gate vs review
+- Pre-submission checklist
+- UI guidelines
+- Domain guardrails
+- Privacy and data
+
+## Metadata gate vs review
+
+`noodle check --target chatgpt --json` returning `ok:true` means the widget is *metadata-ready* (widget
+`domain`, `openai/outputTemplate`, CSP, tool annotations, and `invoking`/`invoked` invocation copy are
+present) — it does NOT prove host rendering, conversation UX, or submission acceptance. Validate real
+rendering in ChatGPT Developer Mode / MCP Inspector, then run the checklist below.
+
+## Pre-submission checklist (what review looks for)
+
+1. **Conversational value** — at least one capability relies on ChatGPT’s strengths: natural-language
+   actions no tap-driven app can do (e.g. "two margheritas and a lemon tart" parses into a cart). Cite
+   concrete app behavior, not aspirations.
+2. **Beyond base ChatGPT** — new knowledge, actions, or presentation (grounded partner data, live
+   inventory, signed handoffs, real-world routing).
+3. **Atomic, model-friendly actions** — self-contained tools with explicit input/output schemas, and an
+   annotation on every tool (`annotations.readOnly()` / `.action()` / `.openAction()`).
+4. **Helpful UI only** — justify each widget (would plain text degrade UX?), and note what you
+   deliberately did NOT build a widget for (payment is off-app → no payment widget).
+5. **In-chat task completion** — the user finishes a meaningful task in chat. For a top-of-funnel app,
+   the task is the discovery/config loop completed in-chat with an intentional handoff.
+6. **Performance** — tool calls scoped per step; response-time targets stated.
+7. **Discoverability** — broad, natural trigger prompts listed; description keywords planned. Golden
+   prompt sets and metadata optimization are a launch workstream, not polish.
+8. **Platform fit** — multi-turn dialogue, conversation memory, and multimodality where genuinely useful.
+
+## UI guidelines
+
+System fonts, monochrome outlined icons, WCAG AA contrast, at most two actions on inline cards, no nested
+scroll, and the right display mode per intent (inline by default; fullscreen only where browsing needs
+it; picture-in-picture only for live state). Brand only through `server` `branding` tokens — accent on
+the primary CTA, logo, and badges, nothing else; the compiler derives the palette. Never inject raw
+global CSS.
+
+## Domain guardrails
+
+For regulated-adjacent apps, add app-specific trust behaviors and **show them in the rendered pixels**:
+cite the source and its revision for consequential lookups; frame regulated content as "considerations,
+not a ruling"; never invent compatibility, availability, or pricing; and always show the relevant
+caution/disclaimer. These are what make a regulated-adjacent app approvable.
+
+## Privacy and data
+
+Data flows through OpenAI; tool payloads and whatever the server stores must match the partner’s privacy
+policy. No payment happens in chat (PCI stays off-app). Avoid per-user OAuth in a top-of-funnel v1 (use
+service credentials via a `connector`); add end-user auth only for two-way apps (`customerAuth`). Keep
+secrets out of tool output, widgets, and logs. If the partner’s published policy predates the app, flag a
+privacy gap for their counsel before submission. Re-run this checklist against the *built* app before
+every submission — not just the wireframe.

package/skills/codex/references/connect-an-api.md

@@ -0,0 +1,76 @@
+# Connect a live API (you were given a key)
+
+When the user hands you an API key or credentials, don't infer the data from documentation — docs
+drift. Probe the live API, learn the real shape, then encode it as a `connector`. The loop:
+
+## Contents
+
+- Secure the key first
+- Probe the live API
+- Model the connector from the observed shape
+- Design intent tools
+- Prove real output
+- Then build the app
+
+## Secure the key first
+
+Never inline or log the key. Have the user put it in an environment variable, then store it as a
+managed secret and reference it only as `secret(...)`:
+
+```sh
+export SOME_API_KEY=…            # the user sets this; it never appears in a file or prompt
+noodle secrets set SOME_API_KEY --from-env SOME_API_KEY
+```
+
+In `server.ts` the key is only ever `secret("SOME_API_KEY")` — keep the raw value out of code, tests,
+prompts, logs, and generated files.
+
+## Probe the live API
+
+Learn the actual response shape empirically. Two ways — capture one real example response per endpoint
+you will use, and read its field names, nesting, array shapes, pagination, and id-vs-label fields:
+
+- **With your own HTTP/shell tool** — call a representative read endpoint using the key **from the env
+  var**, never the literal (so it stays out of logs): `curl -H "Authorization: Bearer $SOME_API_KEY"
+  https://api.example.com/things`. Inspect the returned JSON.
+- **Noodle-native** — author a minimal read operation that maps the whole body (`response: { raw:
+  '${response}' }`), `noodle secrets set` the key, then `noodle tools call` it to see the real payload
+  in-process.
+
+## Model the connector from the observed shape
+
+Encode the API as an HTTP connector, mapping only the fields you actually saw into a small typed
+`output`:
+
+- `connector("id").version("1.0.0").http({ baseUrl, allowedOrigins, auth, operations })`.
+- `auth: { kind: 'bearer', secret: secret('SOME_API_KEY') }` — or `{ kind: 'apiKey', header: 'X-API-Key',
+  secret: secret('SOME_API_KEY') }`. Never put the credential in operation `headers`.
+- Per operation: `method`, `path` (with `{id}` templates), `query: ["arg"]` for URL params, `input`,
+  `output`, and a `response` mapping whose `${response.path}` matches the real JSON — the parsed body is
+  bound directly to `${response}` (no `.body` envelope); use bracket indices for arrays
+  (`${response.results[0].id}`).
+
+The full connector shape, every `auth.kind`, and compute connectors are in
+`references/authoring-workflow.md`.
+
+## Design intent tools
+
+Shape tools around what the user says, not 1:1 around endpoints. Pair an id-taking action with a
+find/search operation that returns `{ id, label }` summaries so the model resolves text → id itself,
+and map each response to a few labelled fields the model can speak from. See the "Design tools for the
+model" section of `references/authoring-workflow.md`.
+
+## Prove real output
+
+`noodle validate` / `noodle test` prove a connector tool *compiles and registers* — not that its
+mapping returns data. With the secret set, run a live read: `noodle tools call <read_tool> --args
+'{…}'` executes the connector against the real API in-process. Confirm the mapped fields are populated,
+not `undefined`; if they are empty, fix the `${response…}` paths against the real payload and re-run.
+Only run a live write if it is safe or the user approved it.
+
+## Then build the app
+
+With real data flowing, design the experience (`references/experience-design.md`), add widgets where a
+UI genuinely helps (`references/widgets-and-apps.md`), and verify with `noodle check`. Deploy per
+`references/deploy-and-ops.md`, and set the same secret in the hosted environment with `noodle secrets
+set` before the first hosted call.

package/skills/codex/references/examples.md

@@ -1,12 +1,24 @@
 # Examples
 
-Flagship examples (one per capability). Read the matching example for the pattern you need; extend an existing flagship rather than inventing a new shape.
+Flagship examples, one per capability. The **bundled** rows ship inside this skill under `examples/<name>/` (the real `server.ts`, `src/views/*.tsx`, and — for the design-first flagships — a `design/` set); read them locally at the paths shown. The rest live only in the Noodle Seed repository under `examples/<name>/` on GitHub. Extend an existing flagship rather than inventing a new shape.
+
+## Bundled in this skill — read locally
+
+Paths are relative to this skill directory. Assets (images/fonts) are omitted from the bundle; fetch the full runnable example from the repository if you need them. Verify any edit with `noodle validate --json` then `noodle test --json`.
+
+| Example | Use when | Read |
+| :-- | :-- | :-- |
+| `hello` | Minimal TypeScript quickstart — a single tool, no connectors/widgets. | `examples/hello/src/server.ts` |
+| `weather` | HTTP connectors, multi-step flows, and the sandboxed compute connector. | `examples/weather/src/server.ts` |
+| `food-ordering` | Consumer ordering MCP App widgets, app-only helpers, cart state, assets, branding, and handoff. | `examples/food-ordering/src/server.ts` |
+| `acme-discovery` | Top-of-funnel discovery→handoff: a discovery carousel, a `create_handoff` deep link, and a design-first UX spec + wireframe. | `examples/acme-discovery/src/server.ts` + `design/` |
+| `acme-tasks` | A two-way productivity app designed around its top-3 prioritized flows (capture/prioritize/complete), with a design-first flow spec + wireframe. | `examples/acme-tasks/src/server.ts` + `design/` |
+| `acme-bistro` | End-to-end ordering with a payment-only handoff; ships a gold-standard `design/` set (UX doc, wireframe with compliance audit, API contract). | `examples/acme-bistro/src/server.ts` + `design/` |
+
+## In the repository only — `examples/<name>/` on GitHub
 
 | Example | Use when |
 | :-- | :-- |
-| `hello` | Minimal TypeScript quickstart — a single tool, no connectors/widgets. |
-| `weather` | HTTP connectors, multi-step flows, and the sandboxed compute connector. |
-| `food-ordering` | Consumer ordering MCP App widgets, app-only helpers, cart state, assets, branding, and handoff. |
 | `customer-auth` | End-user (customer) auth via OIDC/Firebase bridge with delegated credentials. |
 | `stateful-draft` | Durable, caller-scoped widget state handles with optimistic revisions. |
 | `perplexity` | A real SaaS API with bearer auth and a managed `secret`. |