@noodleseed/agent-kit 0.21.1 → 0.23.0

package/skills/claude-code/examples/customer-auth/src/server.ts

@@ -0,0 +1,145 @@
+import {
+  annotations,
+  connector,
+  customerAuth,
+  embeddedAssistant,
+  openAICompatible,
+  secret,
+  server,
+  tool,
+  variable,
+  z,
+} from '@noodleseed/one';
+
+const noodleseedApiOrigin = 'https://dev.noodleseed.com';
+
+const noodleseedApi = connector('noodleseed_app_api')
+  .version('1.0.0')
+  .http({
+    baseUrl: noodleseedApiOrigin,
+    allowedOrigins: [noodleseedApiOrigin],
+    auth: {
+      kind: 'delegatedSessionCookie',
+      provider: 'firebase',
+      sessionUrl: `${noodleseedApiOrigin}/api/auth/session`,
+      tokenField: 'idToken',
+    },
+    operations: {
+      list_org_apps: {
+        type: 'read',
+        method: 'GET',
+        path: '/api/organizations/${args.org_id}/apps',
+        query: ['skip', 'limit'],
+        input: z.object({
+          org_id: z.string(),
+          skip: z.number().optional(),
+          limit: z.number().optional(),
+        }),
+        output: z.object({ result: z.unknown().optional() }),
+        response: {
+          result: '${response}',
+        },
+      },
+      list_organizations: {
+        type: 'read',
+        method: 'GET',
+        path: '/api/organizations',
+        output: z.object({ organizations: z.array(z.unknown()).optional() }),
+        response: {
+          organizations: '${response.organizations}',
+        },
+      },
+    },
+  });
+
+export default server(
+  'noodleseed_customer_auth',
+  {
+    title: 'NoodleSeed.com Customer Auth',
+    version: '1.0.0',
+    branding: {
+      name: 'Noodle Seed Assistant',
+      accent: '#E85D24',
+      surface: '#FFFFFF',
+      surfaceDark: '#171310',
+      colorScheme: 'auto',
+      theme: {
+        light: { accentText: '#FFFFFF', text: '#1C1714' },
+        dark: { accent: '#FF8A4C', accentText: '#1C100A', text: '#FFF8F2' },
+      },
+    },
+    use: { app_api: noodleseedApi },
+    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',
+      },
+    }),
+    instructions:
+      'Customer-authenticated demo. Firebase proves the customer identity, while read-only NoodleSeed.com API calls use broker-managed delegated Firebase customer credentials.',
+    assistant: embeddedAssistant({
+      model: openAICompatible({
+        baseUrl: variable('ASSISTANT_MODEL_BASE_URL'),
+        model: variable('ASSISTANT_MODEL'),
+        apiKey: secret('ASSISTANT_MODEL_API_KEY'),
+      }),
+      // Production origins are exact HTTPS; http://localhost:<port> is allowed for local development.
+      allowedOrigins: [
+        'https://app.noodleseed.com',
+        'https://dev.noodleseed.com',
+        'http://localhost:3000',
+      ],
+      layout: { mode: 'floating', position: 'bottom-right', panelWidth: 420 },
+      labels: {
+        welcomeHeading: 'How can I help with Noodle Seed?',
+        composerPlaceholder: 'Ask about your apps…',
+      },
+      suggestedPrompts: ['Show my organizations', 'List the apps in my organization'],
+    }),
+  },
+  [
+    tool('list_org_apps', {
+      description: 'List NoodleSeed.com apps for an organization from the dev app API.',
+      input: z.object({
+        org_id: z.string(),
+        skip: z.number().int().min(0).optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+      }),
+      output: z.object({
+        result: z.unknown(),
+      }),
+      annotations: annotations.readOnly(),
+      fulfil({ input, connectors }) {
+        const apps = connectors.app_api.listOrgApps({
+          org_id: input.org_id,
+          skip: input.skip,
+          limit: input.limit,
+        });
+        return {
+          result: apps.result,
+        };
+      },
+    }),
+    tool('list_my_organizations', {
+      description: 'List the NoodleSeed.com organizations the signed-in customer belongs to.',
+      input: z.object({}),
+      output: z.object({
+        organizations: z.array(z.unknown()),
+      }),
+      annotations: annotations.readOnly(),
+      fulfil({ connectors }) {
+        const organizations = connectors.app_api.listOrganizations();
+        return {
+          organizations: organizations.organizations,
+        };
+      },
+    }),
+  ],
+);

package/skills/claude-code/examples/customer-auth/test/server.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import app from '../src/server.js';
+
+describe('customer-auth example', () => {
+  it('exports a customer-authenticated, customer-branded embedded assistant', async () => {
+    expect(typeof app.toManifest).toBe('function');
+    const manifest = await app.toManifest();
+    expect(manifest.server.assistant).toMatchObject({
+      model: { kind: 'openai-compatible', apiKey: 'ASSISTANT_MODEL_API_KEY' },
+      layout: { mode: 'floating' },
+    });
+    expect(
+      manifest.server.assistant?.allowedOrigins.every((origin) => origin.startsWith('https://')),
+    ).toBe(true);
+    expect(manifest.server.branding).toMatchObject({
+      name: 'Noodle Seed Assistant',
+      colorScheme: 'auto',
+    });
+    expect(manifest.server.auth).toMatchObject({
+      projectId: '${env.FIREBASE_PROJECT_ID}',
+      apiKey: '${env.FIREBASE_WEB_API_KEY}',
+      authDomain: '${env.FIREBASE_AUTH_DOMAIN}',
+    });
+  });
+});

package/skills/claude-code/examples/food-ordering/README.md

@@ -1,8 +1,9 @@
 # Food Ordering
 
 **Owns:** The flagship consumer ordering MCP App example: React view authoring, app-only helper tools,
-caller-scoped cart state handles, packaged image assets, checkout handoff policy, host actions,
-CSP/permissions metadata, and widget preview coverage.
+caller-scoped cart state handles, invocation context, model-visible widget state/lifecycle, packaged image
+assets, portable structured elicitation, checkout handoff policy, host actions, CSP/permissions metadata,
+and widget preview coverage.
 
 Food Ordering is a generic, synthetic version of a live marketplace ordering app. It lets a user search
 stores, browse menus, customize an item, build a multi-line cart, review the order, and hand off checkout to
@@ -14,10 +15,13 @@ private customer data.
 | Capability | Example |
 | :--- | :--- |
 | Public entry tool | `open_ordering` returns structured fallback content and renders the React widget |
-| App-only helper tools | `search_stores`, `load_menu`, `load_item`, `read_cart`, `sync_cart`, `prepare_checkout` |
+| App-only helper tools | `search_stores`, `load_menu`, `load_item`, `read_cart`, `sync_cart`, `prepare_checkout`; mutating widget-owned helpers use `confirm: false` (equivalent to omission) and execute directly because action hints alone never gate |
 | Durable cart state | `server(..., { state: { handles: { cart } }, use: { state } })` with caller scope and revision checks |
 | React app runtime kit | `@noodleseed/one/react` supplies app flow, shell/nav/view, async state, form, quantity, choice, and handoff primitives |
 | Multi-step widget flow | One React shell navigates stores, menu, item customization, cart, review, and handoff views through `useAppFlow` |
+| Invocation context | `server.context` sets locale/time-zone defaults, derives an ambient service area/date, and makes the same snapshot available to tools and the reserved `noodle_context` MCP adapter |
+| Structured missing input | `plan_order` uses `ctx.elicit` to collect a fulfilment method and date in embedded/headless renderers and bidirectional MCP adapters; the stateless hosted MCP endpoint does not yet carry the server-initiated exchange |
+| Model-visible widget state | `useUpdateModelContext` publishes one cohesive replacement snapshot when supported; `useWidgetLifecycle` auto-publishes mounted/cancelled/dismissed and reports author-owned submitted milestones for future context (not host-presentation proof), while the user-triggered submit pairs `useSendFollowUpMessage` for an immediate reply |
 | Handoff | `handoff.allowedDomains` allows only `https://orders.example.com` checkout URLs |
 | Progressive enhancement | Non-Apps hosts still receive stores, featured items, and a readable fallback summary |
 

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

@@ -30,5 +30,7 @@ export const {
   useOpenExternal,
   useSendFollowUpMessage,
   useToolInfo,
+  useUpdateModelContext,
   useViewState,
+  useWidgetLifecycle,
 } = generateHelpers<AppType>();

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

@@ -174,7 +174,10 @@ type CartInput = {
 };
 
 const readOnly = annotations.readOnly();
-const action = annotations.openAction({ destructive: false });
+// These writes are app-only controls inside the cart widget. The widget already presents the
+// reviewed state and explicit button; `confirm: false` documents direct execution and is equivalent
+// to omission because action/open-world hints alone never enable the confirmation gate.
+const action = annotations.openAction({ destructive: false, confirm: false });
 
 function checkoutUrl(customer: string): string {
   return `https://orders.example.com/checkout?customer=${encodeURIComponent(customer)}`;
@@ -198,6 +201,16 @@ export default server(
     title: 'Food Ordering',
     version: '1.0.0',
     use: { state },
+    context: {
+      defaults: { locale: 'en-US', timeZone: 'America/New_York' },
+      ambient: {
+        output: z.object({ serviceArea: z.string(), orderingDate: z.string() }),
+        fulfil: ({ context }) => ({
+          serviceArea: 'Harbor District',
+          orderingDate: context.temporal.localDate,
+        }),
+      },
+    },
     state: {
       handles: {
         cart: {
@@ -239,13 +252,17 @@ export default server(
         customer: z.string(),
         stores: z.array(storeShape),
         featuredItems: z.array(menuItemShape),
+        localDate: z.string(),
+        serviceArea: z.string(),
         fallback: z.string(),
       }),
-      fulfil: ({ input }) => ({
+      fulfil: ({ input, context }) => ({
         status: 'Ready to build a food order.',
         customer: input.customer,
         stores,
         featuredItems: menu,
+        localDate: context.temporal.localDate,
+        serviceArea: context.ambient.serviceArea,
         fallback: 'Open stores: Harbor Noodles (Noodles), Garden Wraps (Vegetarian).',
       }),
       viewTitle: 'Food ordering',
@@ -363,6 +380,34 @@ export default server(
       }),
       fulfil: () => ({ stores, featuredItems: menu }),
     }),
+    tool('plan_order', {
+      description:
+        'Collect a fulfilment method and requested date as structured input, then return a reviewable order plan without placing an order.',
+      annotations: readOnly,
+      input: z.object({ customer: z.string().default('Guest') }),
+      output: z.object({
+        customer: z.string(),
+        method: z.enum(['pickup', 'delivery']),
+        requestedDate: z.string(),
+        serviceArea: z.string(),
+      }),
+      fulfil: ({ input, context, elicit }) => {
+        const preference = elicit({
+          id: 'choose_fulfilment',
+          message: 'How should we fulfil this order?',
+          input: z.object({
+            method: z.enum(['pickup', 'delivery']).describe('Fulfilment method'),
+            requestedDate: z.string().describe('Requested date').meta({ format: 'date' }),
+          }),
+        });
+        return {
+          customer: input.customer,
+          method: preference.method,
+          requestedDate: preference.requestedDate,
+          serviceArea: context.ambient.serviceArea,
+        };
+      },
+    }),
     tool('show_capabilities', {
       description: 'Return a concise summary for the standalone widget capability preview.',
       annotations: readOnly,

package/skills/claude-code/examples/food-ordering/src/views/ordering-flow.tsx

@@ -1,4 +1,4 @@
-import { useMemo, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 import {
   ActionBar,
   AppShell,
@@ -19,7 +19,9 @@ import {
   useLayout,
   useSendFollowUpMessage,
   useToolInfo,
+  useUpdateModelContext,
   useViewState,
+  useWidgetLifecycle,
   View,
   ViewStack,
 } from '../helpers.js';
@@ -90,7 +92,7 @@ function modifierLabel(value: string): string {
 }
 
 export default function OrderingFlow() {
-  const { displayMode, theme } = useLayout();
+  const { displayMode, supports, theme } = useLayout();
   const entry = structured<{
     readonly customer?: string;
     readonly stores?: readonly Store[];
@@ -106,6 +108,8 @@ export default function OrderingFlow() {
   const setView = flow.navigate;
   const handoff = useHandoff();
   const sendFollowUpMessage = useSendFollowUpMessage();
+  const updateModelContext = useUpdateModelContext();
+  const publishLifecycle = useWidgetLifecycle('ordering-flow');
   const searchStores = useCallTool('search_stores');
   const loadMenu = useCallTool('load_menu');
   const loadItem = useCallTool('load_item');
@@ -134,6 +138,7 @@ export default function OrderingFlow() {
   const setRevision = (value: number) => revisionStore.setState({ value });
   const [quantity, setQuantity] = useState(1);
   const [selectedModifiers, setSelectedModifiers] = useState<readonly string[]>([]);
+  const [lifecycle, setLifecycle] = useState<'active' | 'submitted'>('active');
 
   const storeData = structured<{ readonly stores?: readonly Store[] }>(searchStores.data);
   const menuData = structured<{
@@ -170,6 +175,37 @@ export default function OrderingFlow() {
   const llmSummary = `${view} view for ${customer}; ${cart.lines.length} cart lines; subtotal ${currency(
     cart.subtotal,
   )}`;
+  const canUpdateModelContext = supports?.modelContext === true;
+
+  useEffect(() => {
+    if (!canUpdateModelContext) return;
+    // Each call replaces model context, so publish one cohesive snapshot of current surface state.
+    void updateModelContext({
+      content: [{ type: 'text', text: `Food ordering: ${llmSummary}; ${lifecycle}.` }],
+      structuredContent: {
+        widget: { name: 'ordering-flow', lifecycle },
+        ordering: {
+          view,
+          customer,
+          cartLines: cart.lines.length,
+          subtotal: cart.subtotal,
+          selectedStoreId: selectedStoreId ?? null,
+          selectedItemId: selectedItemId ?? null,
+        },
+      },
+    });
+  }, [
+    canUpdateModelContext,
+    cart.lines.length,
+    cart.subtotal,
+    customer,
+    lifecycle,
+    llmSummary,
+    selectedItemId,
+    selectedStoreId,
+    updateModelContext,
+    view,
+  ]);
 
   async function chooseStore(store: Store) {
     setSelectedStoreId(store.id);
@@ -246,9 +282,26 @@ export default function OrderingFlow() {
       readonly revision?: number;
       readonly checkoutUrl?: string;
     }>(result);
-    setCart(prepared?.cart ?? cart);
+    const preparedCart = prepared?.cart ?? cart;
+    setCart(preparedCart);
     setRevision(prepared?.revision ?? revision + 1);
+    setLifecycle('submitted');
     setView('handoff');
+    if (canUpdateModelContext) {
+      await publishLifecycle('submitted', {
+        view: 'handoff',
+        customer,
+        cartLines: preparedCart.lines.length,
+        subtotal: preparedCart.subtotal,
+        selectedStoreId: preparedCart.selectedStoreId ?? null,
+        selectedItemId: selectedItemId ?? null,
+      });
+    }
+    if (supports?.followUpMessage) {
+      await sendFollowUpMessage({
+        prompt: 'Checkout is prepared. Confirm the cart summary and explain the final handoff.',
+      });
+    }
   }
 
   return (

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

@@ -10,6 +10,13 @@ describe('food-ordering example', () => {
     const manifest = (await app.toManifest()) as {
       server: {
         name: string;
+        context?: {
+          defaults?: { locale?: string; timeZone?: string };
+          ambient?: {
+            outputSchema?: unknown;
+            fulfilment?: { output?: unknown };
+          };
+        };
       };
       handoff?: { allowedDomains?: string[] };
       state?: { handles?: Record<string, { kind: string; scope: string }> };
@@ -17,7 +24,9 @@ describe('food-ordering example', () => {
       tools: Array<{
         name: string;
         visibility?: string[];
+        annotations?: Record<string, unknown>;
         output?: unknown;
+        fulfilment?: { steps?: unknown[]; output?: unknown };
       }>;
       widgets?: Array<{
         name: string;
@@ -27,6 +36,17 @@ describe('food-ordering example', () => {
     };
 
     expect(manifest.server.name).toBe('food_ordering');
+    expect(manifest.server.context).toMatchObject({
+      defaults: { locale: 'en-US', timeZone: 'America/New_York' },
+      ambient: {
+        fulfilment: {
+          output: {
+            serviceArea: 'Harbor District',
+            orderingDate: '${context.temporal.localDate}',
+          },
+        },
+      },
+    });
     expect(manifest.state?.handles?.cart).toMatchObject({
       kind: 'cart',
       scope: 'caller',
@@ -52,7 +72,33 @@ describe('food-ordering example', () => {
       expect(tools.get(helper)?.visibility).toEqual(['app']);
     }
     expect(JSON.stringify(tools.get('open_ordering'))).toContain('featuredItems');
+    expect(JSON.stringify(tools.get('open_ordering'))).toContain('${context.temporal.localDate}');
+    expect(JSON.stringify(tools.get('open_ordering'))).toContain('${context.ambient.serviceArea}');
     expect(JSON.stringify(tools.get('sync_cart'))).toContain('revision');
+    expect(tools.get('sync_cart')?.annotations?.confirm).toBe(false);
+    expect(tools.get('prepare_checkout')?.annotations?.confirm).toBe(false);
+    expect(tools.get('plan_order')?.fulfilment).toMatchObject({
+      steps: [
+        {
+          id: 'choose_fulfilment',
+          elicit: {
+            message: 'How should we fulfil this order?',
+            requestedSchema: {
+              type: 'object',
+              properties: {
+                method: { type: 'string', enum: ['pickup', 'delivery'] },
+                requestedDate: { type: 'string', format: 'date' },
+              },
+              required: ['method', 'requestedDate'],
+            },
+          },
+        },
+      ],
+      output: {
+        method: '${steps.choose_fulfilment.method}',
+        requestedDate: '${steps.choose_fulfilment.requestedDate}',
+      },
+    });
     expect(manifest.widgets?.map((widget) => widget.name)).toContain('capabilities_card');
   });
 });

package/skills/claude-code/references/authoring-workflow.md

@@ -7,7 +7,9 @@
 - Repair loop
 - Connectors
 - HTTP connector example (full server)
+- Delegated downstream auth (call your API as the signed-in user)
 - Design tools for the model
+- Invocation context
 - Compute connector example
 - Tests
 - Secrets and variables
@@ -37,7 +39,7 @@ Declare connectors as data, not imperative code:
 
 Tools record connector calls into a flow; recording is not execution. Do not branch on runtime outputs with native `if` — use declarative `when(...)` conditions.
 
-HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `clientCredentials`, `delegatedOAuth`, and `delegatedSessionCookie`. Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
+HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `clientCredentials`, `delegatedOAuth`, `delegatedSessionCookie`, and `delegatedTokenExchange` (per-user calls to your own API — see "Delegated downstream auth" below). Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
 
 ## HTTP connector example (full server)
 
@@ -96,7 +98,76 @@ export default server('support', { title: 'Support', version: '1.0.0', use: { cr
 
 Naming: connector operation names and tool names are lowercase-with-underscores. Map with `${args.field}` for tool/operation inputs and `${response.path}` for the response — the parsed JSON body is bound directly to `${response}`, so there is **no `.body` envelope**; use bracket syntax for array indices (`${response.data[0].id}`) — a dotted numeric index like `.0.` is invalid. Declare URL query parameters with the operation-level `query: ["arg"]` array, **not** inside `request` (which builds only the JSON body). `allowedOrigins` must be literal origin URLs (the SSRF allowlist); `baseUrl` may be a `variable(...)` that differs by env.
 
-More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `clientCredentials` | `delegatedOAuth` | `delegatedSessionCookie`. For client credentials use `{ kind: "clientCredentials", tokenUrl, clientId, clientSecret, scopes? }` (RFC-6749 grant); for a non-standard partner token endpoint add `profile: "custom"` with a `custom: { requestFormat, clientIdField, clientSecretField, tokenResponsePath, expirySource }` descriptor. Do not put credential headers in operation `headers`; use connector `auth`. For per-customer downstream calls use `delegatedOAuth` or `delegatedSessionCookie` with a matching `customerAuth` server option. Use `.compute(name, { input, output, run })` for a sandboxed transform; `provides:` (instead of `use:`) exposes a connector only to compute `callOperation`; and `noodle import openapi <file>` generates a connector from an OpenAPI spec.
+More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `clientCredentials` | `delegatedOAuth` | `delegatedSessionCookie` | `delegatedTokenExchange`. For client credentials use `{ kind: "clientCredentials", tokenUrl, clientId, clientSecret, scopes? }` (RFC-6749 grant); for a non-standard partner token endpoint add `profile: "custom"` with a `custom: { requestFormat, clientIdField, clientSecretField, tokenResponsePath, expirySource }` descriptor. Do not put credential headers in operation `headers`; use connector `auth`. Use `.compute(name, { input, output, run })` for a sandboxed transform; `provides:` (instead of `use:`) exposes a connector only to compute `callOperation`; and `noodle import openapi <file>` generates a connector from an OpenAPI spec.
+
+## Delegated downstream auth (call your API as the signed-in user)
+
+Use delegated connector auth when the downstream API must enforce its own per-user authorization — a shared service credential plus a forwarded user id would bypass it. Three shapes exist; pick by who owns the downstream:
+
+- **`delegatedTokenExchange`** — your own API. The platform signs a short-lived, verifiable assertion of the signed-in user and exchanges it at a token endpoint you implement (RFC 8693). Works with `customerAuth.bridge(...)` identities and embedded-assistant sessions; no per-user OAuth enrollment.
+- **`delegatedOAuth` with `provider: "firebase" | "microsoft"`** — Noodle-managed bridge providers using stored per-user refresh tokens. Requires the matching `customerAuth` bridge; any other provider string is the compile error `unsupported_delegated_provider`.
+- **`delegatedSessionCookie`** — Firebase-managed session-cookie apps only; not a generic mechanism.
+
+### The connector (your `server.ts`)
+
+```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'],           // optional
+  audience: 'example-api',        // optional; assertion + request audience, defaults to tokenUrl
+  authMethod: 'client_secret_basic', // default; client_secret_post supported
+}
+```
+
+Inside tools, `${user.subject}` / `${user.email}` / `${user.name}` / `${user.locale}` / `${user.timeZone}` / `${user.claims.*}` stay available as verified context; the delegated credential is what makes the *downstream call itself* run as that user.
+
+### The exchange request your endpoint receives
+
+The broker POSTs `application/x-www-form-urlencoded` to `tokenUrl` with `Authorization: Basic base64(clientId:clientSecret)` (or `client_id`/`client_secret` form fields for `client_secret_post`):
+
+```
+grant_type=urn:ietf:params:oauth:grant-type:token-exchange
+subject_token=<RS256 JWT signed by the platform>
+subject_token_type=urn:ietf:params:oauth:token-type:jwt
+scope=time_off            (space-joined, when configured)
+audience=example-api      (when configured)
+```
+
+The `subject_token` claims: `iss` (platform issuer; JWKS at `{iss}/.well-known/jwks.json`), `sub` (verified user id), `aud` (your configured audience or the tokenUrl), `email`, `name`, `claims` (declared session claims), `tenant` (`org/app/env`), `deployment`, `iat`, `exp` (about 120 s), `jti`. Respond with `{ "access_token": "...", "token_type": "Bearer", "expires_in": 900 }`; the broker caches per user + connector + scopes until `expires_in` minus 300 s and presents the token downstream as `Authorization: Bearer`.
+
+### The downstream token endpoint (your backend)
+
+```ts
+// POST /api/assistant/oauth/token — Node example with jose.
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+
+const PLATFORM_ISSUER = process.env.NOODLE_PLATFORM_ISSUER!; // e.g. https://cloud.noodleseed.dev
+const jwks = createRemoteJWKSet(new URL(`${PLATFORM_ISSUER}/.well-known/jwks.json`));
+
+export async function tokenEndpoint(req: Request): Promise<Response> {
+  // 1. Authenticate the broker client credential (client_secret_basic).
+  const basic = req.headers.get('authorization') ?? '';
+  const [clientId, clientSecret] = atob(basic.replace(/^Basic /, '')).split(':');
+  if (!isValidClient(clientId, clientSecret)) return new Response(null, { status: 401 });
+  // 2. Verify the platform-signed user assertion (never trust a plaintext user id).
+  const form = new URLSearchParams(await req.text());
+  const { payload } = await jwtVerify(form.get('subject_token') ?? '', jwks, {
+    issuer: PLATFORM_ISSUER,
+    audience: 'https://app.example.com/api/assistant/oauth/token', // your tokenUrl or configured audience
+  });
+  if (payload.deployment !== undefined && payload.tenant !== 'your-org/your-app/prod') {
+    return new Response(null, { status: 403 }); // optionally pin the calling deployment
+  }
+  // 3. Mint your own short-lived user-scoped token; your API enforces per-user rules from it.
+  const accessToken = await issueAccessToken(String(payload.sub), clientId, form.get('scope') ?? '');
+  return Response.json({ access_token: accessToken, token_type: "Bearer", expires_in: 900 });
+}
+```
+
+Diagnose with `noodle auth doctor` (reports each delegated token exchange endpoint and whether managed delegated providers pair with the declared `customerAuth`). Common failures: `disallowed_token_origin` (add the tokenUrl origin to `allowedOrigins`), `unsupported_delegated_provider` (custom provider strings never reach a broker; use `delegatedTokenExchange`), and `delegated token exchange requires a verified customer caller` at runtime (the surface calling the tool has no verified customer identity — check `customerAuth` and, for embeds, `createAssistantSession({ user })`).
 
 ## Design tools for the model
 
@@ -160,6 +231,50 @@ export default server('todo', { title: 'Tasks', version: '1.0.0', use: { tasks }
 
 The model never sees a task id from the user; `find_tasks` returns `{ id, title }` summaries it can pick from, then `complete_task` acts by id. Keep write actions (`complete_task`) separate and explicitly described so the host can gate them.
 
+## Invocation context
+
+Every executable invocation receives one immutable server-authoritative temporal snapshot. Canonical TypeScript `server()` authoring emits an empty context declaration even when you omit the option, so MCP clients get the reserved read-only `noodle_context` temporal tool with zero setup. Use `server(..., { context })` only to add locale/time-zone defaults and trusted ambient facts that every surface should resolve the same way. Tools, resources, prompts, and the embedded assistant consume the same snapshot; do not create a host-specific date tool.
+
+```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 };
+    },
+  },
+},
+```
+
+Ambient providers are recorded as fulfilment data at author time, may call read-only connector operations only, and have a declared output schema. Later fulfilments read `${context.temporal.localDate}`, `${context.temporal.timeZone}`, `${context.ambient.defaultTeamId}`, and `${context.ambientStatus}`. If ambient resolution fails, the status is `unavailable`; never invent the missing business facts. TypeScript-authored servers always reserve `noodle_context`; only a raw Core-v1 manifest that omits `server.context` retains that tool name. Ambient/model-visible context is capped at 16 KiB serialized JSON, depth 8, and 128 entries per container; credential-shaped keys are rejected.
+
+## Ask for structured missing input
+
+Use `ctx.elicit` inside a tool fulfilment when execution needs one bounded value from the user. The call records an `elicit` flow step and returns its symbolic scope; it does not prompt at author time:
+
+```ts
+tool('prepare_time_off', {
+  description: 'Resolve a time-off request before proposing the write.',
+  input: z.object({ start: z.string(), end: z.string() }),
+  output: z.object({ start: z.string(), end: z.string(), teamId: z.string() }),
+  fulfil: ({ input, elicit }) => {
+    const answer = elicit({
+      id: 'choose_team',
+      message: 'Which team should receive this request?',
+      input: z.object({ teamId: z.string().describe('Team') }),
+    });
+    return { start: input.start, end: input.end, teamId: answer.teamId };
+  },
+});
+```
+
+Use a stable lowercase/number/underscore id and a flat form of string/number/integer/boolean, string choices or multi-select, with optional `email`, `uri`, `date`, or `date-time` formats. Nested objects and credential-shaped fields fail with `invalid_elicitation_schema`. Every interactive flow must place all `ctx.elicit` calls before its first connector operation or compilation fails with `invalid_elicitation_flow`. Embedded/headless clients receive `input_requested`; bidirectional MCP transports map the primitive to standard form `elicitation/create`. An adapter that cannot carry the request fails before executing the tool. Accept validates and resumes without rerunning completed steps; invalid assistant content returns `arg_invalid` with the same interaction still pending for correction; decline/cancel stop. Elicitation gathers missing input and does not replace confirmation for a subsequent write. In a flow marked `confirm: true`, every eligible `input_requested` precedes `tool_proposed`; the final proposal reviews original tool input, elicited values, and the sole exact connector version/operation/resolved arguments. Accept is bound to that action and only then may execution start. A confirmable flow may contain at most one connector operation or compilation fails with `invalid_confirmation_flow`. MCP uses a final standard form-elicitation confirmation on capable bidirectional transports and fails closed otherwise. At the manifest/runtime boundary and in TypeScript action helpers, omitted or `false` executes directly; action, destructive, and open-world hints alone never gate execution. `annotations.action({ confirm: false })` is equivalent to omission, while `annotations.action({ confirm: true })` explicitly enables confirmation.
+
 ## Compute connector example
 
 ```ts

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

@@ -17,8 +17,9 @@ Run `noodle validate` (add `--json` for the machine-readable envelope, `--fix-pr
 | `invalid_shape` | A field has the wrong type or structure; match the shape the compiler reports under `path` against the SDK builder you used. |
 | `invalid_name` | Rename the identifier to match the allowed pattern (lowercase, no spaces/reserved characters) cited at `path`. |
 | `duplicate_name` | Two tools/components share a name; give each a unique name at the cited `path`. |
+| `reserved_name` | Rename the tool at `path`; TypeScript `server()` always reserves `noodle_context`, while raw manifests reserve it when `server.context` is present. |
 | `unsupported_manifest_version` | Update the SDK/CLI so the emitted manifest version is supported; do not pin an old manifest shape. |
-| `reserved_for_future_version` | The verb at `path` (e.g. `compute`, `elicit`) is reserved for a future core version; express the step with `use` (a connector operation) or `map` (a pure mapping) instead. |
+| `reserved_for_future_version` | The verb at `path` (currently `compute` as a flow step) is reserved for a future core version; express the step with `use` (a connector operation), `map` (a pure mapping), or the shipped `ctx.elicit` input primitive instead. |
 | `invalid_operation_ref` | Fix the connector operation reference to `alias.operation` for an operation that exists on that connector. |
 | `external_ref` | Remove the external/remote `$ref`; schemas must be self-contained — inline the definition instead of dereferencing a URL. |
 | `invalid_schema_ref` | Correct the `$use` schema reference syntax at `path`; it does not name a resolvable local schema. |
@@ -34,7 +35,11 @@ Run `noodle validate` (add `--json` for the machine-readable envelope, `--fix-pr
 | `self_step_ref` | A step references its own output; remove the self-reference. |
 | `duplicate_step_id` | Two recorded steps share an id; the recorder derives ids from calls — restructure so each connector call is distinct. |
 | `invalid_fulfilment` | The `fulfil` function records something the compiler cannot model (e.g. branching on a runtime value); record a linear sequence of connector calls and use declarative conditions. |
+| `invalid_elicitation_schema` | Make the requested input a flat object of supported string/number/boolean/enum fields with no credential-shaped keys, and keep `required` names aligned with declared properties. |
+| `invalid_elicitation_flow` | Move every `ctx.elicit` before the first connector operation in the flow, so suspension cannot strand an already-applied side effect. |
+| `invalid_confirmation_flow` | Limit a tool marked `confirm: true` to one connector operation, or split the workflow so its complete resolved action can be reviewed and bound. |
 | `arg_type_mismatch` | A connector call argument has the wrong type; match the operation input type shown under `expected`/`got`. |
+| `ambient_context_action` | Replace the ambient provider call at `path` with a read-only connector operation; per-invocation context resolution must not cause side effects. |
 | `duplicate_resource` | Two resources share an identity; give each `resource(...)` a unique name. |
 | `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. |