@noodleseed/agent-kit 0.16.0 → 0.18.0

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

@@ -19,13 +19,13 @@ const geocoding = connector('open_meteo_geocoding')
         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' },
-        },
+        input: z.object({ name: z.string() }),
+        output: z.object({
+          latitude: z.number(),
+          longitude: z.number(),
+          place: z.string().optional(),
+          country: z.string().optional(),
+        }),
         response: {
           latitude: '${response.results[0].latitude}',
           longitude: '${response.results[0].longitude}',
@@ -44,13 +44,8 @@ const geocoding = connector('open_meteo_geocoding')
         method: 'GET',
         path: '/v1/search',
         query: ['name', 'count'],
-        input: {
-          name: { type: 'string', required: true },
-          count: { type: 'number' },
-        },
-        output: {
-          results: { type: 'array' },
-        },
+        input: z.object({ name: z.string(), count: z.number().optional() }),
+        output: z.object({ results: z.array(z.unknown()).optional() }),
         response: {
           results: '${response.results}',
         },
@@ -69,15 +64,12 @@ const forecast = connector('open_meteo_forecast')
         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' },
-        },
+        input: z.object({ latitude: z.number(), longitude: z.number() }),
+        output: z.object({
+          temperature: z.number().optional(),
+          windspeed: z.number().optional(),
+          weathercode: z.number().optional(),
+        }),
         response: {
           temperature: '${response.current_weather.temperature}',
           windspeed: '${response.current_weather.windspeed}',
@@ -91,18 +83,18 @@ 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 },
-    },
+    input: z.object({
+      place: z.string(),
+      country: z.string().optional(),
+      temperature: z.number(),
+      windspeed: z.number(),
+      weathercode: z.number(),
+    }),
+    output: z.object({
+      conditions: z.string(),
+      headline: z.string(),
+      advice: z.string(),
+    }),
     // 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) => {
@@ -162,12 +154,8 @@ const placeNarrow = connector('geo_places')
   .version('1.0.0')
   .compute('narrow', {
     type: 'read',
-    input: {
-      results: { type: 'unknown' },
-    },
-    output: {
-      places: { type: 'array', required: true },
-    },
+    input: z.object({ results: z.unknown().optional() }),
+    output: z.object({ places: z.array(z.unknown()) }),
     // Self-contained: no imports, no closure over outer variables, synchronous.
     run: (input) => {
       const raw = input.results;

package/skills/codex/references/authoring-workflow.md

@@ -11,6 +11,7 @@
 - Compute connector example
 - Tests
 - Secrets and variables
+- Embedded assistant
 - Boundaries
 
 ## Input paths
@@ -55,16 +56,16 @@ const crm = connector('crm').version('1.0.0').http({
       method: 'GET',
       path: '/customers',
       query: ['email'],
-      input: { email: { type: 'string', required: true } },
-      output: { id: { type: 'string', required: true }, name: { type: 'string' } },
+      input: z.object({ email: z.string() }),
+      output: z.object({ id: z.string(), name: z.string().optional() }),
       response: { id: '${response.data[0].id}', name: '${response.data[0].name}' },
     },
     create_ticket: {
       type: 'action',
       method: 'POST',
       path: '/tickets',
-      input: { customer_id: { type: 'string', required: true }, body: { type: 'string', required: true } },
-      output: { ticket_id: { type: 'string', required: true } },
+      input: z.object({ customer_id: z.string(), body: z.string() }),
+      output: z.object({ ticket_id: z.string() }),
       request: { customer_id: '${args.customer_id}', body: '${args.body}' },
       response: { ticket_id: '${response.id}' },
     },
@@ -120,16 +121,16 @@ const tasks = connector('tasks').version('1.0.0').http({
       method: 'GET',
       path: '/tasks',
       query: ['query'],
-      input: { query: { type: 'string', required: true } },
-      output: { matches: { type: 'array', required: true } },
+      input: z.object({ query: z.string() }),
+      output: z.object({ matches: z.array(z.unknown()) }),
       response: { matches: '${response.results}' },
     },
     close_task: {
       type: 'action',
       method: 'POST',
       path: '/tasks/{id}/close',
-      input: { id: { type: 'string', required: true } },
-      output: { ok: { type: 'boolean', required: true } },
+      input: z.object({ id: z.string() }),
+      output: z.object({ ok: z.boolean() }),
       response: { ok: '${response.ok}' },
     },
   },
@@ -163,8 +164,8 @@ The model never sees a task id from the user; `find_tasks` returns `{ id, title
 
 ```ts
 const scoring = connector('scoring').version('1.0.0').compute('normalize', {
-  input: { email: { type: "string", required: true }, priority: { type: "string" } },
-  output: { score: { type: "number", required: true } },
+  input: z.object({ email: z.string(), priority: z.string().optional() }),
+  output: z.object({ score: z.number() }),
   calls: { find_customer: 'crm.find_customer' },
   limits: { timeoutMs: 1000, maxHostCalls: 2 },
   run(input, { callOperation }) {
@@ -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, 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"], appearance: { brand: { name: "Acme Assistant" }, theme: { defaultMode: "auto", light: { accent: "#3157D5" }, dark: { accent: "#9FB4FF" } } } })` to the server options. 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/codex/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/codex/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/codex/references/connect-an-api.md

@@ -62,7 +62,7 @@ Most real tools return a variable-length list (search results, a user’s tasks)
 
 ```ts
 // The API returns { results: [ { id, name, country, … }, … ] }
-output: { places: { type: 'array' } },
+output: z.object({ places: z.array(z.unknown()) }),
 response: { places: '${response.results}' },
 ```
 
@@ -96,7 +96,7 @@ Pair the read/list with the mutations your intent tools need:
 ```ts
 close_task: {
   type: 'action', method: 'POST', path: '/tasks/{id}/close',
-  input: { id: { type: 'string', required: true } },
+  input: z.object({ id: z.string() }),
   responseType: 'empty',
 },
 ```

package/skills/codex/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/codex/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.
 
@@ -144,8 +144,8 @@ const crm = connector('crm')
         method: 'GET',
         path: '/tickets',
         query: ['id'],
-        input: { id: { type: 'string', required: true } },
-        output: { subject: { type: 'string' }, status: { type: 'string' } },
+        input: z.object({ id: z.string() }),
+        output: z.object({ subject: z.string().optional(), status: z.string().optional() }),
         response: { subject: '${response.subject}', status: '${response.status}' },
       },
     },
@@ -195,8 +195,8 @@ const orders = connector('orders')
         method: 'GET',
         path: '/orders',
         query: ['id'],
-        input: { id: { type: 'string', required: true } },
-        output: { id: { type: 'string' }, status: { type: 'string' } },
+        input: z.object({ id: z.string() }),
+        output: z.object({ id: z.string().optional(), status: z.string().optional() }),
         response: { id: '${response.id}', status: '${response.status}' },
       },
       get_tracking: {
@@ -204,8 +204,8 @@ const orders = connector('orders')
         method: 'GET',
         path: '/tracking',
         query: ['order_id'],
-        input: { order_id: { type: 'string', required: true } },
-        output: { url: { type: 'string' } },
+        input: z.object({ order_id: z.string() }),
+        output: z.object({ url: z.string().optional() }),
         response: { url: '${response.url}' },
       },
     },

package/skills/codex/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/codex/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,7 +21,7 @@ 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. |
 | `useRequestDisplayMode` | Request a host-mediated layout change such as fullscreen; treat it as best-effort and keep inline rendering useful. |
@@ -94,10 +94,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 +112,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 +129,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 +142,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(),