@lenne.tech/nest-server 12.1.1 → 12.3.0

package/src/core/modules/ai/INTEGRATION-CHECKLIST.md

@@ -146,9 +146,10 @@ ai: {
 }
 ```
 
-- **Plan mode / pre-flight permissions:** give data-mutating tools an `authorize()` that
-  checks permission WITHOUT mutating (e.g. load the record + verify ownership). Plan mode
-  runs it for every step before executing anything.
+- **Data-level permissions:** give data-mutating tools an `authorize()` that checks
+  permission WITHOUT mutating (e.g. load the record + verify ownership). It runs before every
+  execution — auto mode, plan mode (for every step before anything runs) and MCP (12.3.0+);
+  return `data` to hand the loaded record to `execute()` (`context.authorization.data`).
 - **Confirmation:** mark create/update/delete tools `mutating: true` and irreversible ones
   `destructive: true`.
 - **Self-optimizing prompts:** the system prompt is built from editable, keyed slots —
@@ -174,8 +175,9 @@ ai: {
   `deferToolSummaryChars` (~200–400) ALONGSIDE it — otherwise the descriptions alone
   re-inflate the prompt you just shrank. Both are scoped to the **emulated tool protocol**:
   in auto mode a connection with `supportsNativeTools: true` gets every full description and
-  schema in the native `tools` payload regardless, so truncation and the banner are skipped
-  there. **Plan mode always uses the emulated protocol**, so a native connection IS truncated
+  schema in the native `tools` payload regardless, and its prompt catalog lists names only
+  (12.3.0+, `ai.nativeToolCatalog: 'full'` restores it), so truncation and the banner are
+  skipped there. **Plan mode always uses the emulated protocol**, so a native connection IS truncated
   there — and since plan mode plans in one call without executing, it cannot follow the
   `search_tools` hint. Keep the cap generous if you use plan mode.
   The truncated tail is typically where a tool's preconditions and role limits are written;
@@ -183,10 +185,16 @@ ai: {
   stays with the registry's role filter, the execution-time re-check, and the
   `mutating`/`destructive` flags behind the confirmation gate, none of which read the
   description.
-- **Where data-level checks belong:** `authorize()` runs in **plan mode only**. In auto mode
-  (the default) and over MCP, the orchestrator calls `execute()` directly. Put ownership and
-  tenant checks INSIDE `execute()` (via `CrudService` + `context.serviceOptions`) — a check
-  that lives only in `authorize()` will not run for most callers.
+- **Guarding the prompt size in a test?** Measure against `ai.contextWindow`, the fallback for
+  connections without a window of their own, and name the test that way: it guards the worst
+  case, not the window a pinned or detected connection has. Raising its limit removes the guard;
+  shrink the catalog instead. At runtime the framework warns once per connection when the system
+  prompt and tool definitions take more than half of the real input budget.
+- **Where data-level checks belong:** `authorize()` decides whether a call may be tried;
+  `execute()` still routes every read and write through `CrudService` +
+  `context.serviceOptions`, so `@Restricted`, `securityCheck()` and tenant scoping apply.
+  Until 12.2 `authorize()` ran in plan mode only — a project that moved its checks into
+  `execute()` for that reason keeps working unchanged.
 
 ### MCP server (only when `ai.mcp.enabled` or `ai.mcp` is truthy)
 
@@ -200,10 +208,14 @@ A **503 Service Unavailable** from `/ai/mcp` therefore means the module could no
 _resolved_, not that it is missing — check the server log for the underlying error.
 The response body carries the stable `#LTNS_0901` code, never the raw error.
 
-> **No confirmation gate over MCP.** `mcpCallTool` does not consult the
-> `mutating`/`destructive` flags, and `authorize()` does not run there either. A
-> destructive tool invoked through `/ai/mcp` executes immediately. Only expose MCP to
-> clients you trust, and put every permission check inside `execute()`.
+> **Confirmation over MCP (12.3.0+).** `tools/call` applies the admin's tool policies and
+> `authorize()`, and asks the user through MCP elicitation before a `destructive` tool (or a
+> `mutating` one under `ai.confirmation.mutating`) runs. A client without elicitation gets an
+> error result. Each user may switch the question off (and on) for themselves via
+> `PUT /ai/settings` / `updateAiSettings`; `ai.mcp.confirmation` sets the default
+> (`false` = off) and `{ enforced: true }` takes the switch away. **Check your MCP clients**
+> and offer users the switch in your UI (`GET /ai/settings` says whether it is enforced).
+> See the module README, "Authorization and confirmation over MCP".
 
 ### MCP OAuth 2.1 (only when `ai.mcp.oauth` is enabled)
 
@@ -229,9 +241,15 @@ Put `{returnTo}` into it only if that login page can send the user back to the A
 (the nuxt-base-starter login accepts same-origin targets only, so leave it out there).
 
 **Optional — your own consent UI:** a subclass of `CoreAiMcpOAuthService` overriding
-`renderConsentPage(view)` (restyle) or `authorizeConsent(client, params, res)` (replace), registered via
+`renderConsentPage(view)` (restyle — `renderMcpOAuthConsentPage(view, { texts, styles })` changes wording and
+CSS without copying markup, scripts or headers; fill both from code or configuration only) or
+`authorizeConsent(client, params, res)` (replace), registered via
 `CoreModule.forRoot(envConfig, { ai: { mcpOAuthService: McpOAuthService } })`.
 
+**Optional — no sticky sessions:** `ai: { mcp: { stateless: true } }` serves `/ai/mcp` without sessions, so any
+replica answers any request. Without a session the server cannot ask the user (no MCP elicitation): tools that
+need confirmation are refused there unless the user or `ai.mcp.confirmation` switched the question off.
+
 **WHY a POST, never "signed in, so issue":** anybody can register a client with their own redirect
 URI and start the flow — PKCE is then theirs too. A GET to `/authorize` is what any link produces,
 and it carries the session cookie, so issuing on GET hands a code for whoever clicks to the
@@ -242,7 +260,10 @@ with a CSRF token.
 **WHY refuse with `this.loadOAuthErrors()`:** the SDK maps an error to its OAuth code only when it
 is one of its own `OAuthError` classes, and turns anything else into `server_error`. A user who
 declines consent should send the client back with `access_denied` (`AccessDeniedError`), not with
-a server error.
+a server error. Check the CSRF token on Deny as on Allow (12.3.0): the refusal redirects the browser to
+the client's registered URI, so an unprotected Deny lets a cross-site POST send a signed-in user there.
+An error before your method runs (a malformed request) is answered with 400 by the framework and never
+redirected.
 
 ## Verification Checklist
 

package/src/core/modules/ai/README.md

@@ -396,6 +396,16 @@ factory.registerBuilder('my-provider', (conn) => new MyProvider(conn));
   `conversationId` to `aiPrompt` to load prior turns and append the new ones.
   Manage via `createAiConversation` / `findAiConversations` / `getAiConversation`
   / `deleteAiConversation`.
+  A prompt only continues the caller's OWN conversation, on REST, the stream and
+  GraphQL alike. An id the caller did not create — another user's, or one that does
+  not exist — counts as no conversation: the run reads no history, writes nothing,
+  uses no conversation-scoped tool grants, and its response carries no
+  `conversationId` (12.3.0; before, the turns were written into the other user's
+  conversation). Admins are no exception here: they may READ every conversation
+  (`getAiConversation`, `findAiConversations` with `all`), never continue one.
+  `CoreAiConversationService.appendMessage(id, message, ownerId)` checks the owner
+  itself and writes nothing for anyone else; a project that calls it directly passes
+  the id of the user the turn belongs to.
 - **Audit** (`ai.audit: true`): every run is persisted to `aiInteractions`
   (admin-readable via `findAiInteractions` / `getAiInteraction`).
 - **Streaming**: `POST /ai/stream` returns Server-Sent Events (`action`, `token`,
@@ -418,26 +428,32 @@ export class TransferFundsTool extends AiTool {
   readonly mutating = true; // governed by the confirmation policy
   readonly destructive = true; // always requires confirmation
 
-  // PLAN-MODE pre-flight, without mutating: lets the whole plan be rejected before
-  // any step runs. It does NOT run in auto mode or over MCP — so it must never be
-  // the only place a permission is checked.
+  // Runs before EVERY execution (12.3.0+): auto mode, plan mode (for the whole plan
+  // before any step runs, and again per step) and MCP — on the arguments that will
+  // run, after the PreToolUse hooks. Never mutates. A throw counts as a refusal.
   async authorize(args, context) {
     const account = await this.accountService.get(args.fromId, context.serviceOptions).catch(() => null);
-    return { allowed: !!account, reason: account ? undefined : 'No access to source account' };
+    return account
+      ? { allowed: true, data: account } // reaches execute() as context.authorization.data
+      : { allowed: false, reason: 'No access to source account' };
   }
 
   async execute(args, context) {
-    // The REAL gate, on every path: route through the service with the caller's
-    // serviceOptions so `@Restricted`, `securityCheck()` and tenant scoping apply.
-    // Do not rely on authorize() having run.
-    const account = await this.accountService.getForUser(args.fromId, context.serviceOptions);
+    // Still route the write through the service with the caller's serviceOptions, so
+    // `@Restricted`, `securityCheck()` and tenant scoping apply: authorize() decides
+    // whether to try, the service decides what the user may change.
+    const account =
+      context.authorization?.data ?? (await this.accountService.getForUser(args.fromId, context.serviceOptions));
     return this.accountService.transfer(account, args.toId, args.amount, context.serviceOptions);
   }
 }
 ```
 
-> **Do not put a permission check only in `authorize()`.** It runs in plan mode
-> only — auto mode (the default) and MCP go straight to `execute()`.
+> **`authorize()` runs on every path since 12.3.0.** Until 12.2 it ran in plan mode
+> only — auto mode (the default) and MCP went straight to `execute()`. A refusal skips
+> the call: the model receives `TOOL_NOT_AVAILABLE` with the `reason` (keep it free of
+> anything the user may not know), an MCP client an error result. The refusal is not
+> recorded as a learning signal.
 
 ## Confirmation for changes
 
@@ -447,6 +463,8 @@ export class TransferFundsTool extends AiTool {
   admin set `enforced: true`.
 - When confirmation is needed the response has `requiresConfirmation: true` +
   `pendingActions`; re-send the prompt with `confirm: true` to proceed.
+- Over MCP the same flags apply through MCP elicitation (12.3.0+) — see
+  [Authorization and confirmation over MCP](#authorization-and-confirmation-over-mcp-1230).
 
 ## Client metadata & prompt enrichment
 
@@ -455,6 +473,16 @@ export class TransferFundsTool extends AiTool {
 - The system prompt is enriched with the user's roles + available tools and optional
   `ai.documentation` (override `CoreAiPromptBuilderService.getDocumentation()` for RAG).
 
+**What bounds the size.** `input.context` and `input.metadata` are capped at 4000 characters
+each for the prompt — that cap protects the context window, not the CPU. The work is bounded
+earlier, by the body parser: a request over `bodyParser.json.limit` (100 kB unless configured)
+is refused with 413 before it is parsed. A project that raises the limit for `dataUrl`
+attachments should raise it only as far as its images need; serializing a client block for the
+cap then costs about half of what parsing the same body already did (measured 2026-11-03:
+2 MB → ~10 ms parse, ~5 ms serialize). The same holds for tool results: `ai.maxToolResultChars`
+keeps them out of the context window, while a tool's own query decides how much data it loads —
+page large result sets in the tool rather than relying on the cap.
+
 ## Self-optimizing prompts (editable templates + governed learning)
 
 The system prompt is assembled from **keyed fragments** by `CoreAiPromptBuilderService`,
@@ -506,8 +534,8 @@ so it can recover within the run.
 > **Security:** learned hints and template overrides only ever **add textual guidance** —
 > they can never relax the permission model. Tool role-filtering,
 > `CrudService`/`@Restricted` and `secretFields` are enforced backend-side regardless of
-> the prompt. (`authorize()` is _not_ part of that unconditional set — it runs in plan
-> mode only; see [Deferred tool schemas](#deferred-tool-schemas-large-registries) below.)
+> the prompt. Since 12.3.0 a tool's `authorize()` belongs to that set too: it runs before
+> every execution, in every mode and over MCP.
 
 ```typescript
 ai: {
@@ -533,6 +561,37 @@ When a user's session history would overflow, the **oldest non-system turns are
 `ai.maxToolResultChars` (default `12000`) — so long-running conversations never exceed the
 model's limit.
 
+**Native tool definitions count against the budget** (12.3.0+): a connection with
+`supportsNativeTools: true` carries every description and schema in the `tools` payload, beside
+the messages, and that payload occupies the same window. **A crowded window is reported**: when
+the system prompt and the tool definitions take more than half of the input budget, the
+framework warns once per connection and process, naming the connection, the numbers and whether
+the window is the connection's own or the `ai.contextWindow` fallback. Before, the only trace was
+a debug line, and the visible symptom was an assistant that answered generically because the
+user's message had been cut.
+
+**Guarding the prompt size in a project test:** measure against `ai.contextWindow` (the
+fallback) and say so in the test — it guards the connections without a window of their own,
+the worst case, not the window a pinned or detected connection has. Raising its limit removes
+that guard; shrink the catalog instead (`deferToolSchemas`, `deferToolSummaryChars`, fewer
+tools per role).
+
+## Tool catalog for native connections (12.3.0+)
+
+A connection with native tool calling receives every tool's description and parameter schema
+in the `tools` payload. Its system-prompt catalog therefore lists **names only** — repeating
+the descriptions (and, without `deferToolSchemas`, the schemas) paid for every tool twice.
+Emulated connections and plan mode keep the full catalog: there it is the model's only source.
+
+```typescript
+ai: {
+  nativeToolCatalog: 'full', // restores descriptions (and schemas) in the native catalog; default 'names'
+}
+```
+
+Use `'full'` only for a model that demonstrably picks tools better with the descriptions in the
+prompt; the cost is the duplicated text on every call.
+
 ## Deferred tool schemas (large registries)
 
 The system prompt normally carries every tool's full JSON parameter schema. With a large
@@ -558,9 +617,10 @@ context, set `deferToolSummaryChars` alongside it (roughly 200–400 works well)
 
 > **Scoped to the emulated tool protocol, not to the provider.** In auto mode a connection
 > with `supportsNativeTools: true` receives every full description and JSON schema through
-> the native `tools` payload anyway, so truncation is skipped there and no `search_tools`
-> banner is emitted — telling the model a description was cut while handing it the full text
-> in the same request would only buy a wasted round-trip against `maxIterations`.
+> the native `tools` payload anyway, and its catalog lists names only (see above), so
+> `deferToolSummaryChars` has no effect there and no `search_tools` banner is emitted —
+> telling the model a description was cut while handing it the full text in the same request
+> would only buy a wasted round-trip against `maxIterations`.
 >
 > **Plan mode always uses the emulated protocol**, so a native connection IS truncated there.
 > Because plan mode returns a complete plan in one call without executing anything, the model
@@ -577,10 +637,8 @@ context, set `deferToolSummaryChars` alongside it (roughly 200–400 works well)
 > confirmation gate reads a tool's `mutating`/`destructive` **flags**, never its description
 > — so a truncated "requires confirmation" sentence cannot disable it.
 >
-> Note `AiTool.authorize()` is **not** part of that chain in every mode: it runs in **plan
-> mode only**. In auto mode (the default) and over MCP, tools go straight to `execute()` — so
-> data-level checks (ownership, tenant scope) must live **inside `execute()`**, routed through
-> `CrudService` with `context.serviceOptions`, not in `authorize()` alone.
+> `AiTool.authorize()` is part of that chain on every path since 12.3.0 (auto mode, plan
+> mode, MCP), and it reads the call's arguments, never the description.
 
 ## Token budgets & usage
 
@@ -671,6 +729,53 @@ the server log; the response carries only a stable `#LTNS_0901` code.
 - Answering a foreign id `404` rather than `403` is deliberate — a 403 would confirm
   that the id exists, and the id travels in a response header and through client logs.
 
+### Authorization and confirmation over MCP (12.3.0+)
+
+`tools/call` applies the same gates as the chat orchestrator, in this order:
+
+1. **Role filter** — the tool must be in the user's set (`AiToolRegistry.forUser()`).
+2. **Tool policies** — the admin's `aiToolPolicies` rules for this call: `deny` answers an
+   error result, `ask` asks in step 4 whatever else is configured.
+3. **`authorize()`** — the tool's data-level check on the call's arguments. A refusal, a
+   thrown error or an `allowed` that is not `true` answers an error result; nothing runs.
+4. **Confirmation** — a `destructive` tool always, a `mutating` tool when
+   `ai.confirmation.mutating` says so (`enforced`, else `default`; MCP has no per-request
+   `requireConfirmation`), as long as MCP asks this user (below). The server asks through
+   **MCP elicitation** (a yes/no form the client shows) and runs the tool only on an
+   explicit yes. A no, a cancelled dialog, an error or a timeout (5 minutes) means "not
+   run". A client without the `elicitation` capability gets an error result instead of an
+   unconfirmed run.
+5. **`execute()`** — with `context.authorization` from step 3.
+
+**Whether MCP asks** is a server default each user may switch for themselves, like a
+"bypass permissions" mode:
+
+| `ai.mcp.confirmation`                | Asks a user who has not chosen | A user's own switch                          |
+| ------------------------------------ | ------------------------------ | -------------------------------------------- |
+| unset, `true`, `{}`                  | yes                            | may switch it off                            |
+| `false`                              | no                             | may switch it on                             |
+| `{ default: true, enforced: true }`  | yes                            | ignored; a change answers 403 (`#LTNS_0609`) |
+| `{ default: false, enforced: true }` | no                             | ignored; a change answers 403                |
+
+The user's switch is `PUT /ai/settings` with `{ mcpConfirmation: false }` (GraphQL
+`updateAiSettings`), read back with `GET /ai/settings` (`aiSettings`), which answers the
+effective value and `mcpConfirmationEnforced` so a UI can show the switch disabled. It is
+stored per user (`aiUserSettings`, one record per user) and touches nobody else's calls.
+Only `false` switches the default off and only `enforced: true` enforces — a misspelt value
+never relaxes the gate. `authorize()` and the admin's `deny` / `ask` rules apply whatever
+the switch says.
+
+`tools/list` gives a `destructive` tool `annotations: { destructiveHint: true, readOnlyHint: false }`
+and a `mutating` one `{ destructiveHint: false, readOnlyHint: false }` — hints for the client's own
+UI, not a security boundary. A tool with neither flag carries no annotations: it may still write,
+so it is never advertised as read-only, and clients keep the spec's cautious defaults.
+
+The confirmation keeps the model from acting without the user; it cannot stop a hostile
+client, which holds the user's credential and could call the API directly. The boundary
+against that stays the role filter, `authorize()` and the `CrudService` inside `execute()`.
+The question is English (an MCP request carries no language); override
+`CoreAiMcpService.confirmationPrompt()` to localize it.
+
 ### Multi-replica / sticky sessions
 
 An MCP session owns a **live Streamable-HTTP transport** — an open response stream
@@ -696,6 +801,16 @@ and sends operators looking in the wrong place.
 
 Without Redis nothing changes: unknown ids answer `404` exactly as before.
 
+**No sticky sessions available?** Set `ai.mcp.stateless: true` (12.3.0+). Every POST then builds its own
+server and transport for the authenticated user (the SDK's stateless mode, `sessionIdGenerator: undefined`),
+no `mcp-session-id` is issued, a session id a client still sends is ignored, and GET / DELETE answer `405`
+with `Allow: POST`. Any replica can answer any request, and the user's rights and tenant are read per request
+by construction. What is lost is what a session carries: server-initiated messages, the SSE stream, and
+server-initiated requests — **MCP elicitation among them**. A tool that needs confirmation (above) is
+therefore refused in this mode unless the user switched the question off (`PUT /ai/settings`) or
+`ai.mcp.confirmation` is `false`. A server that only offers read tools is not affected.
+`testHelper.mcpSession()` follows the setting (no session id expected or sent; `sessionId` is `''`).
+
 ### OAuth 2.1 (`ai.mcp.oauth: true`)
 
 For generic MCP clients that auto-discover + register:
@@ -767,7 +882,13 @@ user decides whether an MCP client may act for them:
 - **Allow** issues the code only with the page's CSRF token, signed with the OAuth secret and bound to
   the user, the client, the redirect URI and the PKCE challenge (10 minutes); a stale token shows the
   form again, a forged or tampered one too, and nothing is issued. **Deny** sends the client back with
-  `access_denied`.
+  `access_denied` — with the same token since 12.3.0; without it the form is shown again.
+- **A malformed request** (a missing `code_challenge`, a wrong `response_type`, …) is answered with `400`
+  and `{ error, error_description }`, never redirected to the client (12.3.0). The redirect URI is whatever
+  the client's registrant wrote, so the SDK's error redirect made `/authorize` an open redirect on this
+  domain (RFC 9700 §4.11.2). Registration itself stays open — claude.ai, ChatGPT, Cursor and Claude Code
+  register their own URIs. Only what happens once the request reached the provider (the user's Allow or
+  Deny, and refusals raised in `authorizeConsent()`) still redirects.
 
 The page carries its own `Content-Security-Policy` (script and style by nonce, `frame-ancestors 'none'`,
 no `form-action`, which browsers would apply to the redirect to the client), `X-Frame-Options: DENY`,
@@ -792,8 +913,25 @@ the page offers no sign-in. Its sign-in goes through the IAM sign-in controller,
 hands Better-Auth the request so Better-Auth's own login-CSRF protection runs — otherwise a hostile page
 could sign the visitor in to the attacker's account before they approve a client.
 
-**Your own page.** Override `renderConsentPage(view)` in a subclass to restyle it (keep every value
-escaped), or `authorizeConsent(client, params, res)` for a consent UI of your own — same shape: no session
+**Your own wording and look (12.3.0+).** Override `renderConsentPage(view)` and call
+`renderMcpOAuthConsentPage(view, { texts, styles })`: `texts` replaces single texts per locale (merged over
+the built-in ones, still escaped), `styles` is CSS appended inside the page's nonce'd `<style>` element. The
+markup, the scripts and the security headers stay the framework's, so the page keeps receiving their fixes.
+Fill both from code or configuration only, never from user or tenant input: a `<` in `styles` is neutralized
+so it cannot end the `<style>` element, and the page's CSP blocks what CSS could load from elsewhere, but CSS
+still decides what the page shows.
+
+```typescript
+protected override renderConsentPage(view: IMcpOAuthConsentView): string {
+  return renderMcpOAuthConsentPage(view, {
+    styles: ':root{--accent:#0b5}',
+    texts: { de: { intro: '{client} möchte in Ihrem Namen auf {app} zugreifen.' } },
+  });
+}
+```
+
+**Your own page.** Override `renderConsentPage(view)` in a subclass to restyle it beyond that (keep every
+value escaped), or `authorizeConsent(client, params, res)` for a consent UI of your own — same shape: no session
 → sign in, GET → show which client, POST with a CSRF token → `saveAuthorizationCode()` and redirect;
 refuse with `AccessDeniedError` from `this.loadOAuthErrors()`. Register the subclass via
 `CoreModule.forRoot(env, { ai: { mcpOAuthService } })`, so the MCP controller and the endpoints share it.
@@ -802,9 +940,9 @@ production secret check runs again before the endpoints are mounted (without a s
 environment outside `local` / `ci` / `e2e` refuses to boot and to sign tokens at all — deployed `develop` and `test`
 stages included).
 
-Known property of the SDK: `/authorize` redirects its error answers to the client's registered
-redirect URI, and any client may register any https URI — an open redirect in the sense of RFC 9700
-§4.11.2, carrying only an OAuth error code.
+Until 12.3.0 the SDK's error redirect made `/authorize` an open redirect in the sense of RFC 9700
+§4.11.2, since any client may register any https URI; the framework now answers those errors itself
+(see "A malformed request" under the consent page above).
 
 **Refusals are OAuth errors (11.43.0).** The SDK's handlers answer an error with its OAuth code only
 when it is one of the SDK's own `OAuthError` classes; anything else becomes `500 server_error`. The

package/src/core/modules/ai/core-ai-mcp.controller.ts

@@ -48,7 +48,8 @@ import { AiToolUser } from './tools/ai-tool.registry.js';
  * sessions behind a load balancer. When Redis is configured, session ids are additionally
  * registered in a shared registry (replica + owning user), which turns a mis-routed request
  * into an explicit 409 naming the owning replica instead of a misleading "unknown session" 404.
- * Without Redis the behavior is unchanged.
+ * Without Redis the behavior is unchanged. `ai.mcp.stateless` removes the requirement altogether:
+ * every request then builds its own server and transport, and any replica can answer it.
  *
  * The registry entry records the OWNING USER, and only that user is ever told about the 409.
  * Otherwise the cross-replica path would undo the local one: an authenticated caller probing
@@ -130,6 +131,11 @@ export class CoreAiMcpController implements OnModuleDestroy {
       return;
     }
 
+    if (this.statelessEnabled()) {
+      await this.handleStatelessPost(req, res, user);
+      return;
+    }
+
     const sessionId = req.headers['mcp-session-id'] as string | undefined;
     let entry = sessionId ? this.transports.get(sessionId) : undefined;
 
@@ -342,6 +348,42 @@ export class CoreAiMcpController implements OnModuleDestroy {
     return body?.method === 'initialize';
   }
 
+  /**
+   * Whether `/ai/mcp` runs without sessions (`ai.mcp.stateless`).
+   */
+  protected statelessEnabled(): boolean {
+    const mcp = ConfigService.get<{ stateless?: boolean }>('ai.mcp');
+    return typeof mcp === 'object' && mcp?.stateless === true;
+  }
+
+  /**
+   * One request, one server: the stateless mode of the SDK transport (`sessionIdGenerator: undefined`).
+   *
+   * Nothing outlives the response, so nothing has to reach the same replica again — the reason this
+   * mode exists. Rights are the user's as of THIS request by construction. A `mcp-session-id` a client
+   * still sends (from before a switch to this mode) is ignored rather than answered 404: there is no
+   * session it could refer to, and a 404 would only send the client into a reconnect.
+   */
+  protected async handleStatelessPost(req: Request, res: Response, user: AiToolUser): Promise<void> {
+    let StreamableHTTPServerTransport: any;
+    try {
+      ({ StreamableHTTPServerTransport } = await import('@modelcontextprotocol/sdk/server/streamableHttp.js'));
+    } catch (err) {
+      // Same lazy import and 503 reasoning as the session path in handlePost().
+      return this.mcpUnavailable(res, err as Error);
+    }
+    const transport: any = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    const server = await this.mcpService.createServer(user);
+    // Released with the response — an aborted request included, so a client that hangs up cannot
+    // leave a server behind.
+    res.on('close', () => {
+      Promise.resolve(transport.close?.()).catch(() => undefined);
+      Promise.resolve(server.close?.()).catch(() => undefined);
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  }
+
   /**
    * Whether the OAuth 2.1 layer is enabled via `ai.mcp.oauth`.
    */
@@ -359,6 +401,11 @@ export class CoreAiMcpController implements OnModuleDestroy {
       this.unauthorized(res);
       return;
     }
+    // Without sessions there is no stream to open and nothing to end (MCP spec: 405 for GET then).
+    if (this.statelessEnabled()) {
+      res.status(405).set('Allow', 'POST').json({ error: 'Method not allowed: this MCP server is stateless' });
+      return;
+    }
     const sessionId = req.headers['mcp-session-id'] as string | undefined;
     const held = sessionId ? this.transports.get(sessionId) : undefined;
     // Same ownership rule as the POST path: another user's session is not ours to serve.

package/src/core/modules/ai/core-ai.constants.ts

@@ -91,6 +91,12 @@ export const AI_TOOL_POLICY_CLASS = 'AI_TOOL_POLICY_CLASS';
 /** Mongoose injection token. */
 export const AI_TOOL_POLICY_MODEL = 'AiToolPolicy';
 
+// ---- user-setting ----
+/** DI token for the model constructor (used by CrudService mapping). */
+export const AI_USER_SETTING_CLASS = 'AI_USER_SETTING_CLASS';
+/** Mongoose injection token. */
+export const AI_USER_SETTING_MODEL = 'AiUserSetting';
+
 // ---- MCP OAuth (stored natively on MongoDB; these models give them their tables on a SQL source) ----
 /** Mongoose model name of the registered OAuth clients (`aiMcpOAuthClients`). */
 export const AI_MCP_OAUTH_CLIENT_MODEL = 'AiMcpOAuthClient';

package/src/core/modules/ai/core-ai.controller.ts

@@ -1,4 +1,4 @@
-import { Body, Controller, Delete, Get, Param, Post, Put, Query, Res } from '@nestjs/common';
+import { Body, Controller, Delete, Get, Inject, Param, Post, Put, Query, Res } from '@nestjs/common';
 import type { Response } from 'express';
 
 import { RESTServiceOptions } from '../../common/decorators/rest-service-options.decorator.js';
@@ -19,6 +19,7 @@ import { CoreAiPromptUpdateInput } from './inputs/core-ai-prompt-update.input.js
 import { CoreAiSlotCreateInput } from './inputs/core-ai-slot-create.input.js';
 import { CoreAiSlotUpdateInput } from './inputs/core-ai-slot-update.input.js';
 import { CoreAiPromptInput } from './inputs/core-ai-prompt.input.js';
+import { CoreAiSettingsInput } from './inputs/core-ai-settings.input.js';
 import { CoreAiAvailableConnection } from './models/core-ai-available-connection.model.js';
 import { CoreAiBudgetLimit } from './models/core-ai-budget-limit.model.js';
 import { CoreAiConnectionPreference } from './models/core-ai-connection-preference.model.js';
@@ -29,6 +30,7 @@ import { CoreAiPromptHint } from './models/core-ai-prompt-hint.model.js';
 import { CoreAiPrompt } from './models/core-ai-prompt.model.js';
 import { CoreAiSlot } from './models/core-ai-slot.model.js';
 import { CoreAiResponse } from './models/core-ai-response.model.js';
+import { CoreAiSettings } from './models/core-ai-settings.model.js';
 import { CoreAiUsageInfo } from './models/core-ai-usage-info.model.js';
 import { CoreAiBudgetService } from './services/core-ai-budget.service.js';
 import { CoreAiConnectionPreferenceService } from './services/core-ai-connection-preference.service.js';
@@ -37,6 +39,7 @@ import { CoreAiConnectionService } from './services/core-ai-connection.service.j
 import { CoreAiConversationService } from './services/core-ai-conversation.service.js';
 import { CoreAiInteractionService } from './services/core-ai-interaction.service.js';
 import { CoreAiPlaceholderRegistry } from './services/core-ai-placeholder.registry.js';
+import { CoreAiUserSettingService } from './services/core-ai-user-setting.service.js';
 import { CoreAiPromptHintService } from './services/core-ai-prompt-hint.service.js';
 import { CoreAiPromptService } from './services/core-ai-prompt.service.js';
 import { CoreAiSlotService } from './services/core-ai-slot.service.js';
@@ -67,6 +70,13 @@ export class CoreAiController {
     protected readonly placeholderRegistry: CoreAiPlaceholderRegistry,
   ) {}
 
+  /**
+   * Personal AI settings (12.3.0+). Injected as a property, not through the constructor, so a project subclass
+   * written before it keeps compiling and still gets the settings endpoints.
+   */
+  @Inject(CoreAiUserSettingService)
+  protected readonly userSettingService: CoreAiUserSettingService;
+
   /**
    * Send a prompt to the AI assistant.
    */
@@ -362,6 +372,31 @@ export class CoreAiController {
     return this.budgetService.getUsageInfo(serviceOptions?.currentUser?.id, RequestContext.getTenantId());
   }
 
+  // ===================================================================================================================
+  // Personal settings
+  // ===================================================================================================================
+
+  /**
+   * The current user's AI settings as they take effect.
+   */
+  @Get('settings')
+  @Roles(RoleEnum.S_USER)
+  async settings(@RESTServiceOptions() serviceOptions: ServiceOptions): Promise<CoreAiSettings> {
+    return this.userSettingService.getSettings(serviceOptions?.currentUser?.id);
+  }
+
+  /**
+   * Change the current user's own AI settings (403 for a setting the server enforces).
+   */
+  @Put('settings')
+  @Roles(RoleEnum.S_USER)
+  async updateSettings(
+    @RESTServiceOptions() serviceOptions: ServiceOptions,
+    @Body() input: CoreAiSettingsInput,
+  ): Promise<CoreAiSettings> {
+    return this.userSettingService.updateSettings(serviceOptions?.currentUser?.id, input);
+  }
+
   /**
    * Find AI budget limits (admin).
    */

package/src/core/modules/ai/core-ai.module.ts

@@ -11,6 +11,8 @@ import {
   AI_MCP_OAUTH_CLIENT_MODEL,
   AI_MCP_OAUTH_CODE_MODEL,
   AI_MCP_OAUTH_REFRESH_TOKEN_MODEL,
+  AI_USER_SETTING_CLASS,
+  AI_USER_SETTING_MODEL,
 } from './core-ai.constants.js';
 import { AiBudgetLimitSchema, CoreAiBudgetLimit } from './models/core-ai-budget-limit.model.js';
 import {
@@ -31,6 +33,7 @@ import { AiSlotSchema, CoreAiSlot } from './models/core-ai-slot.model.js';
 import { AiModeSchema, CoreAiMode } from './models/core-ai-mode.model.js';
 import { AiToolGrantSchema, CoreAiToolGrant } from './models/core-ai-tool-grant.model.js';
 import { AiToolPolicySchema, CoreAiToolPolicy } from './models/core-ai-tool-policy.model.js';
+import { AiUserSettingSchema, CoreAiUserSetting } from './models/core-ai-user-setting.model.js';
 import { LlmProviderFactory } from './providers/llm-provider.factory.js';
 import { AiCryptoService } from './services/ai-crypto.service.js';
 import {
@@ -79,6 +82,7 @@ import {
   CoreAiToolPolicyService,
 } from './services/core-ai-tool-policy.service.js';
 import { AI_MODE_CLASS, AI_MODE_MODEL, CoreAiModeService } from './services/core-ai-mode.service.js';
+import { CoreAiUserSettingService } from './services/core-ai-user-setting.service.js';
 import { CoreAiMcpClientService } from './services/core-ai-mcp-client.service.js';
 import { CoreAiService } from './services/core-ai.service.js';
 import { AiHookRegistry } from './hooks/ai-hook.registry.js';
@@ -149,6 +153,9 @@ export interface CoreAiModuleOptions {
   /** Custom scoped tool-policy store (extends CoreAiToolPolicyService). */
   toolPolicyService?: Type<CoreAiToolPolicyService>;
 
+  /** Custom personal-settings store (extends CoreAiUserSettingService). */
+  userSettingService?: Type<CoreAiUserSettingService>;
+
   /** Custom named-mode store (extends CoreAiModeService). */
   modeService?: Type<CoreAiModeService>;
 
@@ -208,6 +215,7 @@ export class CoreAiModule {
       { model: CoreAiToolGrant, name: AI_TOOL_GRANT_MODEL, schema: AiToolGrantSchema },
       { model: CoreAiToolPolicy, name: AI_TOOL_POLICY_MODEL, schema: AiToolPolicySchema },
       { model: CoreAiMode, name: AI_MODE_MODEL, schema: AiModeSchema },
+      { model: CoreAiUserSetting, name: AI_USER_SETTING_MODEL, schema: AiUserSettingSchema },
       // Stored natively on MongoDB; the models give them their tables on a SQL source
       { name: AI_MCP_OAUTH_CLIENT_MODEL, schema: AiMcpOAuthClientSchema },
       { name: AI_MCP_OAUTH_CODE_MODEL, schema: AiMcpOAuthCodeSchema },
@@ -215,6 +223,7 @@ export class CoreAiModule {
     ]);
     const ToolGrantServiceClass = options.toolGrantService || CoreAiToolGrantService;
     const ToolPolicyServiceClass = options.toolPolicyService || CoreAiToolPolicyService;
+    const UserSettingServiceClass = options.userSettingService || CoreAiUserSettingService;
     const ModeServiceClass = options.modeService || CoreAiModeService;
     const McpClientServiceClass = options.mcpClientService || CoreAiMcpClientService;
     const McpOAuthServiceClass = options.mcpOAuthService || CoreAiMcpOAuthService;
@@ -250,6 +259,7 @@ export class CoreAiModule {
         CoreAiService,
         CoreAiToolGrantService,
         CoreAiToolPolicyService,
+        CoreAiUserSettingService,
         CoreAiModeService,
         CoreAiMcpClientService,
         LlmProviderFactory,
@@ -275,6 +285,7 @@ export class CoreAiModule {
         { provide: AI_TOOL_GRANT_CLASS, useValue: CoreAiToolGrant },
         { provide: AI_TOOL_POLICY_CLASS, useValue: CoreAiToolPolicy },
         { provide: AI_MODE_CLASS, useValue: CoreAiMode },
+        { provide: AI_USER_SETTING_CLASS, useValue: CoreAiUserSetting },
         { provide: CoreAiBudgetService, useClass: BudgetServiceClass },
         { provide: CoreAiConversationService, useClass: ConversationServiceClass },
         { provide: CoreAiInteractionService, useClass: InteractionServiceClass },
@@ -293,6 +304,7 @@ export class CoreAiModule {
         { provide: CoreAiService, useClass: ServiceClass },
         { provide: CoreAiToolGrantService, useClass: ToolGrantServiceClass },
         { provide: CoreAiToolPolicyService, useClass: ToolPolicyServiceClass },
+        { provide: CoreAiUserSettingService, useClass: UserSettingServiceClass },
         { provide: CoreAiModeService, useClass: ModeServiceClass },
         { provide: CoreAiMcpClientService, useClass: McpClientServiceClass },
         { provide: CoreAiMcpOAuthService, useClass: McpOAuthServiceClass },