@noodleseed/agent-kit 0.17.0 → 0.19.0

package/skills/claude-code/examples/acme-tasks/design/wireframe.html

@@ -217,7 +217,7 @@
     <div class="rationale">
       <h4>How to read these wireframes</h4>
       <p>Solid-border phones are the <strong>in-ChatGPT app</strong>. Acme Tasks is a <strong>two-way (read + write) app</strong>, not a discovery funnel: every widget reflects the user's real list, and each action — capture, re-prioritize, complete — is <strong>recorded through a tool call</strong> and confirmed in-chat. The single dashed phone is the <strong>one-time account link</strong> (<span class="mono">customerAuth</span>); there is no transactional off-app step.</p>
-      <p>Widgets are built with the Noodle Seed authoring SDK — <span class="mono">toolWithWidget</span> renders <span class="mono">TaskList</span>; <span class="mono">toolForWidget</span> powers the in-widget re-prioritize. Styling uses host/Noodle Seed semantic tokens via CSS cascade layers; the brand accent (<span class="mono">#7C3AED</span>) is reserved for the logo, checks, primary CTA and <em>high</em> emphasis. Priority uses fixed semantic colors: high red · medium amber · low slate.</p>
+      <p>Widgets are built with the Noodle Seed authoring SDK — <span class="mono">tool + view</span> renders <span class="mono">TaskList</span>; <span class="mono">tool + app visibility</span> powers the in-widget re-prioritize. Styling uses host/Noodle Seed semantic tokens via CSS cascade layers; the brand accent (<span class="mono">#7C3AED</span>) is reserved for the logo, checks, primary CTA and <em>high</em> emphasis. Priority uses fixed semantic colors: high red · medium amber · low slate.</p>
       <p><span class="r-tag ux">UX</span> flow rationale &nbsp; <span class="r-tag ui">UI</span> interface rationale &nbsp; <span class="r-tag acme">ACME</span> product-model fit &nbsp; <span class="r-tag trust">TRUST</span> write-safety / grounding guardrail</p>
     </div>
   </div>
@@ -401,11 +401,11 @@
   <div class="section" id="prioritize">
     <span class="section-label">Flow 2 · the hub</span>
     <h2 class="section-title">Prioritize — read the day, then re-order it in place</h2>
-    <p class="section-subtitle"><span class="mono">list_today</span> renders the grounded list, highest priority first; the per-row priority control (a <span class="mono">toolForWidget</span> helper hidden from the model) lets the user re-rank without describing the task twice. This is the widget the other two flows write into.</p>
+    <p class="section-subtitle"><span class="mono">list_today</span> renders the grounded list, highest priority first; the per-row priority control (a <span class="mono">tool + app visibility</span> helper hidden from the model) lets the user re-rank without describing the task twice. This is the widget the other two flows write into.</p>
     <div class="rationale">
       <h4>Why it's built this way</h4>
       <p><span class="r-tag ux">UX</span> "What's on my plate?" wants an answer <em>and</em> a next move. The list is grouped high → low so the triager sees the real order at a glance and adjusts with one tap.</p>
-      <p><span class="r-tag acme">ACME</span> Re-prioritize is <span class="mono">set_priority</span> as <span class="mono">toolForWidget</span> — <strong>widget-only</strong>, hidden from the model's tool surface. The model reasons about three tools (list, add, complete); the fourth is pure UI plumbing, keeping the model's choices clean.</p>
+      <p><span class="r-tag acme">ACME</span> Re-prioritize is <span class="mono">set_priority</span> as <span class="mono">tool + app visibility</span> — <strong>widget-only</strong>, hidden from the model's tool surface. The model reasons about three tools (list, add, complete); the fourth is pure UI plumbing, keeping the model's choices clean.</p>
       <p><span class="r-tag trust">TRUST</span> The list only ever shows tasks that exist — the app never invents a task or a priority. Every re-rank echoes a confirmation ("Set review_pr to high priority").</p>
     </div>
     <div class="phones-row">
@@ -543,7 +543,7 @@
   <div class="section" id="api">
     <span class="section-label">Technical appendix</span>
     <h2 class="section-title">MCP tools &amp; call sequence</h2>
-    <p class="section-subtitle">The four tools behind the flows. <span class="mono">list_today</span> is the only widget-opening tool (<span class="mono">toolWithWidget</span>); <span class="mono">set_priority</span> is widget-only (<span class="mono">toolForWidget</span>, hidden from the model); <span class="mono">add_task</span> and <span class="mono">complete_task</span> are model-visible.</p>
+    <p class="section-subtitle">The four tools behind the flows. <span class="mono">list_today</span> is the only widget-opening tool (<span class="mono">tool + view</span>); <span class="mono">set_priority</span> is widget-only (<span class="mono">tool + app visibility</span>, hidden from the model); <span class="mono">add_task</span> and <span class="mono">complete_task</span> are model-visible.</p>
 
     <div class="api-panel">
       <h4>Read &amp; render (Flow 2 · the hub)</h4>
@@ -559,7 +559,7 @@
 
     <div class="api-panel">
       <h4>Prioritize (Flow 2 helper) &amp; Complete (Flow 3)</h4>
-      <div class="api-step"><span class="verb">WRITE</span><span><span class="tname">set_priority</span> — returns { status, task, priority } · toolForWidget, hidden from the model</span></div>
+      <div class="api-step"><span class="verb">WRITE</span><span><span class="tname">set_priority</span> — returns { status, task, priority } · tool + app visibility, hidden from the model</span></div>
       <div class="api-note">Input <span class="mono">{ task:id, priority }</span>. Called only by the priority ▾ in TaskList — keeps the model's tool surface to the three it should reason about.</div>
       <div class="api-step"><span class="verb">WRITE</span><span><span class="tname">complete_task</span> — returns { status, task } · model-visible</span></div>
       <div class="api-note">Input <span class="mono">{ task:id, title:"" }</span>. Model-visible so "I finished X" completes directly; local non-destructive write, confirmed with the remaining count.</div>
@@ -596,7 +596,7 @@
 
 <div class="footer">
   Acme Tasks × ChatGPT — Two-Way App Wireframes · Noodle Seed · v1 · July 2026<br>
-  Illustrative wireframes for a fictional app. Built with the Noodle Seed authoring SDK (toolWithWidget / toolForWidget · customerAuth). This flagship seeds the task list; a production deployment connects the user's account. Task data shown is sample content.
+  Illustrative wireframes for a fictional app. Built with the Noodle Seed authoring SDK (tool + view / tool + app visibility · customerAuth). This flagship seeds the task list; a production deployment connects the user's account. Task data shown is sample content.
 </div>
 
 </body>

package/skills/claude-code/examples/acme-tasks/src/server.ts

@@ -1,4 +1,4 @@
-import { annotations, server, tool, toolForWidget, toolWithWidget, z } from '@noodleseed/one';
+import { annotations, server, tool, 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,
@@ -52,7 +52,7 @@ export default server(
   },
   [
     // Flow 2 — Prioritize / Today: render the list so the human triages and the model can speak to it.
-    toolWithWidget('list_today', {
+    tool('list_today', {
       description: 'Show today’s Acme Tasks and render the task-list widget.',
       annotations: readOnly,
       input: z.object({ focus: z.string().default('today') }),
@@ -66,8 +66,8 @@ export default server(
         focus: input.focus,
         tasks: today,
       }),
-      widgetTitle: 'Today’s tasks',
-      widgetDescription: 'A prioritized task list: capture, re-prioritize, and complete in place.',
+      viewTitle: 'Today’s tasks',
+      viewDescription: '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',
@@ -119,7 +119,8 @@ export default server(
       }),
     }),
     // Flow 2 helper (widget-only): re-prioritize a task from the list widget.
-    toolForWidget('set_priority', {
+    tool('set_priority', {
+      visibility: ['app'],
       description: 'Re-prioritize a task from the list widget.',
       annotations: localWrite,
       input: z.object({

package/skills/claude-code/examples/food-ordering/src/server.ts

@@ -1,15 +1,4 @@
-import {
-  annotations,
-  asset,
-  connector,
-  resource,
-  server,
-  tool,
-  toolForWidget,
-  toolWithWidget,
-  widget,
-  z,
-} from '@noodleseed/one';
+import { annotations, asset, connector, resource, server, tool, z } from '@noodleseed/one';
 
 const heroImage = asset('assets/noodle-bowl.jpg');
 
@@ -235,7 +224,7 @@ export default server(
     },
   },
   [
-    toolWithWidget('open_ordering', {
+    tool('open_ordering', {
       description:
         'Open a complete food-ordering widget with store discovery, menu browsing, cart review, and checkout handoff.',
       annotations: readOnly,
@@ -257,13 +246,13 @@ export default server(
         featuredItems: menu,
         fallback: 'Open stores: Harbor Noodles (Noodles), Garden Wraps (Vegetarian).',
       }),
-      widgetTitle: 'Food ordering',
+      viewTitle: 'Food ordering',
       domain: 'https://orders.example.com',
       view: {
         component: 'ordering-flow',
         entry: './views/ordering-flow.tsx',
       },
-      widgetDescription:
+      viewDescription:
         'A complete consumer ordering surface with app-only helper tools, cart state, and checkout handoff.',
       csp: {
         connectDomains: ['https://orders.example.com'],
@@ -272,7 +261,8 @@ export default server(
       },
       permissions: { clipboardWrite: {} },
     }),
-    toolForWidget('search_stores', {
+    tool('search_stores', {
+      visibility: ['app'],
       description: 'Filter synthetic restaurants for the ordering widget.',
       annotations: readOnly,
       input: z.object({
@@ -282,7 +272,8 @@ export default server(
       output: z.object({ stores: z.array(storeShape) }),
       fulfil: () => ({ stores }),
     }),
-    toolForWidget('load_menu', {
+    tool('load_menu', {
+      visibility: ['app'],
       description: 'Load synthetic menu categories and items for one store.',
       annotations: readOnly,
       input: z.object({ storeId: z.string() }),
@@ -293,14 +284,16 @@ export default server(
       }),
       fulfil: ({ input }) => ({ storeId: input.storeId, stores, items: menu }),
     }),
-    toolForWidget('load_item', {
+    tool('load_item', {
+      visibility: ['app'],
       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', {
+    tool('read_cart', {
+      visibility: ['app'],
       description: 'Read the caller-scoped ordering cart state.',
       annotations: readOnly,
       input: z.object({}),
@@ -314,7 +307,8 @@ export default server(
         return { value: state.value, revision: state.revision, status: state.status };
       },
     }),
-    toolForWidget('sync_cart', {
+    tool('sync_cart', {
+      visibility: ['app'],
       description: 'Patch the caller-scoped ordering cart with the widget cart mirror.',
       annotations: action,
       input: cartInput,
@@ -333,7 +327,8 @@ export default server(
         return { cart, revision: state.revision, status: state.status };
       },
     }),
-    toolForWidget('prepare_checkout', {
+    tool('prepare_checkout', {
+      visibility: ['app'],
       description: 'Prepare the caller-scoped cart for checkout handoff.',
       annotations: action,
       input: cartInput,
@@ -375,6 +370,17 @@ export default server(
         status: 'Food Ordering widget capabilities are ready.',
         note: 'Standalone preview covers React views, helper tools, cart state, handoff, CSP, and permissions.',
       }),
+      viewName: 'capabilities_card',
+      viewTitle: 'Food Ordering capabilities',
+      viewDescription: 'Standalone widget resource for previewing the ordering capability surface.',
+      domain: 'https://orders.example.com',
+      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: {} },
     }),
     resource('food_ordering_guide', {
       uri: 'docs://food-ordering',
@@ -392,21 +398,5 @@ export default server(
           '- 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/claude-code/references/authoring-workflow.md

@@ -11,6 +11,7 @@
 - Compute connector example
 - Tests
 - Secrets and variables
+- Embedded assistant
 - Boundaries
 
 ## Input paths
@@ -197,6 +198,10 @@ After focused tests pass, run `noodle validate --json`, `noodle test --json`, an
 
 Author managed config as `secret("NAME")` / `variable("NAME")` and operate it with `noodle secrets set` / `noodle variables set` (scoped org/app/env). Never inline secret values in `server.ts`, tests, or generated files.
 
+## Embedded assistant
+
+To place the same server tools inside the SaaS web app, declare the shared identity once with `branding: { name: "Acme", accent: "#3157D5", surface: "#FFFFFF", surfaceDark: "#161B26", theme: { dark: { accent: "#9FB4FF" } } }`, then add `assistant: embeddedAssistant({ model: openAICompatible({ baseUrl: variable("ASSISTANT_MODEL_BASE_URL"), model: variable("ASSISTANT_MODEL"), apiKey: secret("ASSISTANT_MODEL_API_KEY") }), allowedOrigins: ["https://app.example.com"], layout: { mode: "floating", position: "bottom-right" } })`. Widgets and the embed inherit the same brand kit. Keep origins exact. The customer backend uses `@noodleseed/assistant/server` to exchange its already-authenticated user for a short-lived browser session; client and model secrets never enter the browser. Run `noodle check --target embedded-assistant` before deploy, then manage backend credentials with `noodle assistant clients create|list|rotate|revoke`.
+
 ## Boundaries
 
 Do not hand-author manifest JSON/YAML, runtime artifacts, connector IR, or hosted asset metadata. Do not read or copy secrets, bearer tokens, refresh tokens, static access keys, `.env.noodle`, or `~/.noodle/config.json`. Hosted access is identity-based — do not add static data-plane credential paths.

package/skills/claude-code/references/cli-commands.md

@@ -46,6 +46,7 @@ Every `noodle` command, grouped by area. Local authoring commands (`validate`, `
 | Command | What it does |
 | :-- | :-- |
 | `noodle link` | Bind this directory to a Noodle Seed Cloud target (org/app/env). |
+| `noodle assistant` | Manage backend credentials for customer-branded embedded assistant clients. |
 | `noodle deploy` | Deploy the server to Noodle Seed Cloud. |
 | `noodle open` | Open or print the latest deployment URL. |
 | `noodle status` | Show hosted deployment status. |

package/skills/claude-code/references/compile-errors.md

@@ -38,8 +38,8 @@ Run `noodle validate` (add `--json` for the machine-readable envelope, `--fix-pr
 | `duplicate_prompt` | Two prompts share a name; rename one `prompt(...)`. |
 | `duplicate_resource_uri` | Two resources resolve to the same URI; make each resource URI unique. |
 | `unsupported_uri_template` | Fix the resource URI template to a supported form at the cited `path`. |
-| `duplicate_widget` | Two widgets share an identity; give each `widget(...)`/`view` a unique component name. |
-| `unknown_widget_tool` | The widget references a tool that does not exist; point `toolWithWidget`/`view` at a declared tool (see `didYouMean`). |
+| `duplicate_widget` | Two tool views share an identity; give each `viewName` or `view.component` a unique name. |
+| `unknown_widget_tool` | The widget references a tool that does not exist; point `tool`/`view` at a declared tool (see `didYouMean`). |
 | `unknown_widget_action_tool` | A widget action calls a tool that is not declared; declare it or fix the action target name. |
 | `duplicate_widget_tool` | A tool is bound to more than one widget; bind each tool to a single widget. |
 | `invalid_widget_binding` | Fix the `data-bind`/binding expression in the widget; it does not resolve against the tool output. |

package/skills/claude-code/references/experience-design.md

@@ -87,7 +87,7 @@ the widget**, and the widget filled with plausible, internally consistent data (
 Label each widget with its component name so the wireframe, the spec, and the code share one
 vocabulary; put the funnel boundary at the top; and render off-app destinations distinctly (they are
 reached only after the handoff). Each wireframe screen maps directly to noodle: a screen with a widget
-is a `toolWithWidget` + a React `view`; a plain answer is a `tool`; an off-app destination is a
+is a `tool` + a React `view`; a plain answer is a `tool`; an off-app destination is a
 `handoff.allowedDomains` entry. A compact single screen, anonymized to a fictional "Acme" business:
 
 ```html

package/skills/claude-code/references/sdk-surface.md

@@ -14,13 +14,10 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
 ### 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.
+- `tool(name, options)` — declare every tool; add `view` to render an MCP App or `visibility: ["app"]` for an app-only helper.
 
-### Widgets & assets
+### Views & assets
 
-- `widget(...)` — declare a widget/view component.
 - `asset("./path")` — reference a packaged asset (e.g. an image).
 - `annotations(...)` — tool/Apps annotation metadata.
 
@@ -51,14 +48,17 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
 
 - `z` — Zod, for input/output schemas (compiles to JSON Schema 2020-12).
 
+### Other
+
+- `embeddedAssistant`
+- `openAICompatible`
+
 ## Authoring signatures
 
-- `server(name, options, definitions)` — `options` commonly includes `title`, `version`, `instructions`, `branding`, `auth`, `use`, `provides`, `state`, and `handoff`; `definitions` is the array of tools/resources/prompts/widgets.
-- `tool(name, { description, input, output, annotations?, fulfil })` — `input`/`output` are Zod schemas; `fulfil({ input, connectors, user })` returns data matching `output`.
-- `toolWithWidget(name, { description, input, output, fulfil, view })` — same as `tool`, plus `view: { component, entry }` for a React widget.
-- `toolForWidget(name, { input, output, fulfil })` — helper tool for widget actions; hidden from the model.
+- `server(name, options, definitions)` — `options` commonly includes `title`, `version`, `instructions`, `branding`, `auth`, `use`, `provides`, `state`, and `handoff`; `definitions` is the array of tools/resources/prompts.
+- `tool(name, { description, input, output, annotations?, visibility?, view?, fulfil })` — `input`/`output` are Zod schemas; `fulfil({ input, connectors, user })` returns data matching `output`. Add `view: { component, entry }` for a React widget; use `visibility: ["app"]` for an app-only helper.
 - `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.
+- View metadata (`viewTitle`, `viewDescription`, `csp`, `domain`, `permissions`) belongs on the tool that renders it; `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.
 

package/skills/claude-code/references/troubleshooting.md

@@ -19,9 +19,9 @@ For protocol/conformance checks, the headless harness is `@mcpjam/cli`, not a `n
 | ChatGPT warns “Widget CSP is not set” | The widget declares no `csp` | Declare `csp` on the widget with the exact origins it uses |
 | ChatGPT warns “Widget domain is not set” | No `domain` on the widget (required for app-store submission) | Set `domain: "https://…"` (one https origin per app) on each widget |
 | External links do nothing, or show a safe-link warning | Link opened outside the host bridge, or the target origin is not allowlisted | Use `useOpenExternal()` (never `window.open`) and add the target origins to the server-level `handoff.allowedDomains` |
-| Tool succeeds but no widget appears | The tool has no view, or the host surface doesn’t support MCP Apps | Use `toolWithWidget`, run `noodle check`, preview with `noodle devtools`; on non-Apps surfaces only the text/structured result renders |
+| Tool succeeds but no widget appears | The tool has no view, or the host surface doesn’t support MCP Apps | Use `tool`, run `noodle check`, preview with `noodle devtools`; on non-Apps surfaces only the text/structured result renders |
 | Widget shows stale or missing data | The widget reads `structuredContent`, which must match the `output` schema | Make `fulfil` return exactly the `output` shape (arrays and nested objects are supported); inspect the live result with `noodle devtools` |
-| `useCallTool` fails from the widget | Tool name mismatch, or the helper tool is model-visible | List names with `noodle tools`; widget-only helpers must be declared with `toolForWidget` |
+| `useCallTool` fails from the widget | Tool name mismatch, or the helper tool is model-visible | List names with `noodle tools`; widget-only helpers must be declared with `tool` |
 | `noodle validate` passes but React views fail to bundle (“requires Vite”) | Project dependencies are not installed — widget bundling uses the app-local Vite | Run the project’s package install, then retry `noodle dev` / `noodle deploy` |
 | Hosted endpoint returns 401 to probes | Expected: hosted servers challenge unauthenticated calls with OAuth metadata | Sign in from the host when prompted; widen who may call with `noodle access set` if testers are outside the org |
 | Tools error only after deploy | Runtime/config differences surface hosted (secrets, connector reachability) | Run `noodle smoke`, then `noodle metrics --agent-output` and `noodle events --tool <name> --status tool_error --json`; check `noodle secrets list` scope |

package/skills/claude-code/references/widgets-and-apps.md

@@ -12,7 +12,7 @@
 
 ## 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" }` — a React component the compiler bundles at validate/deploy time.
+Use `tool(name, { description, input, output, fulfil, view })` for a model-visible tool that renders a widget, and the same `tool(name, { ..., visibility: ["app"] })` for an app-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
 
@@ -21,9 +21,10 @@ Author views as React components. `generateHelpers<ServerDefinition>()` (from `@
 | 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. |
+| `useCallTool` | Call a tool from the widget — returns `{ status, callTool, callToolAsync, data, structuredContent, error, reset }`; target a model-visible tool or a hidden `tool` 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?, host?, supports? }` (`displayMode` is `"inline"`/`"pip"`/`"fullscreen"`) — adapt styling to the host theme and mode. |
+| `useBranding` | Read the server-level brand name and themed logo/mark/avatar URLs when widget content needs identity assets; CSS tokens are applied automatically. |
 | `useRequestDisplayMode` | Request a host-mediated layout change such as fullscreen; treat it as best-effort and keep inline rendering useful. |
 | `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. |
@@ -94,10 +95,10 @@ export default function OrderStatus() {
 
 ### 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.
+`tool` declares both the model-visible tool that renders the view and app-only helpers the view calls. Put `visibility: ["app"]` on each helper. 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';
+import { annotations, server, tool, z } from '@noodleseed/one';
 
 const item = z.enum(['falafel_wrap', 'lentil_soup', 'mint_lemonade']).default('falafel_wrap');
 const checkoutUrl = (customer: string) =>
@@ -112,7 +113,7 @@ export default server(
     handoff: { allowedDomains: ['https://orders.example.com'] },
   },
   [
-    toolWithWidget('show_order', {
+    tool('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(),
@@ -129,8 +130,8 @@ export default server(
         total: 12,
         checkoutUrl: checkoutUrl(input.customer),
       }),
-      widgetTitle: 'Pickup order',
-      widgetDescription: 'Pick an item and place a pickup order.',
+      viewTitle: 'Pickup order',
+      viewDescription: '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' },
@@ -142,7 +143,8 @@ export default server(
       },
     }),
     // Widget-only helper the view calls with useCallTool('place_order'); hidden from the model.
-    toolForWidget('place_order', {
+    tool('place_order', {
+      visibility: ['app'],
       description: 'Place a pickup order from the widget.',
       // A write that reaches the outside world → `action()` (not read-only, not destructive).
       annotations: annotations.action(),

package/skills/codex/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: noodle-seed
 description: Use when building, validating, testing, deploying, or operating a local or hosted Noodle Seed MCP server or app authored in TypeScript with the noodle CLI.
-version: 0.17.0
+version: 0.19.0
 hash: 39c6a606c728d164
 ---
 

package/skills/codex/examples/acme-bistro/README.md

@@ -3,7 +3,7 @@
 A Noodle MCP App for **Acme Bistro**, a fictional restaurant. It is the flagship for the **end-to-end
 transaction** pattern: the customer browses the menu and builds the order *in chat*, and the order
 completes in chat — only **payment** hands off, via a signed checkout deep link (the card never touches
-the app). It pairs a `toolWithWidget` menu/cart with `toolForWidget` cart helpers and a model-visible
+the app). It pairs a view-backed `tool` menu/cart with app-only `tool` cart helpers and a model-visible
 `create_checkout` tool backed by `handoff.allowedDomains`.
 
 Capability slot: **end-to-end in-chat transaction + payment-only handoff**, plus a worked **design-first**

package/skills/codex/examples/acme-bistro/design/UX-Document.md

@@ -204,7 +204,7 @@ APP:  [tool: create_checkout {customer:"Guest",
 
 ## 5. UI Widget Specifications
 
-> The widget is authored as a Noodle Seed React `view` (`toolWithWidget` → `MenuCart`), styled with **vanilla CSS cascade layers** so it inherits the host's light/dark theme and adapts to ChatGPT's surface. Compliance is verified with `noodle check --target chatgpt`.
+> The widget is authored as a Noodle Seed React `view` (`tool` → `MenuCart`), styled with **vanilla CSS cascade layers** so it inherits the host's light/dark theme and adapts to ChatGPT's surface. Compliance is verified with `noodle check --target chatgpt`.
 
 ### 5.1 Design System Compliance
 
@@ -250,20 +250,20 @@ Modes deliberately **not** used: no Carousel (a single flat menu doesn't need on
 
 ## 6. Tool Definitions (App Backend)
 
-### ★ Tool 1: `show_menu` — `toolWithWidget`
+### ★ Tool 1: `show_menu` — `tool`
 **Input:** `{ customer?: string = "Guest" }`
 **Output:** `{ status, customer, items[] }` where each item is `{ id, name, price, kind }`.
 **Renders:** the `MenuCart` widget.
 **Annotations:** read-only.
 **Triggers:** any menu / ordering intent ("show me Acme's menu", "order from Acme").
 
-### Tool 2: `add_to_cart` — `toolForWidget`
+### Tool 2: `add_to_cart` — `tool`
 **Input:** `{ customer?, item: <menu id> = "stone_pizza", quantity?: int ≥1 = 1, notes?: string }`
 **Output:** `{ status, item, quantity, notes }`.
 **Annotations:** local write (non-destructive).
 **Triggers:** natural-language additions ("add two margheritas", "and a lemon tart"). Widget-facing helper — reflects NL selections into the visible cart.
 
-### Tool 3: `remove_from_cart` — `toolForWidget`
+### Tool 3: `remove_from_cart` — `tool`
 **Input:** `{ customer?, item: <menu id> = "stone_pizza" }`
 **Output:** `{ status, item }`.
 **Annotations:** local write (non-destructive).

package/skills/codex/examples/acme-bistro/design/api-contract.md

@@ -8,9 +8,9 @@ The app maps to four tools:
 
 | Tool | Kind | Job |
 |------|------|-----|
-| `show_menu` | `toolWithWidget` (read-only) | Return the menu + render the `MenuCart` widget |
-| `add_to_cart` | `toolForWidget` (local write) | Reflect a natural-language addition into the visible cart |
-| `remove_from_cart` | `toolForWidget` (local write) | Remove one unit of an item |
+| `show_menu` | `tool` (read-only) | Return the menu + render the `MenuCart` widget |
+| `add_to_cart` | `tool` (local write) | Reflect a natural-language addition into the visible cart |
+| `remove_from_cart` | `tool` (local write) | Remove one unit of an item |
 | `create_checkout` | model-visible `tool` (open-link) | Mint the signed, expiring payment link |
 
 Menu item IDs are the stable enum: `stone_pizza`, `roast_bowl`, `house_salad`, `lemon_tart`, `sparkling`.

package/skills/codex/examples/acme-bistro/design/wireframe.html

@@ -496,13 +496,13 @@
       <div class="api-panel-header">Browse &amp; Build (Steps 1–3)</div>
       <div class="api-step">
         <div class="api-step-label">Step 1 — Show the menu</div>
-        <div class="api-endpoint"><span class="kind read">READ</span><span class="path">show_menu</span><span class="desc">— toolWithWidget. Returns the 5-item menu and renders MenuCart.</span></div>
+        <div class="api-endpoint"><span class="kind read">READ</span><span class="path">show_menu</span><span class="desc">— tool + view. Returns the 5-item menu and renders MenuCart.</span></div>
         <div class="api-note"><strong>Design intent:</strong> the menu is small and static, so it ships in one read — no pagination, no follow-up call. The <code>items[]</code> array is the model's only source of dish names and prices.</div>
       </div>
       <div class="api-step">
         <div class="api-step-label">Steps 2–3 — Build &amp; edit the cart</div>
-        <div class="api-endpoint"><span class="kind write">WRITE</span><span class="path">add_to_cart</span><span class="desc">— toolForWidget. Reflects a natural-language addition (item + quantity) into the visible cart.</span></div>
-        <div class="api-endpoint"><span class="kind write">WRITE</span><span class="path">remove_from_cart</span><span class="desc">— toolForWidget. Removes one unit; the widget's − button calls the same tool.</span></div>
+        <div class="api-endpoint"><span class="kind write">WRITE</span><span class="path">add_to_cart</span><span class="desc">— tool + app visibility. Reflects a natural-language addition (item + quantity) into the visible cart.</span></div>
+        <div class="api-endpoint"><span class="kind write">WRITE</span><span class="path">remove_from_cart</span><span class="desc">— tool + app visibility. Removes one unit; the widget's − button calls the same tool.</span></div>
         <div class="api-note"><strong>Natural-language parsing:</strong> "two margheritas and a lemon tart" becomes <code>add_to_cart{item:"stone_pizza",quantity:2}</code> + <code>add_to_cart{item:"lemon_tart",quantity:1}</code> — the model fills the fields; no UI round-trip. The running total is summed live in the widget (React), not in a tool.</div>
       </div>
     </div>

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

@@ -1,4 +1,4 @@
-import { annotations, server, tool, toolForWidget, toolWithWidget, z } from '@noodleseed/one';
+import { annotations, server, tool, z } from '@noodleseed/one';
 
 // Acme Bistro is a fictional restaurant. This app is deliberately END-TO-END: the customer browses the
 // menu and builds the order in chat, and the order completes in chat — only *payment* hands off, via a
@@ -52,7 +52,7 @@ export default server(
     },
   },
   [
-    toolWithWidget('show_menu', {
+    tool('show_menu', {
       description: 'Show the Acme Bistro menu and render the ordering widget.',
       annotations: readOnly,
       input: z.object({ customer: z.string().default('Guest') }),
@@ -66,8 +66,8 @@ export default server(
         customer: input.customer,
         items: menu,
       }),
-      widgetTitle: 'Order at Acme Bistro',
-      widgetDescription: 'Browse the menu, build an order in chat, and hand off to pay.',
+      viewTitle: 'Order at Acme Bistro',
+      viewDescription: 'Browse the menu, build an order in chat, and hand off to pay.',
       invoking: 'Loading the menu…',
       invoked: 'Menu ready',
       domain: 'https://order.acme.example',
@@ -82,7 +82,8 @@ export default server(
       },
     }),
     // Widget-only cart edits — the model fills the item from natural language ("add two margheritas").
-    toolForWidget('add_to_cart', {
+    tool('add_to_cart', {
+      visibility: ['app'],
       description: 'Add a menu item to the Acme Bistro order from the widget.',
       annotations: localWrite,
       input: z.object({
@@ -104,7 +105,8 @@ export default server(
         notes: input.notes,
       }),
     }),
-    toolForWidget('remove_from_cart', {
+    tool('remove_from_cart', {
+      visibility: ['app'],
       description: 'Remove a menu item from the Acme Bistro order.',
       annotations: localWrite,
       input: z.object({

package/skills/codex/examples/acme-discovery/README.md

@@ -3,7 +3,7 @@
 A Noodle MCP App for **Acme Getaways**, a fictional travel brand. It is the flagship for the
 **top-of-funnel discovery → handoff** pattern: discovery and configuration happen inside ChatGPT; the
 booking/transaction happens off-app on Acme's own site, reached through a signed, attributable handoff
-deep link. It pairs a `toolWithWidget` discovery carousel with a model-visible `create_handoff` tool and
+deep link. It pairs a `tool` discovery carousel with a model-visible `create_handoff` tool and
 server-level `handoff.allowedDomains`.
 
 Capability slots: top-of-funnel funnel discipline, discovery carousel widget, `create_handoff` deep-link

package/skills/codex/examples/acme-discovery/design/UX-Document.md

@@ -202,7 +202,7 @@ Inside the widget, **Continue on Acme** calls `create_handoff(destination="coral
 
 ## 5. UI Widget Specifications (OpenAI Apps SDK Compliant)
 
-> The app has **one** widget, `DiscoveryCarousel`, authored as a React `view` on the `discover_getaways` `toolWithWidget`. It follows the OpenAI Apps SDK UI Guidelines (system fonts, monochrome outlined icons, WCAG AA, ≤2 actions per card, no nested scroll). Styling uses Noodle Seed's server-level `branding` tokens and CSS cascade layers — not app-specific global CSS. Acme's accent teal is restricted to the primary CTA, the logo mark, and the "Shortlisted" state only.
+> The app has **one** widget, `DiscoveryCarousel`, authored as a React `view` on the `discover_getaways` `tool`. It follows the OpenAI Apps SDK UI Guidelines (system fonts, monochrome outlined icons, WCAG AA, ≤2 actions per card, no nested scroll). Styling uses Noodle Seed's server-level `branding` tokens and CSS cascade layers — not app-specific global CSS. Acme's accent teal is restricted to the primary CTA, the logo mark, and the "Shortlisted" state only.
 
 ### 5.1 Design System Compliance
 
@@ -378,8 +378,8 @@ The demo's arc: *a vague mood → four real, priced, reasoned getaways → one s
 ```
 ChatGPT ──tool calls──►  Noodle Seed runtime (server 'acme_discovery')
                               │  app-owned curated catalog (static data)
-                              ├──► discover_getaways   (toolWithWidget → DiscoveryCarousel)
-                              ├──► shortlist_getaway    (toolForWidget, local write)
+                              ├──► discover_getaways   (tool → DiscoveryCarousel)
+                              ├──► shortlist_getaway    (tool, local write)
                               ├──► create_handoff       (open-link → signed Acme deep link)
                               └──► React view bundle (DiscoveryCarousel, branding tokens, CSP)
                                              │

package/skills/codex/examples/acme-discovery/design/wireframe.html

@@ -585,14 +585,14 @@
       <div class="api-step">
         <div class="an">1</div>
         <div class="ac">
-          <div class="tool">discover_getaways<span class="kind">toolWithWidget</span></div>
+          <div class="tool">discover_getaways<span class="kind">tool + view</span></div>
           <div class="api-note">In <code>{ vibe, month, travelers }</code> → out <code>{ status, vibe, month, travelers, options[] }</code> and renders <code>DiscoveryCarousel</code>. Returns the <strong>full curated catalog verbatim</strong> (4 destinations); the model narrates fit. Host status: "Finding getaways…" → "Getaways ready". <code>read-only</code>.</div>
         </div>
       </div>
       <div class="api-step">
         <div class="an">2</div>
         <div class="ac">
-          <div class="tool">shortlist_getaway<span class="kind">toolForWidget</span></div>
+          <div class="tool">shortlist_getaway<span class="kind">tool + app visibility</span></div>
           <div class="api-note">In <code>{ destination, note }</code> → out <code>{ status, destination, note }</code>. Called from inside the carousel when a card's <strong>Shortlist</strong> is tapped; updates widget view-state. <code>local-action</code>, non-destructive — not a booking.</div>
         </div>
       </div>