@lenne.tech/nest-server 11.32.0 → 11.32.2

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.0-to-11.32.1.md

@@ -0,0 +1,84 @@
+# Migration Guide: 11.32.0 → 11.32.1
+
+## Overview
+
+| Category | Change | Effort |
+|----------|--------|--------|
+| **Bugfix** | A missing `migrations/` directory no longer blocks the server boot | None — automatic |
+| **Bugfix** | A spec in `src/core/` no longer breaks vendor-mode projects | None — automatic |
+
+**No code changes required.** Both fixes are internal.
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects: `/lt-dev:backend:update-nest-server-core`.
+
+---
+
+## What was fixed
+
+### A missing `migrations/` directory no longer blocks the boot
+
+`MigrationRunner.loadMigrationFiles()` called `fs.readdirSync()` without checking that the
+directory exists. A missing directory threw `ENOENT` — and because the standard start script is
+`migrate:up && start:local`, the `&&` turned that into a server that never starts, with an error
+that does not point at the cause.
+
+This is a state people produce routinely: *"delete all migrations"* reads to most as *"throw the
+folder away"*.
+
+A missing directory now means the same thing as an empty one — there are no migrations:
+
+```
+[migrate] migrations directory not found — treating as empty: ./migrations
+```
+
+`up()` and `status()` continue and exit 0. **`down()` is unchanged and still fails hard** —
+rollback is an explicit operator action, never a boot path, and an exit 0 with no rollback
+performed would mislead scripted rollbacks. `NSC__MIGRATE__STRICT=true` still turns a
+recorded-but-missing migration into a hard error, so the integrity guard is intact.
+
+If your project kept a `migrations/.gitkeep` purely to work around this, you can drop it — though
+keeping it does no harm.
+
+> Tracked as DEV-2634.
+
+### A `src/core/` spec no longer breaks vendor-mode projects
+
+`hub-mermaid.helper.spec.ts` mixed a value and a type import in one statement
+(`import { buildErDiagram, type HubModelDescriptor } from …`). The lt CLI's vendor conversion drops
+the inline `type` specifier, so the file arrived in vendored projects as
+`import { buildErDiagram }` and failed to compile with `TS2304: Cannot find name
+'HubModelDescriptor'` — breaking `pnpm run check` in every freshly generated vendor-mode project.
+
+The import is now split into two statements, which survives the conversion. Only vendor-mode
+projects were affected; npm-mode consumers never saw it.
+
+> The underlying CLI defect is tracked separately. Splitting the import keeps `src/core/`
+> vendor-safe regardless.
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---------|:------:|
+| Everything from 11.32.0 | Unchanged |
+| `MigrationRunner` public API | Unchanged |
+| `down()` behaviour on a missing rollback file | Unchanged (still hard error) |
+| `NSC__MIGRATE__STRICT` | Unchanged |
+
+Still relevant from the previous release: **[the two security overrides your project needs](11.31.3-to-11.32.0.md#security-add-two-overrides)** — pnpm `overrides:` are not inherited from this package. If you skipped that step, do it now.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `ENOENT: no such file or directory, scandir './migrations'` on start | Pre-11.32.1 | Update; no code change needed |
+| `TS2304: Cannot find name 'HubModelDescriptor'` in a vendored core | Pre-11.32.1 vendored copy | Re-sync the core, or split the import in that one spec by hand |

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.32.0",
+  "version": "11.32.2",
   "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

@@ -1294,6 +1294,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: {
@@ -345,17 +347,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 +434,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 +463,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 +546,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

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

@@ -6,6 +6,7 @@ import { Roles } from '../../common/decorators/roles.decorator';
 import { RoleEnum } from '../../common/enums/role.enum';
 import { ConfigService } from '../../common/services/config.service';
 import { CoreBetterAuthModule } from '../better-auth/core-better-auth.module';
+import { ErrorCode } from '../error-code/error-codes';
 import { CoreAiMcpOAuthService } from './services/core-ai-mcp-oauth.service';
 import { CoreAiMcpService } from './services/core-ai-mcp.service';
 
@@ -59,10 +60,13 @@ export class CoreAiMcpController {
       try {
         ({ StreamableHTTPServerTransport } = await import('@modelcontextprotocol/sdk/server/streamableHttp.js'));
       } catch (err) {
-        // The MCP SDK is a peer-style optional dependency — it must be installed
-        // by the consumer project when `ai.mcp.enabled` is true. Surface a
-        // 503 with an actionable hint instead of the raw "Cannot find module"
-        // 500 that bubbles from the lazy `import()`.
+        // Imported lazily so a consumer that never enables MCP does not pay for
+        // loading the SDK at startup. It IS a regular dependency of this package and
+        // reaches BOTH consumption modes — npm-mode transitively, CLI-vendored
+        // projects through the dependency merge — so a failure here is a resolution
+        // problem, not an absent package. Surface a 503 instead of the raw
+        // "Cannot find module" 500 that bubbles from the lazy `import()`.
+        // See mcpUnavailable() below for the full reasoning.
         return this.mcpUnavailable(res, err as Error);
       }
       const { randomUUID } = await import('node:crypto');
@@ -167,19 +171,31 @@ export class CoreAiMcpController {
   }
 
   /**
-   * 503 Service Unavailable when the optional `@modelcontextprotocol/sdk` peer
-   * dependency is not installed. The SDK is lazy-imported because not every
-   * consumer needs MCP — when `ai.mcp.enabled` is set but the SDK is missing,
-   * we surface the actionable install hint rather than the raw require-stack
-   * trace from the failed `import()`.
+   * 503 Service Unavailable when `@modelcontextprotocol/sdk` cannot be loaded.
+   * The SDK is lazy-imported because not every consumer needs MCP — when
+   * `ai.mcp.enabled` is set but the import fails, we surface an actionable hint
+   * rather than the raw require-stack trace from the failed `import()`.
+   *
+   * The SDK is a regular `dependency` of this package and reaches BOTH consumption
+   * modes: npm-mode consumers resolve it transitively, and CLI-vendored projects get
+   * it merged into their own `package.json` (`convertCloneToVendored()` copies every
+   * upstream dependency, and the import-closure scan additionally backfills bare
+   * specifiers found in dynamic `import()` calls). A failure here is therefore
+   * almost always a RESOLUTION problem — a bundler or test runner with its own
+   * module resolution can fail on the subpath export while plain Node succeeds — not
+   * a genuinely absent package.
+   *
+   * The underlying error goes to the log only, never into the response: it carries
+   * filesystem paths.
    */
   private mcpUnavailable(res: Response, err: Error): void {
     this.logger.error(`MCP SDK not available: ${err.message}`);
     res.status(503).json({
       error:
-        'MCP server unavailable: the @modelcontextprotocol/sdk peer dependency is not installed. ' +
-        'Run `pnpm add @modelcontextprotocol/sdk` (or `npm i @modelcontextprotocol/sdk`) ' +
-        'in your project and restart the server.',
+        `${ErrorCode.SERVICE_UNAVAILABLE} — MCP server unavailable: ` +
+        '@modelcontextprotocol/sdk could not be loaded. It ships as a dependency of ' +
+        '@lenne.tech/nest-server, so this usually means the module could not be resolved ' +
+        'rather than that it is missing; see the server log for the underlying error.',
       statusCode: 503,
     });
   }

package/src/core/modules/ai/interfaces/ai-hook.interface.ts

@@ -38,7 +38,8 @@ export interface AiHookEvent {
  *
  * **Security:** hooks can only ADD restrictions (block calls, redact args) — they
  * cannot relax the permission system. A hook returning no block does not bypass
- * `@Restricted`/`@Roles`/`authorize()`; those still apply.
+ * `@Restricted`/`@Roles`/`securityCheck()`; those still apply on every path
+ * (`authorize()` only runs in plan mode).
  */
 export interface IAiHook {
   /** Unique hook name (for diagnostics and deterministic ordering). */