@noodleseed/agent-kit 0.21.0 → 0.21.1

package/manifest.json

@@ -1,9 +1,9 @@
 {
-  "packageVersion": "0.21.0",
+  "packageVersion": "0.21.1",
   "files": [
     {
       "path": "skills/codex/SKILL.md",
-      "sha256": "09469929851e57fae24fc411a173d0e356aabacb3743beed81232d03e2cc44dd",
+      "sha256": "4a48b0a357c2dfab02ff191d68a9ebb47ad8396a63f476a0f60ba69cc7b943ad",
       "agentTarget": "codex"
     },
     {
@@ -33,7 +33,7 @@
     },
     {
       "path": "skills/codex/references/embedded-assistant.md",
-      "sha256": "db1eec6f6eed10b6525efc721b22756ff769b0234358821c15deb45cd61b39fb",
+      "sha256": "687666010deb32bb605ccc23aeac8778fd1d02c53d7d8e232b6d0b8aeef77668",
       "agentTarget": "codex"
     },
     {
@@ -318,7 +318,7 @@
     },
     {
       "path": "skills/codex/examples/hello/src/server.ts",
-      "sha256": "f5ac538d951adc4f18b2c14205f4f710e7920da2ea911444d52adeab8f801521",
+      "sha256": "5b7dd35428128cfe0f506054e80b060d8a87ef157b03d2ce94d304b14df6e521",
       "agentTarget": "codex"
     },
     {
@@ -353,7 +353,7 @@
     },
     {
       "path": "skills/claude-code/SKILL.md",
-      "sha256": "e31b696b0bcf72de525e0c28ceba8c4d44bd2ce5c6522476a0c33ffc8cb6d677",
+      "sha256": "23754f0386b77f112249ca8b948b479792895303f0257ab0961cbbb81a857693",
       "agentTarget": "claude-code"
     },
     {
@@ -383,7 +383,7 @@
     },
     {
       "path": "skills/claude-code/references/embedded-assistant.md",
-      "sha256": "db1eec6f6eed10b6525efc721b22756ff769b0234358821c15deb45cd61b39fb",
+      "sha256": "687666010deb32bb605ccc23aeac8778fd1d02c53d7d8e232b6d0b8aeef77668",
       "agentTarget": "claude-code"
     },
     {
@@ -668,7 +668,7 @@
     },
     {
       "path": "skills/claude-code/examples/hello/src/server.ts",
-      "sha256": "f5ac538d951adc4f18b2c14205f4f710e7920da2ea911444d52adeab8f801521",
+      "sha256": "5b7dd35428128cfe0f506054e80b060d8a87ef157b03d2ce94d304b14df6e521",
       "agentTarget": "claude-code"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noodleseed/agent-kit",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "private": false,
   "description": "Self-checking, self-updating agent skills for the Noodle Seed CLI. Authored in this repo by @noodle-borg/agent-kit; this is the published, independently-versioned canonical skills artifact the CLI fetches and verifies.",
   "license": "Apache-2.0",

package/skills/claude-code/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.0
+version: 0.21.1
 hash: b4fc528d406e2149
 ---
 

package/skills/claude-code/examples/hello/src/server.ts

@@ -1,4 +1,4 @@
-import { server, tool, z } from '@noodleseed/one';
+import { annotations, server, tool, z } from '@noodleseed/one';
 
 export default server(
   'hello',
@@ -22,6 +22,8 @@ export default server(
       output: z.object({
         message: z.string(),
       }),
+      // Read-only, closed-world: assistant surfaces run this without a consent prompt.
+      annotations: annotations.readOnly(),
       fulfil: ({ input }) => {
         return { message: `Hello, ${input.name}!` };
       },

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

@@ -8,6 +8,7 @@
 - Access modes and customer auth
 - Create the backend client
 - Integrate the customer backend
+- Verified session context (identity and claims)
 - The session response
 - Mount the browser component
 - Toolchain requirements
@@ -113,6 +114,48 @@ 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.
 
+## Verified session context (identity and claims)
+
+The embedding developer defines what authenticated session context the assistant receives. One mechanism, three hops:
+
+1. The authenticated backend passes standard identity and any verified claims at session exchange (flat scalars only):
+
+```ts
+const session = await createAssistantSession({
+  serviceUrl, clientId, clientSecret, origin,
+  user: { id: user.id, email: user.email, name: user.name },
+  claims: { displayName: user.name, accountTier: account.tier, region: account.region },
+});
+```
+
+2. The server author declares the allowlist in `server.ts` — undeclared claims are dropped at session exchange (never rejected, so backend and server deploys may skew safely):
+
+```ts
+assistant: embeddedAssistant({
+  model, allowedOrigins,
+  sessionClaims: {
+    displayName: { exposeToModel: true },
+    accountTier: { exposeToModel: true },
+    region: {}, // tools only, never in the prompt
+  },
+}),
+```
+
+3. Consumption. Tools read the verified identity and declared claims through the `user` scope:
+
+```ts
+tool("greet", {
+  description: "Greet the signed-in user.",
+  input: z.object({}),
+  annotations: annotations.readOnly(),
+  fulfil: ({ user }) => ({ message: `Hello, ${user.name}!`, tier: user.claims.accountTier }),
+});
+```
+
+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.
+
+Page `context` from the widget remains untrusted hint data; verified facts belong in `claims`, never in `context`.
+
 ## 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.
@@ -142,7 +185,7 @@ The component renders a custom element and must mount client-side. In a Next.js
 - 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.
-- Read-only closed-world tools may auto-run; writes require confirmation.
+- 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.
 - Wrong-origin and malformed-origin requests fail closed.
 
@@ -157,4 +200,9 @@ The component renders a custom element and must mount client-side. In a Next.js
 | Validate rejects an origin | Non-loopback HTTP origin in `allowedOrigins` | Use the exact HTTPS production origin; HTTP is only for `localhost`/`127.0.0.1` |
 | 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`) |
+| 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 |
+| `${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 |

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.0
+version: 0.21.1
 hash: cd25535e1d6dbf4f
 ---
 

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

@@ -1,4 +1,4 @@
-import { server, tool, z } from '@noodleseed/one';
+import { annotations, server, tool, z } from '@noodleseed/one';
 
 export default server(
   'hello',
@@ -22,6 +22,8 @@ export default server(
       output: z.object({
         message: z.string(),
       }),
+      // Read-only, closed-world: assistant surfaces run this without a consent prompt.
+      annotations: annotations.readOnly(),
       fulfil: ({ input }) => {
         return { message: `Hello, ${input.name}!` };
       },

package/skills/codex/references/embedded-assistant.md

@@ -8,6 +8,7 @@
 - Access modes and customer auth
 - Create the backend client
 - Integrate the customer backend
+- Verified session context (identity and claims)
 - The session response
 - Mount the browser component
 - Toolchain requirements
@@ -113,6 +114,48 @@ 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.
 
+## Verified session context (identity and claims)
+
+The embedding developer defines what authenticated session context the assistant receives. One mechanism, three hops:
+
+1. The authenticated backend passes standard identity and any verified claims at session exchange (flat scalars only):
+
+```ts
+const session = await createAssistantSession({
+  serviceUrl, clientId, clientSecret, origin,
+  user: { id: user.id, email: user.email, name: user.name },
+  claims: { displayName: user.name, accountTier: account.tier, region: account.region },
+});
+```
+
+2. The server author declares the allowlist in `server.ts` — undeclared claims are dropped at session exchange (never rejected, so backend and server deploys may skew safely):
+
+```ts
+assistant: embeddedAssistant({
+  model, allowedOrigins,
+  sessionClaims: {
+    displayName: { exposeToModel: true },
+    accountTier: { exposeToModel: true },
+    region: {}, // tools only, never in the prompt
+  },
+}),
+```
+
+3. Consumption. Tools read the verified identity and declared claims through the `user` scope:
+
+```ts
+tool("greet", {
+  description: "Greet the signed-in user.",
+  input: z.object({}),
+  annotations: annotations.readOnly(),
+  fulfil: ({ user }) => ({ message: `Hello, ${user.name}!`, tier: user.claims.accountTier }),
+});
+```
+
+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.
+
+Page `context` from the widget remains untrusted hint data; verified facts belong in `claims`, never in `context`.
+
 ## 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.
@@ -142,7 +185,7 @@ The component renders a custom element and must mount client-side. In a Next.js
 - 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.
-- Read-only closed-world tools may auto-run; writes require confirmation.
+- 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.
 - Wrong-origin and malformed-origin requests fail closed.
 
@@ -157,4 +200,9 @@ The component renders a custom element and must mount client-side. In a Next.js
 | Validate rejects an origin | Non-loopback HTTP origin in `allowedOrigins` | Use the exact HTTPS production origin; HTTP is only for `localhost`/`127.0.0.1` |
 | 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`) |
+| 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 |
+| `${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 |