@lenne.tech/nest-server 11.32.2 → 11.32.3

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.2",
+  "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.

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

@@ -111,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

package/src/core/modules/ai/inputs/core-ai-connection.input.ts

@@ -1,4 +1,5 @@
 import { InputType } from '@nestjs/graphql';
+import { IsInt, Min } from 'class-validator';
 
 import { Restricted } from '../../../common/decorators/restricted.decorator';
 import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
@@ -72,6 +73,7 @@ export class CoreAiConnectionInput {
     isOptional: true,
     roles: RoleEnum.ADMIN,
     type: () => Number,
+    validator: (options) => [IsInt(options), Min(1, options)],
   })
   contextWindow?: number = undefined;
 

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

@@ -69,9 +69,21 @@ export interface IAiTool {
 
   /**
    * Whether the tool performs a destructive/irreversible action (delete, bulk
-   * update, payment, …). Destructive tools always require confirmation: they are
-   * NOT executed until the prompt is re-sent with `confirm: true`; the first
-   * response lists them as `pendingActions` with `requiresConfirmation: true`.
+   * update, payment, …). In the CHAT orchestrator destructive tools always require
+   * confirmation: they are NOT executed until the prompt is re-sent with
+   * `confirm: true`; the first response lists them as `pendingActions` with
+   * `requiresConfirmation: true`.
+   *
+   * **No confirmation gate over MCP.** `CoreAiMcpService.mcpCallTool` consults
+   * neither this flag nor {@link IAiTool.mutating}, so a destructive tool invoked
+   * through `/ai/mcp` executes IMMEDIATELY, on the first call. This flag is
+   * therefore a chat-orchestrator contract, not a global execution barrier. The
+   * barriers that DO hold on every path are the registry role filter ({@link
+   * IAiTool.roles}, applied by `forUser()` 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. Expose MCP only to clients you trust
+   * to obtain user consent themselves.
    */
   readonly destructive?: boolean;
 
@@ -80,6 +92,9 @@ export interface IAiTool {
    * mutating tools is governed by the `ai.confirmation` policy (admin default,
    * optionally client-overridable, optionally enforced). `destructive` is the
    * stronger flag and always requires confirmation regardless of policy.
+   *
+   * Same MCP caveat as {@link IAiTool.destructive}: the confirmation policy is not
+   * evaluated on the `/ai/mcp` path at all.
    */
   readonly mutating?: boolean;
 

package/src/core/modules/ai/services/core-ai-connection.service.ts

@@ -32,6 +32,29 @@ import { AI_CONNECTION_CLASS, AI_CONNECTION_MODEL } from '../core-ai.constants';
  */
 export { AI_CONNECTION_CLASS, AI_CONNECTION_MODEL } from '../core-ai.constants';
 
+/**
+ * Minimal shape of a persisted (lean) connection document that the boot-time drift
+ * check needs to build a provider for a probe. It mirrors the fields
+ * {@link CoreAiConnectionService.resolve} reads, declared locally so the drift check can
+ * use the bulk `find()` result directly (no per-connection re-read / N+1).
+ */
+type ResolvableConnectionDoc = {
+  _id: unknown;
+  apiKeyEncrypted?: string;
+  apiKeyEnv?: string;
+  baseUrl: string;
+  contextWindow?: number;
+  defaultMaxTokens?: number;
+  defaultTemperature?: number;
+  defaultUserMaxPeriod?: string;
+  defaultUserMaxTokens?: number;
+  model: string;
+  name: string;
+  providerType?: string;
+  supportsJsonResponse?: boolean;
+  supportsNativeTools?: boolean;
+};
+
 /**
  * CRUD service for {@link CoreAiConnection} — the database-backed LLM
  * configuration. Admin-only (enforced by the model's `@Restricted(ADMIN)` plus
@@ -75,6 +98,9 @@ export class CoreAiConnectionService
   async onModuleInit(): Promise<void> {
     await this.seedDefaultConnection();
     await this.assertStoredKeysDecryptable();
+    // Best-effort, non-blocking: probe endpoints and warn on capability drift. Never
+    // awaited so a slow/unreachable endpoint cannot delay boot.
+    void this.warnOnCapabilityDrift();
   }
 
   /**
@@ -142,6 +168,115 @@ export class CoreAiConnectionService
     }
   }
 
+  /**
+   * Opt-in boot self-check (`ai.capabilityDriftCheck`, default OFF): warn when a
+   * connection DECLARES a capability that contradicts what its endpoint actually
+   * reports. Capabilities are auto-detected only for flags left UNDEFINED (create +
+   * lazy runtime path); an EXPLICIT `supportsNativeTools` / `supportsJsonResponse` is
+   * authoritative and is never re-probed by the normal path — so a wrong explicit flag
+   * silently degrades the assistant forever (e.g. `supportsNativeTools: false` on an
+   * endpoint that DOES support native function calling forces fragile emulated
+   * tool-calling, which weaker models do not sustain once the prompt grows).
+   *
+   * To observe the endpoint's REAL capability for a DECLARED flag, it builds the provider
+   * with the flags cleared to `undefined` — otherwise the provider's `detectCapabilities()`,
+   * which probes ONLY undefined flags, would return nothing to compare against (the whole
+   * point of the check) — then diffs the probed booleans against the stored declaration.
+   *
+   * It NEVER changes the stored value (the admin's explicit choice stays authoritative),
+   * NEVER blocks boot (fire-and-forget, all errors swallowed), and issues outbound calls
+   * to the LLM endpoints — hence it is OFF by default and additionally skipped in the
+   * ci/e2e runners. It reads every enabled connection in a single query (no per-connection
+   * re-read). Connections that leave BOTH flags undefined are handled by
+   * {@link detectAndPersistCapabilities} and are skipped here (nothing declared to check).
+   */
+  protected async warnOnCapabilityDrift(): Promise<void> {
+    // Opt-in: a framework boot must not contact third-party endpoints unless asked.
+    if (!ConfigService.get<boolean>('ai.capabilityDriftCheck')) {
+      return;
+    }
+    // Defense in depth: never probe from the integration test runner (real module boot).
+    // The unit runner (NODE_ENV=test) is intentionally NOT excluded so the method stays
+    // unit-testable with a mocked providerFactory — the opt-in flag above already prevents
+    // accidental probing there.
+    if (!this.providerFactory || ['ci', 'e2e'].includes(process.env.NODE_ENV ?? '')) {
+      return;
+    }
+    try {
+      // Single read (no per-connection re-resolve): the full docs carry everything the
+      // provider factory needs, so there is no N+1 findById per connection.
+      const docs = (await this.mainDbModel
+        .find({ enabled: { $ne: false } })
+        .lean()
+        .exec()) as unknown as ResolvableConnectionDoc[];
+      for (const doc of docs) {
+        // Only a connection that DECLARES a capability can drift; undefined flags are
+        // auto-detected on first use, so there is nothing to reconcile here.
+        if (typeof doc.supportsNativeTools !== 'boolean' && typeof doc.supportsJsonResponse !== 'boolean') {
+          continue;
+        }
+        let provider: { detectCapabilities?: () => Promise<{ jsonResponse?: boolean; nativeTools?: boolean }> };
+        try {
+          // Clear the declared flags so detectCapabilities() actually probes them (it
+          // skips any flag that is already a boolean on the connection).
+          const probeConnection: ResolvedAiConnection = {
+            apiKey: this.resolveApiKeyFromDoc(doc) ?? '',
+            baseUrl: doc.baseUrl,
+            contextWindow: doc.contextWindow,
+            defaultMaxTokens: doc.defaultMaxTokens,
+            defaultTemperature: doc.defaultTemperature,
+            defaultUserMaxPeriod: doc.defaultUserMaxPeriod,
+            defaultUserMaxTokens: doc.defaultUserMaxTokens,
+            id: String(doc._id),
+            model: doc.model,
+            name: doc.name,
+            providerType: doc.providerType || 'openai-compatible',
+            supportsJsonResponse: undefined,
+            supportsNativeTools: undefined,
+          };
+          provider = this.providerFactory.create(probeConnection);
+        } catch {
+          continue; // unresolvable / unbuildable — nothing to compare against
+        }
+        if (typeof provider.detectCapabilities !== 'function') {
+          continue;
+        }
+        const detected = await provider.detectCapabilities().catch(() => undefined);
+        if (!detected) {
+          continue; // probe failed (endpoint down / transport error) — not a drift signal
+        }
+        const drift: string[] = [];
+        if (
+          typeof doc.supportsNativeTools === 'boolean' &&
+          typeof detected.nativeTools === 'boolean' &&
+          doc.supportsNativeTools !== detected.nativeTools
+        ) {
+          drift.push(
+            `supportsNativeTools declared ${doc.supportsNativeTools} but the endpoint reports ${detected.nativeTools}`,
+          );
+        }
+        if (
+          typeof doc.supportsJsonResponse === 'boolean' &&
+          typeof detected.jsonResponse === 'boolean' &&
+          doc.supportsJsonResponse !== detected.jsonResponse
+        ) {
+          drift.push(
+            `supportsJsonResponse declared ${doc.supportsJsonResponse} but the endpoint reports ${detected.jsonResponse}`,
+          );
+        }
+        if (drift.length) {
+          this.logger.warn(
+            `AI connection "${doc.name || String(doc._id)}" capability drift: ${drift.join('; ')}. ` +
+              `The declared value is authoritative and was NOT changed — correct it in the admin UI, or clear it to ` +
+              `re-enable auto-detection, so the assistant uses the endpoint's real capabilities.`,
+          );
+        }
+      }
+    } catch (err) {
+      this.logger.warn(`AI capability drift check skipped: ${(err as Error).message}`);
+    }
+  }
+
   /**
    * Create a connection. Encrypts the optional plaintext `apiKey` and keeps the
    * default connection unique.