@noodleseed/agent-kit 0.21.1 → 0.23.0

package/skills/claude-code/references/embedded-assistant.md

@@ -8,9 +8,10 @@
 - Access modes and customer auth
 - Create the backend client
 - Integrate the customer backend
+- Ground time and ambient facts
 - Verified session context (identity and claims)
 - The session response
-- Mount the browser component
+- Choose a browser renderer
 - Toolchain requirements
 - Verify the boundary
 - Troubleshooting: symptom to diagnosis
@@ -32,6 +33,7 @@ Use the same server tools in the embed; do not create a second tool set. Declare
 
 ```ts
 branding: { name: "Acme", accent: "#3157D5" },
+context: { defaults: { locale: "en-GB", timeZone: "Europe/London" } },
 assistant: embeddedAssistant({
   model: openAICompatible({
     baseUrl: variable("ASSISTANT_MODEL_BASE_URL"),
@@ -105,6 +107,8 @@ export async function POST(request: Request) {
     origin: process.env.PUBLIC_APP_ORIGIN!,
     user: { id: user.id, email: user.email, roles: user.roles },
     context,
+    // Saved, backend-verified user preferences outrank browser hints.
+    preferences: { locale: user.locale, timeZone: user.timeZone },
   });
   return Response.json(session);
 }
@@ -114,6 +118,34 @@ Authenticate before exchange. Source `origin` from trusted server configuration
 
 `serviceUrl` is the Noodle Seed control-plane base URL: the value `noodle assistant clients create` prints, also stored as `serviceUrl` in `deployment.json`. It is NOT the deployment MCP endpoint (`url`, which ends in `/v1/mcp` and rejects session exchange). Never probe or guess endpoints with real credentials.
 
+## Ground time and ambient facts
+
+Every assistant turn receives a server-authoritative instant and user-local date/time. Locale and IANA time zone resolve in this order: backend-verified `preferences` from session exchange, fresh per-turn browser `clientContext` hints, `server.context.defaults`, then platform defaults (`en-US`/`UTC`). Browser hints affect presentation and relative-date interpretation only; they are untrusted and never authorize a tool.
+
+Use the server-level context declaration for application facts that every surface should share:
+
+```ts
+context: {
+  defaults: { locale: 'en-GB', timeZone: 'Europe/London' },
+  ambient: {
+    output: z.object({ defaultTeamId: z.string(), holidays: z.array(z.string()) }),
+    fulfil: ({ user, context, connectors }) => {
+      const calendar = connectors.people.getCalendar({
+        subject: user.subject,
+        asOf: context.temporal.instant,
+      });
+      return { defaultTeamId: calendar.default_team_id, holidays: calendar.holidays };
+    },
+  },
+},
+```
+
+The callback records declarative fulfilment at author time; the shared runtime executes only read-only connector operations, validates the declared output, and freezes one snapshot for the whole invocation and any accepted interaction. Tools/resources/prompts read `context.temporal`, `context.ambient`, and `context.ambientStatus`. The embedded assistant receives the same snapshot in trusted platform context. Canonical TypeScript `server()` authoring emits an empty context declaration even when you omit the option, so MCP clients receive the reserved read-only `noodle_context` temporal tool with zero setup; add `server.context` only for custom defaults or ambient facts. Raw Core-v1 manifests activate the adapter only when that field is present. Never declare a TypeScript author tool named `noodle_context`. Keep ambient facts compact: the platform caps serialized JSON at 16 KiB, depth 8, and 128 entries per container, and rejects credential-shaped keys.
+
+## Structured missing input
+
+A tool authored with `ctx.elicit({ id, message, input })` produces `input_requested` when it reaches the missing value. The built-in and headless renderers consume the same advertised endpoints and interaction-event protocol: either renderer presents that event and, after the current turn stream completes, calls `respond(id, { action: "accept", content })`; decline/cancel stop the flow. Accepted content is schema-validated and completed steps are not rerun; invalid content returns `arg_invalid` and leaves the same request pending for correction. A chained request receives a fresh id and `tool_completed` appears only after the final answer. Every interactive flow must collect all elicited input before its first connector operation. Elicitation gathers an input; it does not approve a later write, which remains separately confirmation-gated. In a flow marked `confirm: true`, every eligible `input_requested` precedes `tool_proposed`; the final proposal reviews the original tool input, elicited values, and sole exact connector version/operation/resolved arguments. Accept is bound to that action and only then may execution start. Confirmable flows may contain at most one connector operation. Bidirectional MCP transports map missing input to standard form `elicitation/create`; an adapter that cannot carry that request fails before executing the tool. The same negotiated form capability carries a final affirmative confirmation and fails closed when unavailable. At the manifest/runtime boundary and in TypeScript action helpers, omitted or `false` preserves direct execution; action hints alone never gate. `annotations.action({ confirm: false })`, like omission, runs directly, while `annotations.action({ confirm: true })` explicitly enables confirmation.
+
 ## Verified session context (identity and claims)
 
 The embedding developer defines what authenticated session context the assistant receives. One mechanism, three hops:
@@ -152,15 +184,17 @@ tool("greet", {
 });
 ```
 
-Manifest expressions use `${user.name}`, `${user.email}`, `${user.subject}`, `${user.claims.<key>}`. The model receives one platform identity line automatically: standard identity (name/email) whenever present, plus only the claims marked `exposeToModel: true` — so the assistant greets the actual user and can pass identity into tool arguments. `noodle check --target embedded-assistant` lists the declared claim contract.
+Manifest expressions use `${user.name}`, `${user.email}`, `${user.subject}`, `${user.locale}`, `${user.timeZone}`, and `${user.claims.<key>}`. The model receives one platform identity line automatically: standard identity (name/email) whenever present, plus only the claims marked `exposeToModel: true` — so the assistant greets the actual user and can pass identity into tool arguments. `noodle check --target embedded-assistant` lists the declared claim contract.
 
-Page `context` from the widget remains untrusted hint data; verified facts belong in `claims`, never in `context`.
+Page `context` from the widget remains untrusted hint data; verified identity/authorization facts belong in `claims`, saved locale/time-zone choices belong in backend `preferences`, and live business facts belong in `server.context.ambient`. Validated preferences also reach fulfilments as `user.locale` and `user.timeZone`, so connectors format in the same verified zone the invocation snapshot uses.
+
+To make the *downstream API call itself* run as the signed-in user (your API enforces its own per-user authorization instead of trusting a forwarded id), give the connector `auth.kind: "delegatedTokenExchange"` — the platform signs a verifiable assertion of this session identity and exchanges it at a token endpoint you implement. Assistant sessions carry the identity this needs; the full contract and a copyable endpoint implementation are in `references/authoring-workflow.md` ("Delegated downstream auth").
 
 ## The session response
 
-The exchange returns the versioned Embedded Assistant v1 contract. `token`, `expiresAt`, and `endpoints.turns` / `endpoints.toolConfirmations` (absolute URLs) are always present; `configuration` is optional theming data. Forward the body unchanged; the widget posts turns to `endpoints.turns` itself. Do not rebuild, filter, or rewrite the response.
+The exchange returns the versioned Embedded Assistant v1 contract. `token`, `expiresAt`, and `endpoints.turns` / legacy `endpoints.toolConfirmations` (absolute URLs) are always present; current services add `endpoints.interactions` for accept/decline/cancel. `configuration` is optional theming data. Forward the body unchanged; browser clients choose the advertised endpoint. Do not rebuild, filter, or rewrite the response.
 
-## Mount the browser component
+## Choose a browser renderer
 
 Use the React wrapper in React applications:
 
@@ -174,19 +208,65 @@ Or import the package root once and mount `<noodle-assistant session-endpoint="/
 
 The component renders a custom element and must mount client-side. In a Next.js App Router tree, put the mount in a `"use client"` component; from a server component or the Pages Router, load it with `next/dynamic` and `ssr: false`.
 
+For a customer-owned renderer, use the DOM-free client. It keeps the session token in memory, streams the same typed events, and never registers a custom element:
+
+```ts
+import { createAssistantClient } from "@noodleseed/assistant/client";
+
+const assistant = createAssistantClient({
+  sessionEndpoint: "/api/assistant/session",
+  clientContext: () => ({
+    locale: navigator.language,
+    timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+  }),
+});
+
+assistant.updateModelContext({
+  content: [{ type: 'text', text: 'The time-off form is mounted.' }],
+  structuredContent: { widget: { name: 'time-off', lifecycle: 'mounted' } },
+});
+
+let pendingId: string | undefined;
+let requestedSchema: unknown;
+assistant.subscribe((event) => {
+  renderAssistantEvent(event);
+  if (event.event === 'view_available') {
+    renderRegisteredView(event.data.resourceUri, event.data.result);
+  }
+  if ((event.event === 'tool_proposed' || event.event === 'input_requested') && typeof event.data.id === 'string') {
+    pendingId = event.data.id;
+    requestedSchema = event.event === 'input_requested' ? event.data.requestedSchema : undefined;
+  }
+});
+
+await assistant.sendMessage("Book next Thursday and Friday off");
+if (pendingId) {
+  const resolution = requestedSchema
+    ? { action: 'accept' as const, content: await renderPortableForm(requestedSchema) }
+    : { action: 'accept' as const };
+  await assistant.respond(pendingId, resolution);
+}
+// The same pending id also accepts { action: 'decline' } or { action: 'cancel' }.
+```
+
+`view_available` means a completed tool has a linked MCP App view. It carries the call/interaction id, tool, `ui://` identity, optional title, and bounded/redacted public result; it does not claim that anything rendered. A headless customer renderer maps that identity to an already-trusted component. Never fetch the `ui://` URI or inject its HTML. The standard element likewise does not render it; it dispatches `assistant-view-available` with the same detail.
+
+`clientContext` is recomputed for each turn. `updateContext(...)` changes separate untrusted page context for the next session exchange; call `resetSession()` when it must take effect immediately. `updateModelContext({ content, structuredContent })` publishes one cohesive renderer snapshot for later message turns without starting a turn; every call replaces the prior snapshot rather than merging fields. It is untrusted per-turn data, not conversation history or authorization input, and both boundaries reject credential-shaped or unbounded updates. A message may re-exchange once after a pre-execution `401`; the client never auto-retries interaction decisions. `tool_proposed.arguments` is a complete schema-aware review projection and, for connector-backed tools, names the sole exact connector version, operation, and resolved arguments. Sensitive/write-only fields are redacted; truncating or omitting any non-sensitive action field fails closed. Accept is bound to the server-held action and claims at most one execution attempt—clients cannot replace it. Normal terminal outcomes scrub private arguments and continuations immediately; only an accepted action still executing retains them for the one-hour unknown-outcome recovery window, after which it records `interaction_outcome_unknown` and scrubs. Without downstream idempotency this is not an exactly-once business-effect guarantee. To reconcile a lost response, explicitly repeat the same id and decision: the service returns its durable stored outcome without re-execution.
+
 ## Toolchain requirements
 
 - Node.js 20+ for `@noodleseed/assistant/server`.
 - The package ships ESM and CommonJS with full export conditions; no bundler aliases, `transpilePackages`, or ambient type shims are needed. If resolution fails, the installed package version is outdated: update `@noodleseed/assistant` instead of adding workarounds.
-- TypeScript `moduleResolution` `bundler` or `node16` recommended; classic `node` also resolves the `/react` and `/server` subpaths.
+- TypeScript `moduleResolution` `bundler` or `node16` recommended; classic `node` also resolves the `/client`, `/react`, and `/server` subpaths.
 
 ## Verify the boundary
 
 - Signed-out session exchange returns `401`.
 - The browser network/DOM/storage contains no client secret or model key.
 - The local and production origins match `allowedOrigins` character-for-character.
-- Auto-run requires the full safe-read annotation (`annotations.readOnly()`: read-only, non-destructive, closed-world); unannotated or partially annotated tools always confirm. Writes require confirmation by design.
-- An expired turn re-exchanges once; confirmations never replay.
+- At the manifest/runtime boundary and in TypeScript action helpers, only `confirm: true` enables confirmation; omitted or `false` preserves Core-v1 direct execution. Action hints alone never enforce approval; `annotations.action({ confirm: false })` is equivalent to omission.
+- An expired turn re-exchanges once; interaction decisions never auto-retry. An explicit same-decision repeat returns the stored outcome without executing again.
+- Accept, decline, and cancel are single-use. Only accept executes; the server ignores replacement tool arguments.
 - Wrong-origin and malformed-origin requests fail closed.
 
 ## Troubleshooting: symptom to diagnosis
@@ -201,8 +281,13 @@ The component renders a custom element and must mount client-side. In a Next.js
 | Session exchange returns 404 | `serviceUrl` points at the deployment MCP endpoint | Use the control-plane service URL printed by `noodle assistant clients create` |
 | Session exchange returns 403 `origin is not allowed` | Request origin differs from `allowedOrigins` character-for-character | Align the exact scheme/host/port on both sides and redeploy |
 | Hydration or `HTMLElement is not defined` errors | The component mounted during server rendering | Mount client-only (`"use client"` or `next/dynamic` with `ssr: false`) |
-| A read-only tool still asks for confirmation | Its annotations fail the safe-read rule: auto-run requires `readOnlyHint: true`, `destructiveHint: false`, AND `openWorldHint: false` (use `annotations.readOnly()`; `readOnly({ openWorld: true })` confirm-gates) | Fix the annotations; `noodle check --target embedded-assistant` lists every confirm-gated tool |
+| A tool runs without the expected confirmation | Its compiled annotations omit `confirm: true` or explicitly set `false` | Pass `{ confirm: true }` to the action helper; action hints alone never gate. `noodle check --target embedded-assistant` lists every confirm-gated tool |
 | `${user.claims.<key>}` is empty | Claim not declared in `sessionClaims` (or key typo) — undeclared claims are dropped at exchange | Declare the key in `embeddedAssistant({ sessionClaims })` and redeploy |
 | `${user.name}` is empty | Backend did not pass `user.name` to `createAssistantSession` | Pass the verified name from the authenticated backend session |
 | The model does not know a claim you passed | Claim is tools-only | Mark it `exposeToModel: true` in `sessionClaims` |
-| Behavior does not change after `noodle deploy` | Outdated platform: before the 2026-07 fix, clients were pinned to their creation-time deployment | Update the platform; sessions now follow the tenant's active deployment |
+| Relative dates use the wrong day or time zone | No verified user preference and the browser hint is missing/stale | Pass saved `preferences` from the backend; provide a fresh per-turn `clientContext` in a headless renderer |
+| The model invents a team/holiday after context lookup fails | The ambient provider returned invalid data or its read-only connector failed (`ambientStatus: unavailable`) | Fix the provider/connector; treat unavailable ambient facts as missing, never prompt instructions |
+| Decline/cancel reports `unsupported_service` | The session came from a legacy service with no `endpoints.interactions` | Upgrade the service; legacy `toolConfirmations` supports accept only |
+| Behavior does not change after `noodle deploy` | Outdated platform: before the 2026-07 fix, clients were pinned to their creation-time deployment | Update the platform; sessions now follow the tenant's active deployment |
+| A delegated connector tool fails with `delegated token exchange requires a verified customer caller` | The calling surface has no verified customer identity (or an old session minted before the platform carried the resource audience) | Verify `customerAuth` is configured and the backend passes the verified `user` to `createAssistantSession`; re-mint the session |
+| Deploy fails with `unsupported_delegated_provider` | `delegatedOAuth.provider` only supports the managed `firebase`/`microsoft` bridges | Use `auth.kind: "delegatedTokenExchange"` for your own token endpoint (see authoring-workflow.md) |

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

@@ -14,12 +14,12 @@ Paths are relative to this skill directory. Assets (images/fonts) are omitted fr
 | `acme-discovery` | Top-of-funnel discovery→handoff: a discovery carousel, a `create_handoff` deep link, and a design-first UX spec + wireframe. | `examples/acme-discovery/src/server.ts` + `design/` |
 | `acme-tasks` | A two-way productivity app designed around its top-3 prioritized flows (capture/prioritize/complete), with a design-first flow spec + wireframe. | `examples/acme-tasks/src/server.ts` + `design/` |
 | `acme-bistro` | End-to-end ordering with a payment-only handoff; ships a gold-standard `design/` set (UX doc, wireframe with compliance audit, API contract). | `examples/acme-bistro/src/server.ts` + `design/` |
+| `customer-auth` | End-user (customer) auth via OIDC/Firebase bridge with delegated credentials. | `examples/customer-auth/src/server.ts` |
 
 ## In the repository only — `examples/<name>/` on GitHub
 
 | Example | Use when |
 | :-- | :-- |
-| `customer-auth` | End-user (customer) auth via OIDC/Firebase bridge with delegated credentials. |
 | `stateful-draft` | Durable, caller-scoped widget state handles with optimistic revisions. |
 | `perplexity` | A real SaaS API with bearer auth and a managed `secret`. |
 | `bitcoin` | API-key HTTP connector, custom auth header, and compute normalization. |

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

@@ -127,7 +127,7 @@ prompt('summarize_ticket', {
 
 ### 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).
+`ctx` is `{ input, user, connectors }`. Bind connectors with `use` on the server, then call one inside `fulfil` to record a step. `annotations.readOnly()` declares a closed-world safe read. TypeScript action helpers enforce confirmation only with `{ confirm: true }`; omitted or `false` executes directly, and action/destructive/open-world hints alone never enable the gate. `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';
@@ -169,7 +169,7 @@ export default server('support', { title: 'Support', version: '1.0.0', use: { cr
     description: 'Echo text back.',
     input: z.object({ text: z.string() }),
     output: z.object({ echo: z.string() }),
-    annotations: annotations.action(), // mutating / world-affecting hint
+    annotations: annotations.action(), // world-affecting hint; add { confirm: true } to gate
     // fulfil may be async — the compiler awaits it while recording the flow.
     fulfil: async ({ input }) => ({ echo: input.text }),
   }),

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

@@ -38,10 +38,12 @@ Author views as React components. `generateHelpers<ServerDefinition>()` (from `@
 | `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. |
+| `useUpdateModelContext` | Publish one compact, cohesive author-selected text/structured snapshot through the standard MCP Apps model-context channel; each call replaces the prior snapshot, so include every still-relevant field and check `useLayout().supports?.modelContext` first. |
+| `useWidgetLifecycle` | Calling the hook auto-publishes `mounted` and listens for host `cancelled`/`dismissed`; use its publisher for author-owned `submitted` or app milestones, include a complete safe replacement snapshot, and pair explicit submit/cancel with `useSendFollowUpMessage` when an immediate reply is wanted. |
 | `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>`).
+Bind interactive elements to tools (`useCallTool("place_order")`), drive named views with `useAppFlow(...)`, open server-created handoffs with `useHandoff()`, and publish one compact, safe, cohesive snapshot with `useUpdateModelContext()` when `useLayout().supports?.modelContext` is true. Every model-context or lifecycle publication replaces the prior snapshot rather than merging fields, so include everything the model should still know. Calling `useWidgetLifecycle("name")` automatically publishes `mounted`, listens for host `cancelled` and `dismissed`, and returns a publisher for author-owned `submitted` or app-specific milestones; `mounted` is not proof that the host presented pixels. Both hooks use the standard MCP Apps model-context channel, not a host-specific API. These updates affect future model context but do not start a model turn. When an explicit user submit/cancel should receive an immediate reply, also call `useSendFollowUpMessage()` from that user action. `data-llm` may remain a DOM inspection hint, but it is not the bidirectional model-state contract. 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
 
@@ -49,14 +51,15 @@ Minimal, complete, and compile-verified — `noodle validate` bundles the view a
 
 ### 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`.
+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 publish cohesive model-context snapshots plus author-owned lifecycle milestones.
 
 ```tsx
+import { useEffect } from 'react';
 import type { ServerDefinition } from '@noodleseed/one';
 import { Action, ActionBar, AsyncBoundary, Feedback, Field, Flow, Frame, Region, Select, generateHelpers } from '@noodleseed/one/react';
 
 // One call wires the typed host bridge; destructure only the hooks this view uses.
-const { useToolInfo, useCallTool, useViewState, useOpenExternal } =
+const { useToolInfo, useCallTool, useViewState, useLayout, useOpenExternal, useSendFollowUpMessage, useUpdateModelContext, useWidgetLifecycle } =
   generateHelpers<ServerDefinition>();
 
 type OrderResult = {
@@ -69,14 +72,36 @@ type OrderResult = {
 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 { supports } = useLayout();
   const openExternal = useOpenExternal();
+  const sendFollowUpMessage = useSendFollowUpMessage();
+  const updateModelContext = useUpdateModelContext();
+  const publishLifecycle = useWidgetLifecycle('pickup-order');
   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 ?? '';
 
+  useEffect(() => {
+    if (!supports?.modelContext) return;
+    void updateModelContext({
+      content: [{ type: 'text', text: `Pickup order: ${item}, total ${total}` }],
+      structuredContent: { widget: { name: 'pickup-order', lifecycle: 'active' }, order: { item, total } },
+    });
+  }, [item, supports?.modelContext, total, updateModelContext]);
+
+  async function submitOrder() {
+    await placeOrder.callTool({ customer: shown?.customer ?? 'Guest', item });
+    if (supports?.modelContext) {
+      await publishLifecycle('submitted', { surface: 'order', item, total, status: 'submitted' });
+    }
+    if (supports?.followUpMessage) {
+      await sendFollowUpMessage({ prompt: `The pickup order was submitted for ${item}. Confirm the result.` });
+    }
+  }
+
   return (
-    // data-llm mirrors the visible state back to the model as text context.
+    // data-llm is an inspection hint; useUpdateModelContext above is the model-visible channel.
     <Frame title="Pickup order" displayMode="auto" data-llm={`Pickup order for ${shown?.customer ?? 'Guest'}: ${item}, total ${total}`}>
       <Flow variant="stack">
       <AsyncBoundary state={placeOrder} loading="Placing order…" error={(error) => error.message}>
@@ -92,7 +117,7 @@ export default function OrderStatus() {
       {confirmed?.status ? <Feedback status="success">{confirmed.status}</Feedback> : null}
       <ActionBar>
       <Action variant="primary" pending={placeOrder.isPending} pendingLabel="Placing…"
-        onClick={() => placeOrder.callTool({ customer: shown?.customer ?? 'Guest', item })}
+        onClick={submitOrder}
       >
         Place order
       </Action>
@@ -160,8 +185,8 @@ export default server(
     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(),
+      // Widget-mediated direct action: explicit false is equivalent to omitting confirmation.
+      annotations: annotations.action({ confirm: false }),
       input: z.object({ customer: z.string().default('Guest'), item }),
       output: z.object({ status: z.string(), item: z.string(), checkoutUrl: z.string() }),
       fulfil: ({ input }) => ({

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.21.1
+version: 0.23.0
 hash: cd25535e1d6dbf4f
 ---
 

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

@@ -29,7 +29,7 @@ const menuItemOutput = z.object({
 // Tool annotations for host planners: the menu read is read-only; cart edits are local writes; checkout
 // opens an external (payment) link.
 const readOnly = annotations.readOnly();
-const localWrite = annotations.localAction({ destructive: false });
+const localWrite = annotations.localAction({ destructive: false, confirm: false });
 const openLink = annotations.openAction();
 
 export default server(

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

@@ -83,7 +83,7 @@ const discoverInput = z.object({
 // shortlisting is a local non-destructive write.
 const readOnly = annotations.readOnly();
 const openLink = annotations.openAction();
-const localWrite = annotations.localAction({ destructive: false });
+const localWrite = annotations.localAction({ destructive: false, confirm: false });
 
 const destinationOutput = z.object({
   id: z.string(),

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

@@ -28,6 +28,8 @@ const priority = z.enum(['high', 'medium', 'low']);
 // non-destructive writes.
 const readOnly = annotations.readOnly();
 const localWrite = annotations.localAction({ destructive: false });
+const confirmedWrite = annotations.localAction({ destructive: false, confirm: true });
+const widgetWrite = annotations.localAction({ destructive: false, confirm: false });
 
 const taskOutput = z.object({
   id: z.string(),
@@ -104,7 +106,7 @@ export default server(
     // Flow 3 — Complete: mark a task done. Model-visible so the model can complete on request.
     tool('complete_task', {
       description: 'Mark an Acme task complete. Pass the task id and its title.',
-      annotations: localWrite,
+      annotations: confirmedWrite,
       input: z.object({
         task: z.string(),
         title: z.string().min(1),
@@ -122,7 +124,7 @@ export default server(
     tool('set_priority', {
       visibility: ['app'],
       description: 'Re-prioritize a task from the list widget.',
-      annotations: localWrite,
+      annotations: widgetWrite,
       input: z.object({
         task: z.string(),
         priority,

package/skills/codex/examples/acme-tasks/test/server.test.ts

@@ -19,4 +19,13 @@ describe('acme-tasks example', () => {
     const text = JSON.stringify(await app.toManifest());
     expect(text).toMatch(/"tasks":\[\{"id":"email_vendor".*"priority":"high"/);
   });
+
+  it('opts the conversational completion action into runtime confirmation', async () => {
+    const manifest = await app.toManifest();
+    const completeTask = manifest.tools.find((candidate) => candidate.name === 'complete_task');
+    const addTask = manifest.tools.find((candidate) => candidate.name === 'add_task');
+
+    expect(completeTask?.annotations?.confirm).toBe(true);
+    expect(addTask?.annotations).not.toHaveProperty('confirm');
+  });
 });

package/skills/codex/examples/customer-auth/README.md

@@ -0,0 +1,237 @@
+# Customer Auth - NoodleSeed.com Firebase customer identity
+
+This curated example owns the customer/end-user authentication with Firebase bridge capability slot. It is
+the NoodleSeed.com dogfood app for proving that a SaaS app can protect an MCP endpoint with its own customer
+identity provider while still using the generic Noodle Seed authoring API.
+
+It also owns the embedded-assistant showcase: the same authenticated MCP surface can be dropped into the
+SaaS web application as a fully customer-branded assistant with independent light and dark themes. The
+assistant loads the active deployment's instructions and model-visible tools rather than installing a stale
+second skill bundle. Interactive MCP Apps widgets continue to render in supported external hosts; the
+initial embedded surface renders text and native tool confirmations.
+
+The public developer entrypoint is [`src/server.ts`](src/server.ts). It declares `customerAuth.firebase(...)` with
+the NoodleSeed.com Firebase project and Firebase Web App public config. It exposes a deliberately small MCP
+surface for org discovery:
+
+- `list_my_organizations` lists the NoodleSeed.com organizations the signed-in customer belongs to (no
+  arguments — the org set comes from the verified customer session).
+- `list_org_apps` lists apps for one of those organizations through the dev app API.
+
+The two tools chain: `list_my_organizations` surfaces the `org_id`s the customer can act on, and
+`list_org_apps` takes one of those `org_id`s. There is no NoodleSeed-specific SDK helper. The downstream API
+is an ordinary authored HTTP connector.
+
+During MCP OAuth login, Noodle Cloud hosts the Firebase bridge page at
+`https://cloud.noodleseed.dev/oauth/customer/firebase/authorize`. The customer app does not add an
+authorization route. The SaaS operator only configures Firebase Auth to allow the Noodle Cloud origin, and
+Noodle Cloud signs the customer in with Firebase before posting the Firebase ID token back to its own bridge
+callback.
+
+## How delegated customer credentials are used
+
+The example has two declarations that work together:
+
+```ts
+auth: customerAuth.firebase({
+  projectId: variable('FIREBASE_PROJECT_ID'),
+  apiKey: variable('FIREBASE_WEB_API_KEY'),
+  authDomain: variable('FIREBASE_AUTH_DOMAIN'),
+  user: {
+    id: 'sub',
+    email: 'email',
+    name: 'name',
+    tenant: 'firebase.tenant',
+    orgs: 'claims.orgs',
+    roles: 'claims.roles',
+  },
+}),
+```
+
+That protects the MCP endpoint with the SaaS customer's Firebase identity. The connector then opts into
+delegated customer credentials:
+
+```ts
+auth: {
+  kind: 'delegatedSessionCookie',
+  provider: 'firebase',
+  sessionUrl: `${noodleseedApiOrigin}/api/auth/session`,
+  tokenField: 'idToken',
+},
+```
+
+Tool code calls the connector normally:
+
+```ts
+fulfil({ input, connectors }) {
+  const apps = connectors.app_api.listOrgApps({
+    org_id: input.org_id,
+    skip: input.skip,
+    limit: input.limit,
+  });
+
+  return { result: apps.result };
+}
+```
+
+At runtime, Noodle Seed verifies the Firebase customer during MCP OAuth, stores that customer's delegated
+Firebase refresh token in the credential broker, and refreshes a short-lived Firebase ID token only when a
+connector-backed tool calls the NoodleSeed.com API. For this app API, the broker exchanges that ID token at
+the existing Next.js `/api/auth/session` route and sends the resulting session cookie to the API. The MCP
+access token remains a Noodle-issued resource-bound token and is never sent to the downstream API.
+
+## Delegated downstream auth for your own API (token exchange)
+
+The Firebase path above only works for Firebase-session downstreams. When the downstream is **your own
+API** with its own token issuance, use `delegatedTokenExchange` instead
+([ADR 0152](../../docs/decisions/0152-delegated-token-exchange-connector-auth.md)): the platform signs a
+short-lived, JWKS-verifiable assertion of the signed-in user and exchanges it (RFC 8693) at a token
+endpoint you implement, which mints your own user-scoped token — so your API enforces its own per-user
+authorization on every call. It works for identities from `customerAuth.bridge(...)` and from embedded
+assistant sessions, with no per-user OAuth enrollment.
+
+```ts
+auth: {
+  kind: 'delegatedTokenExchange',
+  tokenUrl: 'https://app.example.com/api/assistant/oauth/token', // origin must be in allowedOrigins
+  clientId: variable('EXAMPLE_DELEG_CLIENT_ID'),
+  clientSecret: secret('EXAMPLE_DELEG_CLIENT_SECRET'),
+  scopes: ['time_off'],
+},
+```
+
+Your endpoint authenticates the broker's client credential, verifies the `subject_token` JWT against the
+platform issuer JWKS (claims include the verified `sub`, `email`, `name`, declared session `claims`,
+`tenant`, and `deployment`), mints a short-lived user-scoped token, and returns the standard
+`{ access_token, token_type, expires_in }` response. The exact wire contract and a copyable endpoint
+implementation live in [docs/spec/connectors.md](../../docs/spec/connectors.md) and the Agent Kit
+authoring-workflow reference ("Delegated downstream auth"). `noodle auth doctor` reports each declared
+exchange endpoint.
+
+## Validate
+
+```bash
+noodle auth doctor examples/customer-auth/src/server.ts
+noodle validate examples/customer-auth/src/server.ts
+```
+
+## Run locally
+
+```bash
+noodle dev examples/customer-auth/src/server.ts --app noodleseed-customer-auth
+```
+
+## Configuration
+
+The embedded assistant uses a customer-supplied OpenAI Chat Completions-compatible endpoint. Configure its
+managed values at the Noodle deployment environment; none of these values belongs in the customer web
+application environment, and the API key never reaches the browser:
+
+```bash
+noodle variables set ASSISTANT_MODEL_BASE_URL https://model.example.com/v1 --scope env
+noodle variables set ASSISTANT_MODEL your-model --scope env
+noodle secrets set ASSISTANT_MODEL_API_KEY --scope env
+noodle variables set FIREBASE_PROJECT_ID your-firebase-project --scope env
+noodle variables set FIREBASE_WEB_API_KEY your-firebase-web-api-key --scope env
+noodle variables set FIREBASE_AUTH_DOMAIN your-firebase-project.firebaseapp.com --scope env
+noodle check --target embedded-assistant src/server.ts
+```
+
+Assistant origins are exact and HTTPS-only. A local embedding application must serve itself over HTTPS and
+declare an origin such as `https://localhost:3000`; `noodle dev` does not provide TLS for that separate web
+application.
+
+Create the backend credential after deployment. The CLI writes it to a mode-0600 file and never prints the
+secret:
+
+```bash
+noodle assistant clients create --name web --org noodleseed --app customer-auth --env prod
+```
+
+Only the Noodle service URL, assistant client ID, and assistant client secret belong in the authenticated
+customer backend. The model URL, model name, and model API key remain managed by the Noodle deployment.
+
+The customer's authenticated backend calls `createAssistantSession(...)` from
+`@noodleseed/assistant/server`, passing the already-verified user and browser origin. The browser then uses
+the returned short-lived session through the Web Component or React wrapper:
+
+```bash
+pnpm add @noodleseed/assistant
+```
+
+```tsx
+import { NoodleAssistant } from '@noodleseed/assistant/react';
+
+<NoodleAssistant
+  sessionEndpoint="/api/noodle-assistant/session"
+  theme="auto"
+  onSessionExpired={() => console.info('Assistant session renewed')}
+/>;
+```
+
+`theme="auto"` follows the SaaS application. The server-level `branding` block is inherited by both MCP App
+widgets and the assistant; documented `--ns-assistant-*` semantic CSS variables remain the final integration
+escape hatch. There is no second assistant branding declaration.
+The end-user UI contains only customer branding.
+Text streams progressively. Expired turns re-exchange through the authenticated backend and retry once;
+consent-bound tool confirmations never replay automatically.
+
+The Firebase project ID is required because Firebase ID tokens use the project ID as the token audience and
+issuer suffix. The runtime verifies `aud` against the project ID and `iss` against
+`https://securetoken.google.com/<projectId>`.
+
+The Firebase Web API key and auth domain are public Firebase browser configuration. They let the Noodle
+Cloud-hosted bridge initialize Firebase Auth for this customer project; they are not server secrets. Keep
+them out of source with `variable(...)`, restrict the Firebase key to the expected browser origins and APIs,
+and use `secret(...)` only for credentials that must never reach a browser.
+
+The `noodleseed_app_api` connector currently points at the NoodleSeed.com dev app surface:
+
+```text
+https://dev.noodleseed.com
+```
+
+When the customer app moves from `dev.noodleseed.com` to `app.noodleseed.com`, update the connector's
+`noodleseedApiOrigin` constant to the production API origin that serves the same paths.
+
+The connector uses delegated Firebase customer credentials. During the customer OAuth bridge, Noodle Seed
+verifies the Firebase ID token, stores the Firebase refresh token through the credential broker, and refreshes
+a Firebase ID token when the connector calls the NoodleSeed.com app API. The broker then exchanges that ID
+token for the app's existing Next.js session cookie. There is no shared `NOODLESEED_APP_API_TOKEN` for this
+example.
+
+Firebase Auth must list `cloud.noodleseed.dev` as an authorized domain before browser sign-in works in
+production.
+
+## Deploy customer-protected to Noodle Seed Cloud
+
+```bash
+noodle deploy examples/customer-auth/src/server.ts \
+  --org noodleseed \
+  --app customer-auth \
+  --env prod \
+  --access customers
+```
+
+Endpoint:
+
+```text
+https://cloud.noodleseed.dev/o/noodleseed/customer-auth/mcp
+```
+
+## MCP Primitives
+
+- Tool `list_my_organizations`: calls `GET /api/organizations` and returns the organizations the signed-in
+  customer is a member of. Takes no arguments; the org set is scoped by the verified customer session.
+- Tool `list_org_apps`: calls `GET /api/organizations/{org_id}/apps` for one organization `org_id`.
+
+## Auth boundary
+
+Firebase ID-token verification is handled by Noodle Seed's generic Firebase bridge adapter during OAuth
+issuance. The MCP client receives a Noodle-issued, resource-bound access token marked as a Firebase customer
+identity; raw Firebase tokens and inbound MCP bearer tokens are never forwarded to tools, connectors,
+widgets, or downstream systems.
+
+The connector-backed tools use the credential broker to turn the signed-in Firebase customer session into the
+same session-cookie credential that the existing NoodleSeed.com Next.js API already expects. The inbound MCP
+bearer token is never used as an app API credential.

package/skills/codex/examples/customer-auth/noodle.json

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