@lenne.tech/nest-server 11.32.1 → 11.32.3

package/migration-guides/11.25.x-to-11.26.0.md

@@ -74,13 +74,9 @@ Tools self-register in the global `AiToolRegistry`. Implement `IAiTool` (or exte
 
 #### 4. Enable the MCP server (optional)
 
-If you set `ai: { mcp: true }` (or `ai: { mcp: { oauth: true, oauthSecret: '…' } }`), **install the MCP SDK** in your project:
+If you set `ai: { mcp: true }` (or `ai: { mcp: { oauth: true, oauthSecret: '…' } }`), no install step is needed.
 
-```bash
-pnpm add @modelcontextprotocol/sdk
-```
-
-The SDK is a peer-style optional dependency that the controller lazy-imports on the first MCP request — projects without MCP pay no install cost. When `ai.mcp` is set but the SDK is missing, `/ai/mcp` returns **503 Service Unavailable** with the install hint instead of a 500 trace.
+> **Correction (11.32.2):** this guide originally instructed `pnpm add @modelcontextprotocol/sdk` and called the SDK a "peer-style optional dependency". That was wrong. It is a regular `dependency` of `@lenne.tech/nest-server` and reaches both consumption modes — npm-mode transitively, CLI-vendored projects through the dependency merge. The controller still lazy-imports it on the first MCP request, so a project without MCP pays no startup cost. A 503 from `/ai/mcp` therefore means the module could not be RESOLVED; the underlying error is in the server log.
 
 For OAuth 2.1 (generic MCP clients with auto-discovery + dynamic registration), mount the OAuth router in `main.ts`:
 
@@ -264,7 +260,7 @@ If you cast to `as any` to pass these to `CoreModule.forRoot(...)`, you can drop
 | `aiPrompt` returns "No AI service is currently available" | No usable connection exists — create one (admin) or set `AI_BASE_URL` to seed a default |
 | API keys encrypted with a dev default (warning logged) | Set `NSC__AI__ENCRYPTION_SECRET` (32+ chars) in production |
 | Custom MCP controller endpoints return 404 | Ensure the MCP controller is enabled (`ai.mcp`) and OAuth is mounted in `main.ts` when using `ai.mcp.oauth` |
-| `/ai/mcp` returns 503 "MCP server unavailable: the @modelcontextprotocol/sdk peer dependency is not installed" | Install the SDK in your project: `pnpm add @modelcontextprotocol/sdk` (it is a peer-style optional dep, lazy-imported only when MCP is used) |
+| `/ai/mcp` returns 503 | Since 11.32.2 the body carries `#LTNS_0901` and points at the log. The SDK is a regular dependency and reaches both npm and vendor mode, so this means it could not be RESOLVED, not that it is missing — check the server log for the underlying error |
 | Token budgets not enforced | Budgets require `ai.audit: true` (usage is read from `aiInteractions`) |
 | `aiPrompt` returns 500 "BSONError: input must be a 24 character hex string" | A client sent `conversationId: "null"` (literal string). The orchestrator now treats `"null"`/`"undefined"` strings as "no conversation" — upgrade to the latest 11.26.x patch if you still see this |
 

package/migration-guides/11.32.1-to-11.32.2.md

@@ -0,0 +1,173 @@
+# Migration Guide: 11.32.1 → 11.32.2
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | `ai.deferToolSummaryChars` — cap tool descriptions in the deferred tool catalog |
+| **Bugfixes** | Quadratic-backtracking regex in the tool-catalog builder (event-loop stall); three orchestrator messages were English-only; `context` was not framed as untrusted; misleading MCP 503 message |
+| **Migration Effort** | ~5 minutes — read §2 if you assert on AI response text, §3 if you use `deferToolSchemas` |
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.32.2
+pnpm run build
+pnpm test
+```
+
+No configuration change is required. Everything below is either opt-in or a
+correction you inherit automatically.
+
+---
+
+## 1. Fixed: event-loop stall in the tool-catalog builder
+
+`CoreAiPromptBuilderService` used a sentence-splitting regex whose leading greedy
+character class made it **quadratic** in the description length. A tool description
+of 100 KB without a sentence terminator blocked the event loop for **~6.7 seconds**
+— on every prompt build, single-threaded, for the whole API.
+
+This is relevant to you if tool descriptions can come from outside your codebase:
+`CoreAiMcpClientService.buildWrapperTool` adopts whatever a remote MCP server
+advertises, uncapped.
+
+Fixed by matching the terminator via lookahead instead. Runtime is now bounded by
+the configured cap rather than by input length (100 KB: 6.7 s → 0.02 ms).
+
+**Action: none.** Behaviour is unchanged for realistic descriptions. The only inputs
+that summarise differently are those that *begin* with punctuation or place a
+terminator directly after whitespace — the result stays a prefix of the original and
+still respects the cap.
+
+---
+
+## 2. Three orchestrator messages are now translated
+
+These were hard-coded English regardless of the requested language:
+
+| Situation | Now returns |
+|-----------|-------------|
+| Confirmation required for an action | `translate('confirm_required')` |
+| No final answer within `maxIterations` | `translate('no_final_answer')` |
+| Action blocked by policy | `translate('blocked_by_policy')` — the English `\|\|` fallback was removed |
+
+**Action required if** your frontend or tests match on the English strings — e.g.
+`expect(response.text).toContain('could not produce a final answer')`. With
+`language: 'de'` these now return German. Assert on `requiresConfirmation`,
+`actions` or the response shape instead of on prose.
+
+---
+
+## 3. New: `ai.deferToolSummaryChars` (opt-in, default `0`)
+
+Caps each tool description in the **deferred** catalog (`deferToolSchemas: true`).
+
+```typescript
+ai: {
+  deferToolSchemas: true,
+  deferToolSummaryChars: 300,  // 0 (default) = untruncated
+}
+```
+
+With a large registry the descriptions alone can re-inflate the prompt that
+`deferToolSchemas` was meant to shrink. Whole sentences are kept up to the cap, a
+`…` marks the cut (appended **on top of** the cap, so a shortened entry is
+`cap + 1` characters), and `search_tools` still returns the full text.
+
+**The default `0` is deliberate**: enabling `deferToolSchemas` alone never changes
+what a description says. The saving is therefore opt-in — set both together.
+
+Two scoping notes:
+
+- In **auto mode**, a connection with `supportsNativeTools: true` receives full
+  descriptions and schemas through the native `tools` payload anyway, so truncation
+  and the `search_tools` banner are skipped there.
+- **Plan mode always uses the emulated protocol**, so a native connection *is*
+  truncated there — and since plan mode produces a complete plan in one call without
+  executing, it cannot follow the `search_tools` hint. Keep the cap generous if you
+  rely on plan mode.
+
+> The truncated tail is typically where preconditions and role limits are written.
+> This is model **guidance only** — authorization is enforced by the registry role
+> filter, the execution-time re-check and the `mutating`/`destructive` flags, none of
+> which read the description.
+
+---
+
+## 4. `input.context` is now framed as UNTRUSTED
+
+`appendClientContext()` previously labelled the structured `context` block
+`Context (structured):` while `metadata` was explicitly marked untrusted. Both
+arrive on the same request from the same client, so the asymmetry invited smuggling
+instructions through the half that read as trusted. Both blocks now carry identical
+UNTRUSTED framing, and U+2028/U+2029 (which `JSON.stringify` does **not** escape) are
+neutralised so a client cannot fake a line break out of its block.
+
+**Action required if** you have a prompt fragment, `aiSlots` override or test that
+matches the old `Context (structured):` label.
+
+---
+
+## 5. Corrected documentation: `AiTool.authorize()` runs in PLAN MODE only
+
+No code change — but the docs previously implied `authorize()` was a general
+enforcement layer. It is not: auto mode (the default) and the MCP endpoint call
+`execute()` directly.
+
+**Check your tools.** A data-level check (ownership, tenant scope) that lives *only*
+in `authorize()` does not run for most callers. Put it inside `execute()`, routed
+through `CrudService` with `context.serviceOptions`, and treat `authorize()` as the
+plan-mode pre-flight that can reject a whole plan before any step runs.
+
+> Also note there is **no confirmation gate over MCP**: `mcpCallTool` does not consult
+> the `mutating`/`destructive` flags. A destructive tool invoked through `/ai/mcp`
+> executes immediately.
+
+---
+
+## 6. MCP 503 message changed shape
+
+`/ai/mcp` returned an install hint claiming `@modelcontextprotocol/sdk` was a missing
+"peer-style optional dependency". That was wrong: it is a regular `dependency` and
+reaches both consumption modes (npm-mode transitively, CLI-vendored projects via the
+dependency merge). A failure there is a **resolution** problem, not an absent package.
+
+The body now carries the stable `#LTNS_0901` ErrorCode and points at the server log.
+The underlying error (which contains filesystem paths) stays out of the response.
+
+**Action required if** you match on the old message text. Branch on the ErrorCode.
+
+---
+
+## 7. Test-runner change (framework repo only)
+
+`restoreMocks: true` was added to `vitest.config.ts` and `vitest-e2e.config.ts`.
+These files are **not** part of the vendored file set, so vendor-mode consumers are
+unaffected. Adopting it in your own project is recommended: without it, a
+`vi.spyOn` whose manual `mockRestore()` is skipped by a throwing assertion stays
+installed for the rest of the worker. Note vitest restores in `onBeforeTryTask`,
+i.e. **before** each attempt — a spy installed in `beforeAll` will not survive.
+
+---
+
+## Module Documentation
+
+- [AI module README](../src/core/modules/ai/README.md) — see "Deferred tool schemas (large registries)"
+- [AI INTEGRATION-CHECKLIST](../src/core/modules/ai/INTEGRATION-CHECKLIST.md) — advanced configuration
+- [Configurable features](../.claude/rules/configurable-features.md) — the Numeric Sentinel pattern
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Test asserts on English AI text and fails | §2 — messages are translated now | Assert on `requiresConfirmation` / `actions`, not prose |
+| `deferToolSummaryChars` has no effect | `deferToolSchemas` is off — the framework logs a warning once | Enable both together |
+| Tool descriptions truncated on a native connection | Plan mode always uses the emulated protocol (§3) | Raise the cap, or set `deferToolSummaryChars: 0` |
+| `/ai/mcp` returns 503 | The SDK could not be **resolved** (it is installed) | Check the server log for the underlying resolution error |
+| A prompt fragment no longer matches | §4 — the `context` label changed | Update the fragment / `aiSlots` override |

package/migration-guides/11.32.2-to-11.32.3.md

@@ -0,0 +1,129 @@
+# Migration Guide: 11.32.2 → 11.32.3
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | `ai.capabilityDriftCheck` — opt-in boot warning when an explicit connection capability contradicts the endpoint; `ai.defaultConnection.contextWindow` — seed a connection's context window from config |
+| **Bugfixes** | The AI connection `contextWindow` admin input now rejects non-positive / non-integer values |
+| **Migration Effort** | ~2 minutes — everything is opt-in; read §3 only if your admin tooling writes `contextWindow` |
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.32.3
+pnpm run build
+pnpm test
+```
+
+No configuration change is required. Everything below is opt-in or a
+tightening you inherit automatically.
+
+---
+
+## 1. New: `ai.capabilityDriftCheck` (opt-in, default `false`)
+
+A connection's `supportsNativeTools` / `supportsJsonResponse` flags are
+auto-detected while they are left **undefined**, but an **explicit** value is
+authoritative and is never re-probed. A wrong explicit flag therefore degrades the
+assistant silently — e.g. `supportsNativeTools: false` on a backend that *does*
+support native function calling forces fragile emulated tool-calling.
+
+Enable this opt-in boot self-check to surface such a mismatch:
+
+```typescript
+ai: {
+  capabilityDriftCheck: true,  // default false
+}
+```
+
+When enabled, at startup the module probes each enabled connection that declares an
+explicit flag and logs a **warning** on mismatch. It never changes the stored value
+(your explicit choice stays authoritative — clear the flag in the admin UI to
+re-enable auto-detection).
+
+**It is off by default because it makes outbound calls to the LLM endpoints on
+every boot** (and is additionally skipped in the `ci`/`e2e` runners). Note this is a
+diagnostic log only: if you deliberately override a flag against what the endpoint
+reports (e.g. native tools are advertised but unreliable on your model), the warning
+is expected and can be ignored.
+
+**Action: none** unless you want the diagnostic — then set the flag.
+
+---
+
+## 2. New: `ai.defaultConnection.contextWindow`
+
+The one-time `ai.defaultConnection` seed now accepts `contextWindow`, so a
+config-seeded connection can carry its context window from the start instead of
+relying on auto-detection:
+
+```typescript
+ai: {
+  defaultConnection: {
+    name: 'default',
+    baseUrl: '...',
+    model: '...',
+    contextWindow: 32768,  // optional — omit to auto-detect
+  },
+}
+```
+
+Omit it to keep the existing behaviour (auto-detect by probing the endpoint /
+`knownContextWindow()`, falling back to the global `ai.contextWindow` default of
+8192).
+
+**Action: none** — additive and optional.
+
+---
+
+## 3. Tightened: `contextWindow` admin input validation
+
+The `contextWindow` field on the AI connection create/update input is now validated
+as a **positive integer** (`@IsInt` + `@Min(1)`). Previously any number (including
+`0`, a negative, or a float) was accepted verbatim, and an explicit `0` is not
+"unset" — it would have fed the orchestrator's context budget as a real (broken)
+value instead of falling back to the safe default.
+
+**Action required if** your admin tooling or tests send a non-integer or
+`< 1` `contextWindow` to `createAiConnection` / `updateAiConnection` — those calls
+now return a validation error. Send a positive integer, or omit the field to
+auto-detect.
+
+---
+
+## 4. Documentation: the MCP confirmation-gate boundary
+
+No code change — a clarification of the `IAiTool.destructive` / `.mutating` JSDoc
+(reinforcing §5 of the 11.32.2 guide). Over `/ai/mcp` there is **no confirmation
+gate**: `mcpCallTool` consults neither flag, so a destructive tool executes on the
+first call. The barriers that *do* hold on every path are the registry **role
+filter** (`forUser()`, applied before `execute()`) and the authorization inside
+`execute()` itself — so a destructive tool restricted to a real role stays
+unreachable by lesser-privileged MCP clients; MCP only skips the extra confirmation
+step for clients that may already see the tool.
+
+**Action:** expose `/ai/mcp` only to clients you trust to obtain user consent
+themselves, and keep data-level authorization inside `execute()` (not only in the
+plan-mode `authorize()`).
+
+---
+
+## Module Documentation
+
+- [AI module README](../src/core/modules/ai/README.md) — see "Capability auto-detection"
+- [AI INTEGRATION-CHECKLIST](../src/core/modules/ai/INTEGRATION-CHECKLIST.md) — advanced configuration
+- [Configurable features](../.claude/rules/configurable-features.md) — the AI Assistant row
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Boot logs "capability drift" for a connection | §1 — an explicit flag disagrees with the endpoint | Correct the flag in the admin UI, or clear it to auto-detect; ignore if the override is deliberate |
+| `createAiConnection` rejects `contextWindow` | §3 — it must be a positive integer now | Send an integer `>= 1`, or omit to auto-detect |
+| A destructive tool ran over `/ai/mcp` without confirmation | §4 — MCP has no confirmation gate by design | Only expose MCP to trusted clients; enforce data-level checks in `execute()` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.32.1",
+  "version": "11.32.3",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",

package/src/core/common/interfaces/server-options.interface.ts

@@ -1110,6 +1110,16 @@ export interface IAiDefaultConnection {
   /** Capability tags (free-form, e.g. 'analysis', 'vision'). */
   capabilities?: string[];
 
+  /**
+   * Total context window (input + output tokens) the model supports. Drives the
+   * orchestrator's context budget (system prompt + history + tool results). Omit to
+   * auto-detect by probing the endpoint / `knownContextWindow()`; set it explicitly
+   * when the endpoint exposes no limit and the model id is unknown to the heuristic
+   * (otherwise the orchestrator assumes the conservative `ai.contextWindow` default
+   * of 8192 and trims the prompt + tool results on every turn).
+   */
+  contextWindow?: number;
+
   /** Default maximum number of tokens for completions. */
   defaultMaxTokens?: number;
 
@@ -1212,6 +1222,19 @@ export interface IAi {
     user?: { maxPrompts?: number; maxTokens?: number };
   };
 
+  /**
+   * Opt-in boot self-check: after startup, probe each enabled connection that declares
+   * an EXPLICIT `supportsNativeTools` / `supportsJsonResponse` and warn (log only) when
+   * the declared value contradicts what the endpoint actually reports — a wrong explicit
+   * flag otherwise silently degrades the assistant (e.g. forcing fragile emulated
+   * tool-calling on a backend that supports native function calling). OFF by default
+   * because it makes outbound calls to the LLM endpoints on every boot; the declared
+   * value is never changed (clear it in the admin UI to re-enable auto-detection). Also
+   * skipped in the ci/e2e runners.
+   * @default false
+   */
+  capabilityDriftCheck?: boolean;
+
   /**
    * Confirmation policy for mutating tool actions (create/update/delete).
    * `destructive` tools always require confirmation regardless of this policy.
@@ -1294,6 +1317,55 @@ export interface IAi {
    */
   deferToolSchemas?: boolean;
 
+  /**
+   * Maximum characters per tool description in the DEFERRED catalog
+   * (`deferToolSchemas: true`). Whole sentences are kept up to this cap (always
+   * at least the first one); when the first sentence alone exceeds the cap the
+   * text is cut on a word boundary. A shortened description always ends in `…`,
+   * which is appended ON TOP of the cap — a shortened entry is therefore
+   * `deferToolSummaryChars + 1` characters, not exactly the cap. The full text
+   * stays available through the `search_tools` meta-tool.
+   *
+   * Without a cap a large tool registry re-inflates the very prompt that
+   * `deferToolSchemas` was meant to shrink: with enough tools the descriptions
+   * alone can outweigh the schemas they replaced and consume the majority of a
+   * small context window. With a cap, mind that the omitted tail is where tool
+   * authors typically put preconditions and role restrictions; the catalog
+   * banner tells the model to fetch the full text before calling such a tool.
+   * Note this is model GUIDANCE only — it never relaxes authorization. Which tools
+   * a caller sees and may run is decided server-side by the registry's role filter
+   * (`AiToolRegistry.forUser()`), re-checked at execution time, and the
+   * confirmation gate reads the `mutating`/`destructive` FLAGS, never the
+   * description text. (`AiTool.authorize()` runs in plan mode only — in auto mode
+   * and over MCP, data-level checks belong inside `execute()`.)
+   *
+   * Applies to the EMULATED tool protocol, not to a provider as such. In auto mode
+   * a connection with native tool calling receives every full description and schema
+   * through `buildToolSchemas()` regardless, so no truncation is applied there and no
+   * `search_tools` banner is emitted — capping would otherwise assert a truncation
+   * that the tool payload right next to it contradicts.
+   *
+   * **Plan mode always uses the emulated protocol** (it sends no native schemas), so a
+   * native connection IS truncated there. Because plan mode returns a complete plan in
+   * one call and executes nothing, the model cannot act on a `search_tools` hint before
+   * committing — the catalog therefore carries a different banner there, telling it the
+   * descriptions are abbreviated and to plan conservatively. The dropped tail stays
+   * unrecoverable for planning, so keep the cap generous if you rely on plan mode.
+   *
+   * `0` (the default) keeps the untruncated descriptions, so enabling
+   * `deferToolSchemas` alone never changes what a tool description says. That
+   * backward-compatible default means the prompt saving is opt-in: when you turn
+   * on `deferToolSchemas` to reclaim context, set this too — roughly 200–400 is
+   * a good starting point, low enough to shrink a large catalog while still
+   * carrying a full first sentence per tool.
+   *
+   * Setting this WITHOUT `deferToolSchemas` does nothing (the cap only applies to
+   * the deferred catalog); the framework logs a warning once at runtime rather
+   * than ignoring it silently.
+   * @default 0
+   */
+  deferToolSummaryChars?: number;
+
   /** Maximum number of agent-loop iterations (tool round-trips). @default 5 */
   maxIterations?: number;
 

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

@@ -137,6 +137,8 @@ ai: {
   },
   contextWindow: 8192,                 // fallback when a connection has no auto-detected window
   maxToolResultChars: 12000,           // cap tool-results fed back to the model
+  deferToolSchemas: false,             // catalog = names + descriptions only; schemas via search_tools
+  deferToolSummaryChars: 0,            // 0 = full descriptions; set ~200-400 WITH deferToolSchemas
   promptLearning: { autoApply: false },// governed self-improvement (admins approve learned hints)
   mcp: { oauth: true, oauthSecret: process.env.NSC__AI__ENCRYPTION_SECRET },
 }
@@ -165,21 +167,41 @@ ai: {
 - **Context window:** detected automatically per connection and persisted; no setup needed.
   Override per connection (`contextWindow`) or globally (`ai.contextWindow`) if a backend
   isn't recognized.
+- **Many tools?** `deferToolSchemas: true` keeps the full JSON schemas out of the system
+  prompt (the model fetches one on demand via the built-in `search_tools` meta-tool). Set
+  `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
+  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;
+  the model is told to fetch the full text first, but that is guidance only — authorization
+  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.
 
 ### MCP server (only when `ai.mcp.enabled` or `ai.mcp` is truthy)
 
-**Install the MCP SDK** in your project:
+**No install step needed.** `@modelcontextprotocol/sdk` is a regular dependency of
+`@lenne.tech/nest-server` and reaches both consumption modes — npm-mode projects
+resolve it transitively, CLI-vendored projects get it merged into their own
+`package.json`. `CoreAiMcpController` still `import()`s it lazily, so a project
+that never enables MCP pays no startup cost.
 
-```bash
-pnpm add @modelcontextprotocol/sdk
-# or: npm install @modelcontextprotocol/sdk
-```
+A **503 Service Unavailable** from `/ai/mcp` therefore means the module could not be
+_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.
 
-The SDK is a peer-style optional dependency — it is `import()`-ed lazily by
-`CoreAiMcpController` only when an MCP request actually arrives, so projects
-that don't enable MCP pay no install cost. When `ai.mcp` is set but the SDK
-is not installed, `/ai/mcp` returns **503 Service Unavailable** with an
-install-hint message instead of a 500 trace.
+> **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()`.
 
 ### MCP OAuth 2.1 (only when `ai.mcp.oauth` is enabled)
 

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

@@ -56,6 +56,8 @@ ai: {
   systemPrompt: 'You are a helpful assistant for …',
   contextWindow: 8192,            // fallback when a connection has no detected window
   maxToolResultChars: 12000,      // cap a tool-results payload fed back to the model
+  deferToolSchemas: false,        // catalog lists names + descriptions only; schemas via search_tools
+  deferToolSummaryChars: 0,       // 0 = full descriptions; set ~200-400 together with deferToolSchemas
   promptLearning: { autoApply: false }, // governed self-improvement (admin approves hints)
   // Optional one-time seed of a default connection (DB is the source of truth):
   defaultConnection: {
@@ -109,6 +111,12 @@ never probed). Detection runs in two complementary ways:
   once, persists, and uses the result. Until then the safe emulated baseline applies.
 - **On demand:** admins can re-probe via `detectAiConnectionCapabilities` /
   `POST /ai/connections/:id/detect-capabilities` (e.g. after changing `baseUrl`/`model`).
+- **Boot drift check (opt-in):** set `ai.capabilityDriftCheck: true` to probe every enabled
+  connection that has an EXPLICIT flag once at startup and log a warning when the declared
+  value contradicts what the endpoint reports (a wrong explicit flag otherwise degrades the
+  assistant silently, e.g. forcing emulated tool-calling on a native-capable backend). It only
+  warns — the stored value is never changed. OFF by default because it makes outbound calls to
+  the LLM endpoints on every boot; also skipped in the ci/e2e runners.
 
 The probe is provider-agnostic best effort: `response_format: json_object` is sent
 (2xx → JSON supported); a trivial tool with `tool_choice: 'required'` is sent (2xx
@@ -345,17 +353,28 @@ export class TransferFundsTool extends AiTool {
   readonly name = 'transfer_funds';
   readonly mutating = true; // governed by the confirmation policy
   readonly destructive = true; // always requires confirmation
-  // Pre-flight check WITHOUT mutating — decides if the user may run this:
+
+  // 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.
   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' };
   }
+
   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);
+    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()`.
+
 ## Confirmation for changes
 
 - `destructive` tools always require confirmation.
@@ -421,9 +440,10 @@ The model also receives **structured tool errors** (`{ error: { code, message, h
 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, `authorize()`,
+> they can never relax the permission model. Tool role-filtering,
 > `CrudService`/`@Restricted` and `secretFields` are enforced backend-side regardless of
-> the prompt.
+> 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.)
 
 ```typescript
 ai: {
@@ -449,6 +469,55 @@ 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.
 
+## Deferred tool schemas (large registries)
+
+The system prompt normally carries every tool's full JSON parameter schema. With a large
+registry that catalog can dominate a small context window. Set `ai.deferToolSchemas: true`
+and the catalog lists only tool **names + descriptions**; the model fetches a specific
+schema on demand through the built-in `search_tools` meta-tool.
+
+With many tools the **descriptions alone** can then re-inflate the prompt the deferral was
+meant to shrink. `ai.deferToolSummaryChars` caps each description in that deferred catalog:
+whole sentences up to the cap (always at least the first one), a word-boundary cut when the
+first sentence already exceeds it, and a `…` marker appended **on top of** the cap.
+
+```typescript
+ai: {
+  deferToolSchemas: true,
+  deferToolSummaryChars: 300,  // 0 (default) = keep descriptions untruncated
+}
+```
+
+The default of `0` is deliberate: enabling `deferToolSchemas` alone never changes what a
+tool description _says_. The saving is therefore opt-in — when you defer schemas to reclaim
+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`.
+>
+> **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
+> cannot act on a `search_tools` hint before committing — the catalog therefore carries a
+> different banner there ("descriptions are abbreviated, plan conservatively") instead of
+> promising a lookup that would arrive too late. The dropped tail stays unrecoverable for
+> planning, so keep the cap generous if you rely on plan mode.
+
+> **The truncated tail is where preconditions and role restrictions usually live.** The
+> catalog banner instructs the model to fetch the full text via `search_tools` before
+> calling a `…`-marked tool. This is model **guidance only** — it never affects
+> authorization. Which tools a user sees and may run is decided server-side by the registry's
+> role filter (`AiToolRegistry.forUser()`), re-checked when the call executes; and the
+> 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.
+
 ## Token budgets & usage
 
 Token/prompt limits are **per user AND per tenant**, with **config defaults** so you
@@ -483,17 +552,16 @@ The `AiToolRegistry` also feeds a real **MCP server** at `POST/GET/DELETE /ai/mc
 (Streamable HTTP), so external MCP clients use the same backend tools with the
 same role gating. Enable with `ai: { mcp: true }`.
 
-**Install the SDK** in your project (it is a peer-style optional dependency that
-the controller lazy-imports only when an MCP request arrives — projects that
-don't enable MCP pay no install cost):
-
-```bash
-pnpm add @modelcontextprotocol/sdk
-```
+**No install step needed.** `@modelcontextprotocol/sdk` ships as a regular
+dependency of `@lenne.tech/nest-server` and reaches both consumption modes:
+npm-mode projects resolve it transitively, and CLI-vendored projects get it
+merged into their own `package.json`. The controller still `import()`s it
+lazily, so a project that never enables MCP does not pay the startup cost.
 
-When `ai.mcp` is set but the SDK is missing, `/ai/mcp` returns **503 Service
-Unavailable** with an actionable install-hint message instead of a 500 stack
-trace.
+If `/ai/mcp` nevertheless returns **503 Service Unavailable**, the module could
+not be _resolved_ — a bundler or test runner with its own module resolution can
+fail on the subpath export while plain Node succeeds. The underlying error is in
+the server log; the response carries only a stable `#LTNS_0901` code.
 
 - Auth: the request must carry a valid Bearer token/session (resolved by the
   framework's existing auth) — the MCP session is bound to that user, and