@lenne.tech/nest-server 11.25.6 → 11.26.1

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

@@ -1045,10 +1045,267 @@ export interface ICorsConfig {
   enabled?: boolean;
 }
 
+/**
+ * Bootstrap configuration for a default AI connection.
+ *
+ * When set and no connection exists yet, the AI module seeds this as the default
+ * connection on first start. The database remains the source of truth afterwards;
+ * connections are managed at runtime (admin CRUD / frontend settings). Prefer
+ * `apiKeyEnv` over an inline `apiKey` so no secret is committed to config.
+ */
+export interface IAiDefaultConnection {
+  /** Inline plaintext API key (encrypted on seed). Prefer `apiKeyEnv` instead. */
+  apiKey?: string;
+
+  /** Name of an environment variable holding the API key (e.g. 'AI_API_KEY'). */
+  apiKeyEnv?: string;
+
+  /** Base URL of the OpenAI-compatible endpoint. */
+  baseUrl: string;
+
+  /** Capability tags (free-form, e.g. 'analysis', 'vision'). */
+  capabilities?: string[];
+
+  /** Default maximum number of tokens for completions. */
+  defaultMaxTokens?: number;
+
+  /** Default sampling temperature. */
+  defaultTemperature?: number;
+
+  /** Human-readable description. */
+  description?: string;
+
+  /** Model id sent to the backend (e.g. 'gpt-oss-120b'). */
+  model: string;
+
+  /** Human-readable connection name. */
+  name: string;
+
+  /** Provider type (default 'openai-compatible'). */
+  providerType?: string;
+
+  /**
+   * Native JSON / structured-output support. Omit to auto-detect by probing the
+   * endpoint (explicit `true`/`false` is authoritative and never probed).
+   */
+  supportsJsonResponse?: boolean;
+
+  /**
+   * Native function/tool-calling support. Omit to auto-detect by probing the
+   * endpoint (explicit `true`/`false` is authoritative and never probed).
+   */
+  supportsNativeTools?: boolean;
+
+  /** Whether the model supports image input. */
+  supportsVision?: boolean;
+}
+
+/**
+ * Rate-limit configuration for AI prompts (presence implies enabled).
+ */
+export interface IAiRateLimit {
+  /** Explicitly disable while keeping the config (default: enabled when present). */
+  enabled?: boolean;
+
+  /** Maximum number of prompts per window per user. @default 20 */
+  max?: number;
+
+  /** Window length in seconds. @default 60 */
+  windowSeconds?: number;
+}
+
+/**
+ * Configuration for the AI assistant module (presence implies enabled).
+ *
+ * The AI module adds a prompt orchestrator with emulated/native tool calling and
+ * database-backed LLM connections (managed at runtime by admins). Omit the block
+ * to disable the module entirely; set `enabled: false` to keep config but disable.
+ *
+ * @example
+ * ```typescript
+ * ai: {
+ *   maxIterations: 5,
+ *   rateLimit: { max: 20, windowSeconds: 60 },
+ *   defaultConnection: {
+ *     name: 'Default LLM',
+ *     baseUrl: 'https://llm.example.com/v1',
+ *     model: 'gpt-oss-120b',
+ *     apiKeyEnv: 'AI_API_KEY',
+ *   },
+ * }
+ * ```
+ */
+export interface IAi {
+  /**
+   * Optional SSRF allowlist for connection base URLs. When set (non-empty), the
+   * provider only sends requests to these hosts (matched by `host` incl. port, or
+   * bare `hostname`); unset → permissive (so local providers like Ollama on localhost
+   * work out of the box). `baseUrl` is admin-only, so this guards a compromised or
+   * misconfigured admin, not end-user input.
+   * @example ['llm.example.com', 'localhost:11434']
+   */
+  allowedBaseUrlHosts?: string[];
+
+  /**
+   * Persist an audit record (`aiInteractions`) for every prompt run (admin-readable).
+   * @default false
+   */
+  audit?: boolean;
+
+  /**
+   * Token/prompt budgets for AI prompts, enforced before a run (HTTP 429 + translated
+   * message). Requires `audit` (usage is read from `aiInteractions`). All limits are
+   * optional — a missing or `0` limit means unlimited (only the LLM's own limit then
+   * applies). These are the DEFAULTS; admins can override per user/tenant at runtime
+   * (`aiBudgetLimits`, `CoreAiBudgetService`).
+   */
+  budget?: {
+    /** Reset window. @default 'day' */
+    period?: 'day' | 'month' | 'none';
+    /** Default limit applied to a whole tenant (sum of all its users). */
+    tenant?: { maxPrompts?: number; maxTokens?: number };
+    /** Default limit applied per user. */
+    user?: { maxPrompts?: number; maxTokens?: number };
+  };
+
+  /**
+   * Confirmation policy for mutating tool actions (create/update/delete).
+   * `destructive` tools always require confirmation regardless of this policy.
+   */
+  confirmation?: {
+    mutating?: {
+      /** Admin default: require confirmation for mutating actions. @default false */
+      default?: boolean;
+      /** When true, the client cannot override the default (always require). @default false */
+      enforced?: boolean;
+    };
+  };
+
+  /**
+   * System documentation injected into the system prompt to inform the LLM
+   * (official docs, domain rules, API description). For dynamic/RAG docs, override
+   * `CoreAiPromptBuilderService.getDocumentation()` instead.
+   */
+  documentation?: string;
+
+  /** Optional one-time seed for a default connection (see {@link IAiDefaultConnection}). */
+  defaultConnection?: IAiDefaultConnection;
+
+  /**
+   * Default execution mode when the client does not specify one.
+   * `auto` (reactive loop) or `plan` (validate all permissions, then execute atomically).
+   * @default 'auto'
+   */
+  defaultMode?: 'auto' | 'plan';
+
+  /** Explicitly disable while keeping the config (default: enabled when present). */
+  enabled?: boolean;
+
+  /**
+   * Pass-phrase used to derive the AES-256-GCM key for encrypting connection API
+   * keys. Falls back to `NSC__AI__ENCRYPTION_SECRET` / `SECRETS_ENCRYPTION_KEY`.
+   * MUST be set to a random 32+ char value in production.
+   */
+  encryptionSecret?: string;
+
+  /**
+   * Fallback total context window (input + output tokens) used to budget the
+   * assembled session messages when a connection has no `contextWindow` set. When the
+   * conversation (per user/session) would overflow, the oldest history turns are
+   * dropped and oversized payloads truncated before the LLM call.
+   * @default 8192
+   */
+  contextWindow?: number;
+
+  /**
+   * Optional config for the `ClaudeCliProvider` (LLM backend that invokes a local
+   * `claude` CLI binary). Only consumed when a connection's `providerType` is
+   * `claude-cli` or the provider is registered explicitly.
+   */
+  claudeCli?: {
+    /** Path/name of the Claude CLI binary. @default 'claude' */
+    bin?: string;
+    /** Extra CLI flags appended verbatim to every invocation (admin-only). */
+    extraArgs?: string[];
+    /** Optional `--budget` cap (USD) appended to every invocation. */
+    maxBudgetUsd?: number;
+  };
+
+  /**
+   * LLM-driven context compaction: when a session would overflow the connection's
+   * context window, the oldest non-system/non-last turns are summarized by a single
+   * LLM call (via the same connection's provider) and REPLACED by a one-paragraph
+   * summary system message — instead of being dropped. Falls back to the hard trim
+   * path on any error. Disable with `false`.
+   * @default true
+   */
+  compaction?: boolean;
+
+  /**
+   * Defer the parameter schemas of tools out of the system prompt. With many tools
+   * the JSON-Schema catalog dominates the prompt; with `deferToolSchemas: true`
+   * the system prompt only lists tool names + short descriptions and the built-in
+   * `search_tools` meta-tool lets the model fetch a single tool's schema on demand.
+   * @default false
+   */
+  deferToolSchemas?: boolean;
+
+  /** Maximum number of agent-loop iterations (tool round-trips). @default 5 */
+  maxIterations?: number;
+
+  /** Maximum characters of a tool-results payload fed back to the model. @default 12000 */
+  maxToolResultChars?: number;
+
+  /**
+   * Governed self-improvement loop for the system prompt. The orchestrator records
+   * failure signals (tool errors, not-permitted calls); recurring patterns become
+   * learned hints. By default hints are `suggested` and only affect the prompt once an
+   * admin approves them; `autoApply` auto-approves them. Learning never relaxes
+   * permissions — hints only add textual guidance.
+   */
+  promptLearning?: {
+    /** Auto-approve learned hints instead of requiring admin approval. @default false */
+    autoApply?: boolean;
+    /** Enable the learning loop. @default true (when an `ai` block is present) */
+    enabled?: boolean;
+    /** Occurrences before a suggested hint is auto-approved (with `autoApply`). @default 1 */
+    minOccurrences?: number;
+  };
+
+  /**
+   * Expose the tool registry as an MCP server at `/ai/mcp` (Streamable HTTP) for
+   * external MCP clients. Requires `@modelcontextprotocol/sdk`. Boolean shorthand.
+   *
+   * `oauth: true` additionally enables the OAuth 2.1 layer (dynamic client
+   * registration + PKCE) so generic MCP clients can authenticate; mount the OAuth
+   * router in `main.ts` via `mountAiMcpOAuth(app)` (see INTEGRATION-CHECKLIST).
+   * Without it, MCP authenticates via the existing Bearer/session token.
+   * @default false
+   */
+  mcp?: boolean | { enabled?: boolean; oauth?: boolean; oauthSecret?: string };
+
+  /** Rate limiting for prompts. */
+  rateLimit?: IAiRateLimit;
+
+  /** Base system prompt prepended to every conversation. */
+  systemPrompt?: string;
+}
+
 /**
  * Options for the server
  */
 export interface IServerOptions {
+  /**
+   * Configuration for the AI assistant module.
+   *
+   * Presence implies enabled (omit to disable, `{ enabled: false }` to keep config
+   * but disable). Adds the prompt orchestrator, the tool registry and admin-managed
+   * database-backed LLM connections.
+   *
+   * @see IAi
+   */
+  ai?: boolean | IAi;
+
   /**
    * Base URL of the frontend/app application.
    *
@@ -2866,6 +3123,61 @@ interface IBetterAuthWithPasskey extends IBetterAuthBase {
  * @since 11.22.0
  */
 export interface ICoreModuleOverrides {
+  /**
+   * Override AI module collaborators with project-specific subclasses.
+   *
+   * - `budgetService` must extend `CoreAiBudgetService`
+   * - `connectionResolver` must extend `CoreAiConnectionResolverService`
+   * - `connectionService` must extend `CoreAiConnectionService`
+   * - `controller` must extend `CoreAiController`
+   * - `conversationService` must extend `CoreAiConversationService`
+   * - `interactionService` must extend `CoreAiInteractionService`
+   * - `mcpClientService` must extend `CoreAiMcpClientService`
+   * - `modeService` must extend `CoreAiModeService`
+   * - `placeholderRegistry` must extend `CoreAiPlaceholderRegistry`
+   * - `preferenceService` must extend `CoreAiConnectionPreferenceService`
+   * - `promptBuilder` must extend `CoreAiPromptBuilderService`
+   * - `promptHintService` must extend `CoreAiPromptHintService`
+   * - `promptService` must extend `CoreAiPromptService`
+   * - `resolver` must extend `CoreAiResolver` (re-declare GraphQL decorators)
+   * - `service` must extend `CoreAiService`
+   * - `slotService` must extend `CoreAiSlotService`
+   * - `toolGrantService` must extend `CoreAiToolGrantService`
+   * - `toolPolicyService` must extend `CoreAiToolPolicyService`
+   *
+   * @example
+   * ```typescript
+   * {
+   *   ai: {
+   *     service: MyAiService,
+   *     resolver: MyAiResolver,
+   *     connectionResolver: MyConnectionResolver,
+   *     slotService: MySlotService,
+   *   },
+   * }
+   * ```
+   */
+  ai?: {
+    budgetService?: Type<any>;
+    connectionResolver?: Type<any>;
+    connectionService?: Type<any>;
+    controller?: Type<any>;
+    conversationService?: Type<any>;
+    interactionService?: Type<any>;
+    mcpClientService?: Type<any>;
+    modeService?: Type<any>;
+    placeholderRegistry?: Type<any>;
+    preferenceService?: Type<any>;
+    promptBuilder?: Type<any>;
+    promptHintService?: Type<any>;
+    promptService?: Type<any>;
+    resolver?: Type<any>;
+    service?: Type<any>;
+    slotService?: Type<any>;
+    toolGrantService?: Type<any>;
+    toolPolicyService?: Type<any>;
+  };
+
   /**
    * Override BetterAuth controller and/or resolver.
    *

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

@@ -0,0 +1,220 @@
+# AI Module Integration Checklist
+
+## Reference Implementation
+
+- Local (npm): `node_modules/@lenne.tech/nest-server/src/server/modules/ai/`
+- Local (vendor): `src/server/modules/ai/` in this repo
+- GitHub: https://github.com/lenneTech/nest-server/tree/develop/src/server/modules/ai
+
+## Overview
+
+The AI module is **auto-registered by `CoreModule.forRoot()`** when an `ai` config
+block is present (presence implies enabled). You only need to:
+
+1. add the `ai` config block,
+2. set an encryption secret,
+3. create one or more AI tools (project-specific capabilities),
+4. register your tools in a module.
+
+No manual `CoreAiModule` import is required for the default setup.
+
+## Required Steps
+
+### 1. Configure the module (`config.env.ts`)
+
+Add an `ai` block to each relevant environment:
+
+```typescript
+ai: {
+  encryptionSecret: process.env.NSC__AI__ENCRYPTION_SECRET, // REQUIRED in prod (32+ chars)
+  maxIterations: 5,
+  rateLimit: { max: 20, windowSeconds: 60 },
+  defaultConnection: {                 // optional one-time seed
+    name: 'Default LLM',
+    baseUrl: process.env.AI_BASE_URL,   // any OpenAI-compatible endpoint
+    model: process.env.AI_MODEL,
+    apiKeyEnv: 'AI_API_KEY',            // prefer env over inline apiKey
+    supportsNativeTools: false,         // set per the backend's actual support
+  },
+}
+```
+
+**WHY the encryption secret:** connection API keys are AES-256-GCM encrypted at
+rest. Without `ai.encryptionSecret` / `NSC__AI__ENCRYPTION_SECRET` /
+`SECRETS_ENCRYPTION_KEY`, an insecure development default is used (logged as a
+warning) in non-production environments. In **production/staging the app refuses to
+boot** when AI is enabled but no secret is set (mirrors the email/cookie production
+guards) — so a missing secret can never silently ship. The same applies to the MCP
+OAuth signing secret when `ai.mcp.oauth` is enabled.
+
+### 2. Set the LLM API key (environment)
+
+```bash
+# .env
+AI_API_KEY=...
+AI_BASE_URL=https://your-openai-compatible-endpoint/v1
+NSC__AI__ENCRYPTION_SECRET=<random 32+ char string>
+```
+
+Admins can also store/rotate keys at runtime via the connection CRUD endpoints
+(stored encrypted; env is only the fallback).
+
+### 3. Create AI tools — REQUIRED for the assistant to do anything domain-specific
+
+> **AI agents / new integrators read this first:** the AI module has **no automatic
+> access to your domain models**. Without explicitly registered tools, every domain
+> question (e.g. "show me the latest orders", "find user X") gets the answer
+> _"I don't have a tool to do that"_ — that's the LLM correctly reporting its
+> capabilities, NOT a bug. **You must write a tool for every domain operation that
+> should be reachable from chat.**
+
+**Create:** `src/server/modules/ai/tools/<your>.tool.ts`
+**Copy from:** the reference tools shipped at
+`node_modules/@lenne.tech/nest-server/src/server/modules/ai/tools/` (`find-users.tool.ts`,
+`get-user.tool.ts`, `delete-user.tool.ts`, `update-user-job-title.tool.ts`) — those
+demonstrate read / restricted-read / destructive-write / mutating-write patterns.
+
+When copying:
+
+- Replace relative framework imports `'../../../../core/...'` with the npm specifier
+  `'@lenne.tech/nest-server'`.
+- Adjust the relative path to your own services (e.g. `'../../user/user.service'`
+  becomes `'../user/user.service'` if you copy `tools/` one level shallower; the
+  reference structure assumes `tools/` is a sub-folder of `ai/`).
+- For each tool: declare `name` / `description` / `parameters` (JSON-Schema) /
+  `roles`; flag mutating ones with `mutating: true` and irreversible ones with
+  `destructive: true`.
+- Implement `execute(args, context)` by **always** routing through a `CrudService`
+  with `context.serviceOptions` — NOT directly through `Model.find()` etc.
+  CrudService preserves the caller's `@Restricted` / `@Roles` / `securityCheck()`
+  guarantees. Direct Model access bypasses the permission layer and IS a security
+  bug.
+
+### 4. Register your tools in a module — REQUIRED
+
+**Create:** `src/server/modules/ai/ai-tools.module.ts` (copy from the framework
+reference at `node_modules/@lenne.tech/nest-server/src/server/modules/ai/ai-tools.module.ts`)
+and import it in `server.module.ts`:
+
+```typescript
+// server.module.ts → imports: [ … , AiToolsModule ]
+```
+
+Each tool subclass listed in the module's `providers: []` self-registers in the
+global `AiToolRegistry` via the `AiTool` base class. The registry is provided
+globally by the auto-registered `CoreAiModule`, so your module only needs to
+import whatever services your tools depend on (e.g. `UserModule`).
+
+A consumer project without `AiToolsModule` (or with an empty `providers: []`)
+will boot fine — the AI just won't have any domain tools to call.
+
+### 5. (Optional) Override collaborators
+
+For custom behaviour, pass subclasses via `CoreModule.forRoot()`:
+
+```typescript
+CoreModule.forRoot(envConfig, {
+  ai: { service: MyAiService, resolver: MyAiResolver, promptBuilder: MyPromptBuilder },
+});
+```
+
+When overriding the resolver, **re-declare all GraphQL decorators**
+(`@Mutation`/`@Query`/`@Roles`) — the schema is built from decorators at compile
+time.
+
+## Advanced configuration (optional)
+
+```typescript
+ai: {
+  defaultMode: 'auto',                 // or 'plan' (validate all permissions, then execute atomically)
+  documentation: '…',                  // system docs injected into the prompt (or override getDocumentation())
+  confirmation: { mutating: { default: false, enforced: false } }, // require confirmation for create/update/delete
+  audit: true,                         // persist runs to aiInteractions (required for budget)
+  budget: {                            // per-user/tenant token limits (defaults; admins override per user/tenant)
+    period: 'day',                     // 'day' | 'month' | 'none'
+    user: { maxTokens: 50000 },        // 0/undefined = unlimited
+    tenant: { maxTokens: 2000000 },
+  },
+  contextWindow: 8192,                 // fallback when a connection has no auto-detected window
+  maxToolResultChars: 12000,           // cap tool-results fed back to the model
+  promptLearning: { autoApply: false },// governed self-improvement (admins approve learned hints)
+  mcp: { oauth: true, oauthSecret: process.env.NSC__AI__ENCRYPTION_SECRET },
+}
+```
+
+- **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.
+- **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 —
+  admins customize any slot via `aiSlots` (`/ai/slots`, tenant-scoped) and review the
+  learned hints the system records on tool failures via `aiPromptHints` (`/ai/prompt-hints`).
+  Both are `@Roles(ADMIN)`; build an admin UI with the `useLtAiAdmin` composable
+  (`listEffectiveSlots` returns framework defaults + tenant overrides + custom slots with
+  `isSystem`/`isOverride` flags; `resetSlot` undoes an override). Hints never relax
+  permissions.
+- **User prompts ("Vorlagen"):** users author re-usable short prompts for themselves
+  (private) or their tenant (public) via `aiPrompts` (`/ai/prompts`, `useLtAiPrompts`).
+  Inserted into the chat input by a picker.
+- **Placeholders:** `{{placeholder}}` tokens in both system slots AND user prompts are
+  resolved at run time by `CoreAiPlaceholderRegistry`. The current list is served via
+  `GET /ai/placeholders` (`useLtAiPlaceholders`) — your slot/prompt editors should render
+  it dynamically so project-added placeholders show up without a frontend change. Register
+  project-specific placeholders via `placeholderRegistry.register({ name, description, resolve })`.
+- **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.
+
+### MCP server (only when `ai.mcp.enabled` or `ai.mcp` is truthy)
+
+**Install the MCP SDK** in your project:
+
+```bash
+pnpm add @modelcontextprotocol/sdk
+# or: npm install @modelcontextprotocol/sdk
+```
+
+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.
+
+### MCP OAuth 2.1 (only when `ai.mcp.oauth` is enabled)
+
+**Edit `main.ts`** (after `app.init()`):
+
+```typescript
+import { mountAiMcpOAuth } from '@lenne.tech/nest-server';
+await mountAiMcpOAuth(app, { baseUrl: process.env.BASE_URL });
+```
+
+Override `CoreAiMcpOAuthService.authorizeConsent()` with your login/consent UI (the only
+browser-interactive step). All other OAuth pieces (tokens, PKCE, stores) are built in.
+
+## Verification Checklist
+
+- [ ] Build succeeds (`pnpm run build`)
+- [ ] Tests pass (`pnpm test`)
+- [ ] `findAiConnections` / `getAiConnection` etc. are admin-only and never return `apiKeyEncrypted`
+- [ ] A created connection's `hasApiKey` is `true`, the key is stored encrypted
+- [ ] `aiPrompt` works for an authenticated user
+- [ ] With multiple connections, resolution honors the chain (default → tenant → user → client → enforced)
+- [ ] `aiAvailableConnections` returns a non-sensitive list (no `apiKey`/`baseUrl`) flagging `selected`/`locked`
+- [ ] `aiSetUserConnection` rejects a connection not available to the caller's tenant
+- [ ] With zero connections, `aiPrompt` returns a denied "unavailable" response (no crash)
+- [ ] Your tools appear in `AiToolRegistry.all()` and are role-filtered correctly
+- [ ] Tools route through `CrudService` (no raw `.lean()`/aggregate results sent to the LLM)
+
+## Common Mistakes
+
+| Mistake                                       | Symptom                                                       | Fix                                                       |
+| --------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------- |
+| No `ai` config block                          | Module not loaded, `aiPrompt` missing from schema             | Add an `ai` block (presence implies enabled)              |
+| No encryption secret in prod                  | **App refuses to boot** (throws); dev/local only warns        | Set `NSC__AI__ENCRYPTION_SECRET` (32+ chars)              |
+| Encryption secret changed after keys stored   | Boot logs "key(s) could not be decrypted"; those prompts fail | Re-enter the API key for the listed connections           |
+| Tool returns `.lean()`/aggregate data         | `@Restricted` fields leak into the LLM context                | Route through `CrudService` with `context.serviceOptions` |
+| Tool not registered                           | Tool never offered to the LLM                                 | Declare it as a provider in a module (extends `AiTool`)   |
+| Overridden resolver method missing decorators | Method absent from GraphQL schema                             | Re-declare `@Mutation`/`@Query`/`@Roles` in the override  |
+| Storing a real API key in `config.env.ts`     | Secret committed to the repo                                  | Use `apiKeyEnv` or the runtime connection CRUD            |