@noodleseed/agent-kit 0.22.0 → 0.23.1

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

@@ -9,6 +9,7 @@
 - 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
@@ -121,7 +122,7 @@ auth: {
 }
 ```
 
-Inside tools, `${user.id}` / `${user.email}` / `${user.name}` / `${user.claims.*}` stay available as verified context; the delegated credential is what makes the *downstream call itself* run as that user.
+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
 
@@ -230,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/cli-commands.md

@@ -86,6 +86,7 @@ Every `noodle` command, grouped by area. Local authoring commands (`validate`, `
 | Command | What it does |
 | :-- | :-- |
 | `noodle audit` | Operator governance audit status and event queries. |
+| `noodle billing` | Super-admin preview of the explicit legacy billing-account migration without writing data (`billing migration preview`). |
 | `noodle logs` | View service/deployment logs. |
 | `noodle metrics` | MCP analytics for a deployed server (volume, sessions, latency percentiles, two-tier errors, tools, clients). Agents: `noodle metrics --agent-output` for a health verdict + next actions. |
 | `noodle events` | The per-request MCP event stream with status/tool/client filters; `--session <id>` replays one session in order. Agents: add `--json` and filter (`--status tool_error\|mcp_error`) when debugging. |

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. |

package/skills/claude-code/references/deploy-and-ops.md

@@ -59,6 +59,10 @@ Once deployed, register the server as a tool in a host with `noodle connect <hos
 
 Manage runtime config with `noodle secrets` / `noodle variables` (scoped org/app/env). Operators use `noodle logs`, `noodle audit`, and `noodle policy` for logs, governance audit, and policy.
 
+## Billing migration preview
+
+`noodle billing migration preview [--file <mapping.json>]` is a super-admin, read-only inventory and validation command for legacy organizations. It never creates billing accounts, links organizations, or changes entitlements, and there is no apply command. Keep real mapping files outside the repository. The versioned file must classify production apps for every organization: `linkState: "unlinked"` selects a current owner subject under the fixed hosted issuer `https://accounts.google.com`, while `linkState: "linked"` asserts the exact current billing-account ID and link version. Inventory apps with `noodle apps list --archived --json` so archive state is visible. A blocked preview exits 1 even though the JSON response is a successful preview envelope; inspect `data.preview.blockers` and resolve every blocker before a future cutover workflow exists.
+
 ## Agent-safe CLI recipes
 
 Use explicit flags in headless runs so commands never wait for a prompt:
@@ -74,6 +78,7 @@ noodle validate --json
 noodle test --json
 noodle deploy --json
 noodle smoke --json
+noodle billing migration preview --json
 noodle agents doctor --json
 ```
 

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,17 +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:
 
@@ -176,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
@@ -203,10 +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` |
+| 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/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.22.0
+version: 0.23.1
 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/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/codex/examples/food-ordering/src/helpers.ts

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

package/skills/codex/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,