@noodleseed/agent-kit 0.8.1 → 0.10.0

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

@@ -3,35 +3,206 @@
 ## Contents
 
 - Tools and views
-- React authoring
-- CSP and permissions
-- Host bridge
+- React hook surface
+- 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" }`.
+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 authoring
+## React hook surface
 
-Author views as React components. Get typed helpers from `@noodleseed/one/react`:
+Author views as React components. `generateHelpers<ServerDefinition>()` (from `@noodleseed/one/react`) returns the typed host hooks:
 
-```ts
+| 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 `{ 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`.
+
+```tsx
+import type { ServerDefinition } from '@noodleseed/one';
 import { generateHelpers } from '@noodleseed/one/react';
-const { useCallTool, useLayout, useToolInfo, useViewState } = generateHelpers<AppType>();
+
+// 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>
+  );
+}
 ```
 
-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>`).
+### 2. The tool declaration
+
+`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';
 
-## CSP, domain, and permissions
+const item = z.enum(['falafel_wrap', 'lentil_soup', 'mint_lemonade']).default('falafel_wrap');
+const checkoutUrl = (customer: string) =>
+  `https://orders.example.com/pickup?customer=${customer}`;
 
-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.
+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),
+      }),
+    }),
+  ],
+);
+```
+
+## ChatGPT App = this widget + a domain
+
+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:
+
+- `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.
+
+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.
+
+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