@noodleseed/agent-kit 0.9.0 → 0.10.0

package/skills/codex/references/sdk-surface.md

@@ -3,43 +3,51 @@
 Import these from `@noodleseed/one`. They are declarative builders that emit manifest data — do not hand-author the manifest or runtime artifacts. React view helpers come from `@noodleseed/one/react` (`generateHelpers`); the hook surface is documented in `widgets-and-apps.md`.
 Platform helper connectors are explicit subpath imports from `@noodleseed/one/platform` (`noodlePlatform`, `noodlePlatformCatalog`) when an app needs first-party hosted state APIs.
 
-## Server & tools
+## Contents
+
+- Exports by area
+- Authoring signatures
+- Recipes
+
+## Exports by area
+
+### Server & tools
 
 - `server(name, options, definitions)` — the server/app root.
 - `tool(name, { description, input, output, fulfil })` — a model-visible tool.
 - `toolWithWidget(name, { ..., view })` — a model-visible tool that renders an MCP Apps widget.
 - `toolForWidget(name, { ... })` — a widget-only helper tool, hidden from the model.
 
-## Widgets & assets
+### Widgets & assets
 
 - `widget(...)` — declare a widget/view component.
 - `asset("./path")` — reference a packaged asset (e.g. an image).
 - `annotations(...)` — tool/Apps annotation metadata.
 
-## Connectors & flows
+### Connectors & flows
 
 - `connector("id").version(...).http({...})` or `.compute(...)` — declarative data connectors.
 - `when(...)` — declarative conditions for recorded flows (no native branching on runtime values).
 
-## Resources & prompts
+### Resources & prompts
 
 - `resource(name, { ... })` — an MCP resource.
 - `prompt(name, { ... })` — an MCP prompt.
 
-## Managed config
+### Managed config
 
 - `secret("NAME")` — reference a managed secret (operated via `noodle secrets`).
 - `variable("NAME")` — reference a managed variable (operated via `noodle variables`).
 
-## Customer auth
+### Customer auth
 
 - `customerAuth.oidc(...)`, `.firebase(...)`, `.microsoft(...)`, or `.bridge(...)` — end-user/customer identity for `--access customers` deployments.
 
-## Sessions
+### Sessions
 
 - `handoffSession(...)` — typed cross-host handoff session envelopes.
 
-## Schemas
+### Schemas
 
 - `z` — Zod, for input/output schemas (compiles to JSON Schema 2020-12).
 
@@ -52,4 +60,121 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
 - `resource(name, { uri, description?, mimeType?, fulfil })` and `prompt(name, { description?, arguments?, fulfil })` expose MCP resources/prompts.
 - `widget(name, { title, view, csp?, domain?, permissions? })` declares reusable view metadata; `asset("./path")` packages local files.
 - `customerAuth.*(...)` belongs in `server` options when deployed customer callers need verified identity; inspect `examples/customer-auth` or `examples/sharepoint` before using it.
-- `state` defines durable widget state handles; `handoff` declares allowed external domains for safe host handoff.
+- `state` defines durable widget state handles; `handoff` declares allowed external domains for safe host handoff.
+
+## Recipes
+
+Minimal, complete, compiling recipes — author in `src/server.ts`, then `noodle validate`. Inside a `fulfil`, `ctx.input` (a prompt’s arguments or a templated resource’s URI variables) and `ctx.connectors` are **symbolic**: reference them to record a flow. Recording is not execution, so never branch on their runtime values with native `if` — use `when(...)`.
+
+### Resource
+
+`resource(name, { uri, title?, description?, mimeType?, fulfil })`. `fulfil` returns `{ contents: [{ uri, mimeType, text }] }`. Use a fixed URI for a constant document, or a `{var}` template whose variable arrives on `ctx.input`.
+
+```ts
+import { resource } from '@noodleseed/one';
+
+// Fixed-URI resource: one constant document the model can read.
+resource('changelog', {
+  uri: 'docs://changelog',
+  title: 'Changelog',
+  mimeType: 'text/markdown',
+  fulfil: () => ({
+    contents: [
+      { uri: 'docs://changelog', mimeType: 'text/markdown', text: 'Changelog: 1.0.0 first release' },
+    ],
+  }),
+});
+
+// {var} URI-template resource: the URI variable arrives on ctx.input (a symbolic ref).
+resource('ticket', {
+  uri: 'tickets://{id}',
+  title: 'Support ticket',
+  mimeType: 'text/markdown',
+  fulfil: (ctx) => ({
+    contents: [
+      { uri: `tickets://${ctx.input.id}`, mimeType: 'text/markdown', text: `Ticket ${ctx.input.id}` },
+    ],
+  }),
+});
+```
+
+### Prompt
+
+`prompt(name, { title?, description?, arguments?, fulfil })`. `arguments` is a Zod object (each key becomes a `prompts/list` descriptor) or an explicit `[{ name, description?, required? }]` list. `fulfil` returns `{ messages: [{ role, content: { type: 'text', text } }] }`; supplied argument values arrive on `ctx.input`.
+
+```ts
+import { prompt, z } from '@noodleseed/one';
+
+prompt('summarize_ticket', {
+  title: 'Summarize ticket',
+  description: 'Draft a short summary of a support ticket.',
+  // A Zod object: each key becomes a prompts/list descriptor (or pass [{ name, description?, required? }]).
+  arguments: z.object({
+    ticket_id: z.string().describe('Ticket to summarize'),
+    tone: z.enum(['concise', 'detailed']).default('concise'),
+  }),
+  // Argument values arrive on ctx.input; return the prompts/get messages shape.
+  fulfil: (ctx) => ({
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: `Summarize ticket ${ctx.input.ticket_id} in a ${ctx.input.tone} tone.`,
+        },
+      },
+    ],
+  }),
+});
+```
+
+### Non-trivial tool: ctx connectors, annotations, visibility, async
+
+`ctx` is `{ input, user, connectors }`. Bind connectors with `use` on the server, then call one inside `fulfil` to record a step. `annotations.readOnly()` / `annotations.action()` set the tool hints; `visibility` defaults to `['model', 'app']` — set `['app']` to hide a helper from the model. `fulfil` may be `async` (the compiler awaits it while recording).
+
+```ts
+import { annotations, connector, server, tool, z } from '@noodleseed/one';
+
+// A tool-facing HTTP connector, bound to the server via `use`, reachable as ctx.connectors.crm.
+const crm = connector('crm')
+  .version('1.0.0')
+  .http({
+    baseUrl: 'https://crm.example.com',
+    allowedOrigins: ['https://crm.example.com'],
+    operations: {
+      get_ticket: {
+        type: 'read',
+        method: 'GET',
+        path: '/tickets',
+        query: ['id'],
+        input: { id: { type: 'string', required: true } },
+        output: { subject: { type: 'string' }, status: { type: 'string' } },
+        response: { subject: '${response.subject}', status: '${response.status}' },
+      },
+    },
+  });
+
+export default server('support', { title: 'Support', version: '1.0.0', use: { crm } }, [
+  tool('get_ticket', {
+    description: 'Fetch a support ticket by id.',
+    input: z.object({ id: z.string() }),
+    output: z.object({ subject: z.string(), status: z.string() }),
+    annotations: annotations.readOnly(), // read-only hint for hosts
+    visibility: ['model', 'app'], // default; use ['app'] to hide the tool from the model
+    // ctx is { input, user, connectors }. A connector call records one flow step (a Ref) —
+    // recording is not execution, so never branch on the result with native if (use when).
+    fulfil: ({ input, connectors }) => {
+      const found = connectors.crm.get_ticket({ id: input.id });
+      return { subject: found.subject, status: found.status };
+    },
+  }),
+  tool('echo', {
+    description: 'Echo text back.',
+    input: z.object({ text: z.string() }),
+    output: z.object({ echo: z.string() }),
+    annotations: annotations.action(), // mutating / world-affecting hint
+    // fulfil may be async — the compiler awaits it while recording the flow.
+    fulfil: async ({ input }) => ({ echo: input.text }),
+  }),
+]);
+```

package/skills/codex/references/widgets-and-apps.md

@@ -3,60 +3,206 @@
 ## Contents
 
 - Tools and views
-- React authoring
 - React hook surface
-- Shaping tool output for widgets
-- Widget state and model context
-- CSP, domain, and permissions
-- Host bridge
+- Worked widget recipe
+- ChatGPT App = this widget + a domain
+- Knowledge/source apps (search + fetch)
+- Permissions and host bridge
 - Readiness and boundaries
 
 ## Tools and views
 
-Use `toolWithWidget(name, { description, input, output, fulfil, view })` for a model-visible tool that renders a widget, and `toolForWidget(name, { ... })` for a widget-only helper hidden from the model. A `view` is `{ component: "name", entry: "./views/name.tsx" }`.
-
-## React authoring
-
-Author views as React components. Get typed helpers from `@noodleseed/one/react`:
-
-```ts
-import { generateHelpers } from '@noodleseed/one/react';
-const { useToolInfo, useCallTool, useViewState, useLayout, useOpenExternal, useSendFollowUpMessage } =
-  generateHelpers<AppType>();
-```
-
-Bind interactive elements to tools (`useCallTool("place_order")`) and annotate model-facing context with `data-llm`. A raw `html` escape hatch exists for self-contained widgets (declarative `data-bind`/`data-action`; no inline `<script>`).
+Use `toolWithWidget(name, { description, input, output, fulfil, view })` for a model-visible tool that renders a widget, and `toolForWidget(name, { ... })` for a widget-only helper hidden from the model. A `view` is `{ component: "name", entry: "./views/name.tsx" }` — a React component the compiler bundles at validate/deploy time.
 
 ## React hook surface
 
+Author views as React components. `generateHelpers<ServerDefinition>()` (from `@noodleseed/one/react`) returns the typed host hooks:
+
 | Hook | Use for |
 | :-- | :-- |
 | `useToolInfo` | Read the invoking tool result; `structuredContent` is the widget’s typed data payload. |
-| `useCallTool` | Call a tool from the widget — returns `{ callTool, data, error, isPending }`; target a model-visible tool or a hidden `toolForWidget` helper. |
+| `useCallTool` | Call a tool from the widget — returns `{ status, callTool, callToolAsync, data, structuredContent, error, reset }`; target a model-visible tool or a hidden `toolForWidget` helper. |
 | `useViewState` | Persist per-widget UI state across re-renders and restores: `const [value, setValue] = useViewState("key", initial)`. |
 | `useLayout` | Read host layout: `{ theme, displayMode, locale? }` (`theme` is `"light"`/`"dark"`, `displayMode` is `"inline"`/`"fullscreen"`) — adapt styling to the host theme and mode. |
 | `useOpenExternal` | Open an external link through the host (never `window.open`); the target origin must be listed in the server-level `handoff.allowedDomains`. |
 | `useSendFollowUpMessage` | Send a follow-up prompt to the model from a user interaction: `send({ prompt })` — trigger only from an explicit user action. |
+| `useAppFlow` | Manage named widget views with persisted params and back-stack state: `const flow = useAppFlow({ initialView, views })`. |
+| `useHandoff` | Open server-created HTTP(S) handoff URLs through the host with status/error state; domain policy still comes from `handoff.allowedDomains`. |
+
+Bind interactive elements to tools (`useCallTool("place_order")`), drive named views with `useAppFlow(...)`, open server-created handoffs with `useHandoff()`, and annotate model-facing context with `data-llm`. Use `createViewStore("key", initial)` for multi-component widget state such as carts, filters, or drafts. Use the domain-neutral React components from `@noodleseed/one/react` (`AppShell`, `ShellNav`, `ViewStack`, `AsyncBoundary`, `ActionBar`, `Field`, `QuantityStepper`, `ChoiceGroup`, `HandoffButton`, and related state components) for rich apps before inventing local shell/control scaffolding. Adapt to the host with `useLayout()` — style for both `theme` values, and keep the inline `displayMode` compact (content fits the space; no internal scrolling). Trigger `useOpenExternal()`, `useHandoff()`, and `useSendFollowUpMessage()` only from explicit user actions. A raw `html` escape hatch exists for self-contained widgets (declarative `data-bind`/`data-action`; no inline `<script>`).
+
+## Worked widget recipe
+
+Minimal, complete, and compile-verified — `noodle validate` bundles the view and `noodle check --target chatgpt` audits it. Author two files: the view (`src/views/order-status.tsx`) and the tool declaration (`src/server.ts`).
+
+### 1. The view component
+
+Author React. `generateHelpers<ServerDefinition>()` (from `@noodleseed/one/react`) returns the typed host hooks: read the tool result with `useToolInfo`, call a widget-only helper with `useCallTool`, keep local UI state that survives re-render with `useViewState`, open an allowlisted link with `useOpenExternal`, and mirror model-facing context back to the model as text with `data-llm`.
 
-Adapt to the host with `useLayout()` — style for both `theme` values, and keep the inline `displayMode` compact (content fits the space; no internal scrolling). Trigger `useOpenExternal()` and `useSendFollowUpMessage()` only from explicit user actions.
+```tsx
+import type { ServerDefinition } from '@noodleseed/one';
+import { generateHelpers } from '@noodleseed/one/react';
+
+// One call wires the typed host bridge; destructure only the hooks this view uses.
+const { useToolInfo, useCallTool, useViewState, useOpenExternal } =
+  generateHelpers<ServerDefinition>();
+
+type OrderResult = {
+  readonly customer?: string;
+  readonly item?: string;
+  readonly total?: number;
+  readonly checkoutUrl?: string;
+};
+
+export default function OrderStatus() {
+  const shown = useToolInfo('show_order').structuredContent as OrderResult | undefined;
+  const placeOrder = useCallTool('place_order'); // calls the widget-only helper tool
+  const openExternal = useOpenExternal();
+  const [item, setItem] = useViewState('item', shown?.item ?? 'falafel_wrap'); // survives re-render
+  const confirmed = placeOrder.data?.structuredContent as { readonly status?: string } | undefined;
+  const total = shown?.total ?? 0;
+  const checkoutUrl = shown?.checkoutUrl ?? '';
+
+  return (
+    // data-llm mirrors the visible state back to the model as text context.
+    <main data-llm={`Pickup order for ${shown?.customer ?? 'Guest'}: ${item}, total ${total}`}>
+      <h1>Pickup order</h1>
+      <label>
+        Item
+        <select value={item} onChange={(event) => setItem(event.currentTarget.value)}>
+          <option value="falafel_wrap">Falafel Wrap</option>
+          <option value="lentil_soup">Lentil Soup</option>
+          <option value="mint_lemonade">Mint Lemonade</option>
+        </select>
+      </label>
+      <button
+        type="button"
+        disabled={placeOrder.isPending}
+        onClick={() => placeOrder.callTool({ customer: shown?.customer ?? 'Guest', item })}
+      >
+        {placeOrder.isPending ? 'Placing…' : 'Place order'}
+      </button>
+      <p>{confirmed?.status ?? `Total: $${total}`}</p>
+      <button type="button" onClick={() => openExternal(checkoutUrl)}>
+        Continue checkout
+      </button>
+    </main>
+  );
+}
+```
+
+### 2. The tool declaration
 
-## Shaping tool output for widgets
+`toolWithWidget` is the model-visible tool that renders the view; pair it with `toolForWidget` helpers the view calls (hidden from the model). Wire `view: { component, entry }`, `csp`, a widget `domain`, and a real `output` schema so non-Apps hosts still receive structured data. Inside `fulfil`, `input` is a symbolic ref recorded into a flow — reference it in output/template strings, but never use it as an object key or `if` condition.
+
+```ts
+import { annotations, server, toolForWidget, toolWithWidget, z } from '@noodleseed/one';
+
+const item = z.enum(['falafel_wrap', 'lentil_soup', 'mint_lemonade']).default('falafel_wrap');
+const checkoutUrl = (customer: string) =>
+  `https://orders.example.com/pickup?customer=${customer}`;
+
+export default server(
+  'pickup',
+  {
+    title: 'Pickup',
+    version: '1.0.0',
+    // External-link targets the widget opens; the compiler derives ChatGPT redirect_domains from this.
+    handoff: { allowedDomains: ['https://orders.example.com'] },
+  },
+  [
+    toolWithWidget('show_order', {
+      description: 'Show the pickup order and render the ordering widget.',
+      // Declare tool annotations — a ChatGPT-submission requirement. A read → `readOnly()`.
+      annotations: annotations.readOnly(),
+      input: z.object({ customer: z.string().default('Guest') }),
+      output: z.object({
+        customer: z.string(),
+        item: z.string(),
+        total: z.number(),
+        checkoutUrl: z.string(),
+      }),
+      fulfil: ({ input }) => ({
+        customer: input.customer,
+        item: 'falafel_wrap',
+        total: 12,
+        checkoutUrl: checkoutUrl(input.customer),
+      }),
+      widgetTitle: 'Pickup order',
+      widgetDescription: 'Pick an item and place a pickup order.',
+      // A ChatGPT App is this widget + a domain: one https origin per app.
+      domain: 'https://pickup.example.com',
+      view: { component: 'order-status', entry: './views/order-status.tsx' },
+      csp: {
+        connectDomains: ['https://orders.example.com'],
+        resourceDomains: ['https://example.com'],
+        // Keep CSP origins exact and minimal. Add `frameDomains` ONLY if the widget embeds an
+        // iframe — it relaxes subframe rendering and triggers stricter ChatGPT review.
+      },
+    }),
+    // Widget-only helper the view calls with useCallTool('place_order'); hidden from the model.
+    toolForWidget('place_order', {
+      description: 'Place a pickup order from the widget.',
+      // A write that reaches the outside world → `action()` (not read-only, not destructive).
+      annotations: annotations.action(),
+      input: z.object({ customer: z.string().default('Guest'), item }),
+      output: z.object({ status: z.string(), item: z.string(), checkoutUrl: z.string() }),
+      fulfil: ({ input }) => ({
+        status: `Order placed for ${input.customer}.`,
+        item: input.item,
+        checkoutUrl: checkoutUrl(input.customer),
+      }),
+    }),
+  ],
+);
+```
 
-The widget reads the tool result’s `structuredContent`, typed by the tool’s `output` schema — arrays and nested objects are fully supported, so model the data naturally (`z.array(z.object({ ... }))`) instead of flattening. Keep the result’s `content` useful on its own: hosts without MCP Apps support show only the text/structured result, so the tool must degrade gracefully.
+## ChatGPT App = this widget + a domain
 
-## Widget state and model context
+A "ChatGPT App" is not a separate authoring surface — it is exactly this MCP Apps widget rendered by the ChatGPT host. From the same declaration you author three things:
 
-Persist UI state (selections, drafts, pagination) with `useViewState("key", initial)` — it survives re-renders and conversation restores. For durable, caller-scoped state handles with optimistic revisions, follow the `stateful-draft` example. Mark the DOM the model should see with `data-llm` attributes; everything else stays widget-only.
+- `domain` on the widget — one https origin per app (required for app-store submission, optional for dev-mode testing).
+- `csp: { connectDomains, resourceDomains }` — the exact network/resource origins the widget may reach; keep them minimal. Add `frameDomains` only if the widget embeds an iframe (it relaxes subframe rendering and draws stricter review).
+- server `handoff.allowedDomains` — the external-link targets `useOpenExternal()` opens.
 
-## CSP, domain, and permissions
+The compiler emits the rest automatically: the `openai/*` metadata (`openai/outputTemplate`, `openai/widgetCSP`, `openai/widgetDescription`) and ChatGPT’s `redirect_domains` (derived from `handoff.allowedDomains`). `window.openai` and Claude’s ext-apps bridge are auto-detected at startup, so the same widget renders in both Claude and ChatGPT with no host-specific code.
 
-Declare network/host needs explicitly: `csp: { connectDomains, resourceDomains, frameDomains }` and `permissions` (e.g. `clipboardWrite`). Secrets are never injected into widgets; tool output is redacted before widget delivery.
+Verify it in the loop: `noodle check --target chatgpt --json` returning `ok:true` means the widget is **metadata-ready** for ChatGPT’s checks (`domain`, `openai/outputTemplate`, CSP present) — it does NOT prove host rendering, conversation UX, or submission acceptance. Fix any `severity:"error"` finding by its `fix`, then re-check. Validate real rendering in ChatGPT Developer Mode / MCP Inspector as a higher level before submitting.
+
+**Every tool needs annotations** (`annotations.readOnly()` / `.action()` / `.openAction()`) — missing or wrong `readOnlyHint`/`openWorldHint`/`destructiveHint` is a common submission rejection. **App-store submission is more than building**: a public https endpoint, exact CSP, org verification, app info, screenshots, and test prompts are required — follow OpenAI’s Apps submission guidelines; `noodle check --target chatgpt` covers only the metadata prerequisites.
+
+## Knowledge/source apps (ChatGPT): search + fetch
+
+If the app is a read-only knowledge/source connector (docs, wiki, CRM lookups) meant for ChatGPT company-knowledge, implement exactly two tools — `search` and `fetch`, both read-only. ChatGPT only surfaces knowledge apps that match these signatures:
+
+```ts
+import { annotations, server, tool, z } from '@noodleseed/one';
+
+export default server('kb', { title: 'Knowledge base', version: '1.0.0' }, [
+  tool('search', {
+    description: 'Search the knowledge base; return citable results.',
+    annotations: annotations.readOnly(),
+    input: z.object({ query: z.string() }),
+    output: z.object({
+      results: z.array(z.object({ id: z.string(), title: z.string(), url: z.string() })),
+    }),
+    fulfil: ({ input }) => ({ results: [{ id: 'doc-1', title: `Match: ${input.query}`, url: 'https://example.com/doc-1' }] }),
+  }),
+  tool('fetch', {
+    description: 'Fetch one document by id for citation.',
+    annotations: annotations.readOnly(),
+    input: z.object({ id: z.string() }),
+    output: z.object({ id: z.string(), title: z.string(), text: z.string(), url: z.string() }),
+    fulfil: ({ input }) => ({ id: input.id, title: 'Doc', text: 'Full document text…', url: 'https://example.com/doc-1' }),
+  }),
+]);
+```
 
-For ChatGPT: set `domain` on each widget (one https origin per app; required for app-store submission, optional for dev-mode testing), and declare external-link targets in the server-level `handoff.allowedDomains` — the compiler derives ChatGPT’s `redirect_domains` from it so `useOpenExternal()` links open without the safe-link warning. `noodle check --target chatgpt` verifies all of this.
+`search` → `{ results: [{ id, title, url }] }`; `fetch` → `{ id, title, text, url, metadata? }`. `url` must be an absolute, user-openable https link for citation.
 
-## Host bridge
+## Permissions and host bridge
 
-One runtime targets both Claude’s ext-apps bridge and ChatGPT’s `window.openai`, detected at startup. Tool results still carry useful `content`/`structuredContent` so non-Apps hosts degrade gracefully.
+Declare extra host capabilities with `permissions` (e.g. `permissions: { clipboardWrite: {} }`). Secrets are never injected into widgets and tool output is redacted before widget delivery. Tool results still carry useful `content`/`structuredContent`, so non-Apps hosts degrade gracefully.
 
 ## Readiness and boundaries