@lenne.tech/nest-server 11.25.6 → 11.26.0

package/src/core/modules/ai/inputs/core-ai-prompt-hint-create.input.ts

@@ -0,0 +1,26 @@
+import { InputType } from '@nestjs/graphql';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { CoreAiPromptHintInput } from './core-ai-prompt-hint.input';
+
+/**
+ * Input to create a learned AI prompt hint manually. `content` and `trigger` are
+ * required (the learning loop normally creates these automatically).
+ */
+@InputType({ description: 'Input to create a learned AI prompt hint', isAbstract: true })
+@Restricted(RoleEnum.ADMIN)
+export class CoreAiPromptHintCreateInput extends CoreAiPromptHintInput {
+  @UnifiedField({
+    description: 'Guidance text added to the prompt when approved',
+    roles: RoleEnum.ADMIN,
+  })
+  override content: string = undefined;
+
+  @UnifiedField({
+    description: 'Failure-pattern identifier that produced the hint',
+    roles: RoleEnum.ADMIN,
+  })
+  trigger: string = undefined;
+}

package/src/core/modules/ai/inputs/core-ai-prompt-hint.input.ts

@@ -0,0 +1,43 @@
+import { InputType } from '@nestjs/graphql';
+import { IsIn } from 'class-validator';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+
+/**
+ * Input to update a learned AI prompt hint (admins typically approve/reject or edit).
+ */
+@InputType({ description: 'Input to update a learned AI prompt hint', isAbstract: true })
+@Restricted(RoleEnum.ADMIN)
+export class CoreAiPromptHintInput {
+  @UnifiedField({
+    description: 'Guidance text added to the prompt when approved',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+  })
+  content?: string = undefined;
+
+  @UnifiedField({
+    description: 'Whether the hint is active',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  enabled?: boolean = undefined;
+
+  @UnifiedField({
+    description: 'Scope the hint applies to (e.g. a tool name); empty = global',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+  })
+  scope?: string = undefined;
+
+  @UnifiedField({
+    description: "Governance status: 'suggested', 'approved' or 'rejected'",
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    validator: () => [IsIn(['approved', 'rejected', 'suggested'])],
+  })
+  status?: string = undefined;
+}

package/src/core/modules/ai/inputs/core-ai-prompt-update.input.ts

@@ -0,0 +1,42 @@
+import { InputType } from '@nestjs/graphql';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
+import { CoreInput } from '../../../common/inputs/core-input.input';
+import { RoleEnum } from '../../../common/enums/role.enum';
+
+/** Input for updating a {@link CoreAiPrompt}. All fields optional. */
+@InputType({ description: 'Input to update a user prompt' })
+@Restricted(RoleEnum.S_USER)
+export class CoreAiPromptUpdateInput extends CoreInput {
+  @UnifiedField({ description: 'The prompt text', isOptional: true, roles: RoleEnum.S_USER })
+  content?: string = undefined;
+
+  @UnifiedField({ description: 'Description', isOptional: true, roles: RoleEnum.S_USER })
+  description?: string = undefined;
+
+  @UnifiedField({
+    description: 'Whether the prompt is active',
+    isOptional: true,
+    roles: RoleEnum.S_USER,
+    type: () => Boolean,
+  })
+  enabled?: boolean = undefined;
+
+  @UnifiedField({ description: 'Icon hint', isOptional: true, roles: RoleEnum.S_USER })
+  icon?: string = undefined;
+
+  @UnifiedField({ description: 'Display label', isOptional: true, roles: RoleEnum.S_USER })
+  name?: string = undefined;
+
+  @UnifiedField({
+    description: 'Sort order',
+    isOptional: true,
+    roles: RoleEnum.S_USER,
+    type: () => Number,
+  })
+  order?: number = undefined;
+
+  @UnifiedField({ description: 'Visibility scope', isOptional: true, roles: RoleEnum.S_USER })
+  scope?: string = undefined;
+}

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

@@ -0,0 +1,144 @@
+import { InputType } from '@nestjs/graphql';
+import { IsIn, IsString, MaxLength } from 'class-validator';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { JSON } from '../../../common/scalars/json.scalar';
+
+/**
+ * Input for an AI prompt sent from the frontend.
+ */
+@InputType({ description: 'Input for an AI prompt', isAbstract: true })
+@Restricted(RoleEnum.S_USER)
+export class CoreAiPromptInput {
+  /**
+   * Optional id of the AI connection to use (defaults to the configured default).
+   */
+  @UnifiedField({
+    description: 'Id of the AI connection to use (defaults to the configured default)',
+    isOptional: true,
+    roles: RoleEnum.S_USER,
+  })
+  connectionId?: string = undefined;
+
+  /**
+   * Confirm execution of destructive tool actions requested in a previous turn.
+   */
+  @UnifiedField({
+    description: 'Confirm execution of destructive tool actions',
+    isOptional: true,
+    roles: RoleEnum.S_USER,
+    type: () => Boolean,
+  })
+  confirm?: boolean = undefined;
+
+  /**
+   * Optional conversation id for multi-turn continuation.
+   */
+  @UnifiedField({
+    description: 'Conversation id for multi-turn continuation',
+    isOptional: true,
+    roles: RoleEnum.S_USER,
+  })
+  conversationId?: string = undefined;
+
+  /**
+   * Optional structured context the frontend wants the assistant to consider.
+   */
+  @UnifiedField({
+    description: 'Optional structured context for the assistant',
+    isOptional: true,
+    roles: RoleEnum.S_USER,
+    type: () => JSON,
+  })
+  context?: Record<string, any> = undefined;
+
+  /**
+   * Optional client metadata giving the assistant more situational context, e.g.
+   * current URL, previous navigation steps, console logs. Treated as UNTRUSTED
+   * input (size-capped, clearly delimited) to limit prompt-injection risk.
+   */
+  @UnifiedField({
+    description: 'Optional client metadata (current URL, navigation steps, console logs, …)',
+    isOptional: true,
+    roles: RoleEnum.S_USER,
+    type: () => JSON,
+  })
+  metadata?: Record<string, any> = undefined;
+
+  /**
+   * Execution mode. `auto` (default) runs the reactive agent loop; `plan` first
+   * produces a complete plan, validates ALL action permissions up front, and only
+   * then executes (all-or-nothing).
+   */
+  @UnifiedField({
+    description: "Execution mode: 'auto' (reactive loop) or 'plan' (validate all permissions, then execute atomically)",
+    isOptional: true,
+    roles: RoleEnum.S_USER,
+    validator: () => [IsIn(['auto', 'plan'])],
+  })
+  mode?: string = undefined;
+
+  /**
+   * The user's prompt text.
+   */
+  @UnifiedField({
+    description: 'The user prompt text',
+    roles: RoleEnum.S_USER,
+    // IsNotEmpty is auto-applied for required fields by @UnifiedField; only IsString
+    // + MaxLength need to be declared here (the custom validator replaces built-ins).
+    validator: () => [IsString(), MaxLength(50000)],
+  })
+  prompt: string = undefined;
+
+  /**
+   * Client override of the admin confirmation-for-mutating-actions default.
+   * Ignored when the admin has enforced the policy.
+   */
+  @UnifiedField({
+    description: 'Override the admin default for requiring confirmation of mutating actions (ignored when enforced)',
+    isOptional: true,
+    roles: RoleEnum.S_USER,
+    type: () => Boolean,
+  })
+  requireConfirmation?: boolean = undefined;
+
+  /**
+   * When confirming a mutating action (`confirm: true`), persist the consent so the
+   * user does not have to re-confirm the same tool next time. Scope: `'conversation'`
+   * (this thread only), `'user'` (this user, all conversations), `'tenant'` (whole
+   * tenant). Destructive tools are never grantable — they always confirm.
+   */
+  @UnifiedField({
+    description: "Remember the confirmation as a grant: 'conversation', 'user' or 'tenant'",
+    isOptional: true,
+    roles: RoleEnum.S_USER,
+  })
+  rememberDecision?: string = undefined;
+
+  /**
+   * Named agent mode (admin-defined). Restricts the assistant to a curated tool set
+   * and optional model/prompt override for this run (e.g. `'support'`, `'audit'`).
+   * See {@link CoreAiMode}.
+   */
+  @UnifiedField({
+    description: 'Named agent mode (admin-defined; restricts tools / prompts / model)',
+    isOptional: true,
+    roles: RoleEnum.S_USER,
+  })
+  agentMode?: string = undefined;
+
+  /**
+   * Multi-modal attachments for the user prompt (e.g. screenshots, documents).
+   * Forwarded to vision-capable providers; ignored by providers without vision
+   * support. Items are `{ mimeType, dataUrl|url, name? }`.
+   */
+  @UnifiedField({
+    description: 'Multi-modal attachments (images, documents) for the prompt',
+    isOptional: true,
+    roles: RoleEnum.S_USER,
+    type: () => JSON,
+  })
+  attachments?: { dataUrl?: string; mimeType: string; name?: string; url?: string }[] = undefined;
+}

package/src/core/modules/ai/inputs/core-ai-slot-create.input.ts

@@ -0,0 +1,26 @@
+import { InputType } from '@nestjs/graphql';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { CoreAiSlotUpdateInput } from './core-ai-slot-update.input';
+
+/**
+ * Input to create an AI slot (system-prompt building block). `key` and `content`
+ * are required.
+ */
+@InputType({ description: 'Input to create an AI slot (system-prompt building block)', isAbstract: true })
+@Restricted(RoleEnum.ADMIN)
+export class CoreAiSlotCreateInput extends CoreAiSlotUpdateInput {
+  @UnifiedField({
+    description: 'Slot text — supports placeholder tokens; the active registry is served by GET /ai/placeholders',
+    roles: RoleEnum.ADMIN,
+  })
+  override content: string = undefined;
+
+  @UnifiedField({
+    description: "Logical prompt slot key (e.g. 'base', 'permissions', 'anti_hallucination')",
+    roles: RoleEnum.ADMIN,
+  })
+  override key: string = undefined;
+}

package/src/core/modules/ai/inputs/core-ai-slot-update.input.ts

@@ -0,0 +1,65 @@
+import { InputType } from '@nestjs/graphql';
+import { IsIn } from 'class-validator';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+
+/**
+ * Input to update an AI slot (system-prompt building block). All fields optional.
+ */
+@InputType({ description: 'Input to update an AI slot', isAbstract: true })
+@Restricted(RoleEnum.ADMIN)
+export class CoreAiSlotUpdateInput {
+  @UnifiedField({
+    description: "Capability scope: 'all', 'native' or 'emulated'",
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    validator: () => [IsIn(['all', 'emulated', 'native'])],
+  })
+  capability?: string = undefined;
+
+  @UnifiedField({
+    description: 'Slot text — supports placeholder tokens; the active registry is served by GET /ai/placeholders',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+  })
+  content?: string = undefined;
+
+  @UnifiedField({
+    description: 'Admin-facing description of the slot',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+  })
+  description?: string = undefined;
+
+  @UnifiedField({
+    description: 'Whether the slot is included in the prompt',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  enabled?: boolean = undefined;
+
+  @UnifiedField({
+    description: "Logical prompt slot key (e.g. 'base', 'permissions', 'anti_hallucination')",
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+  })
+  key?: string = undefined;
+
+  @UnifiedField({
+    description: "Locale (e.g. 'en', 'de'); empty = all languages",
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+  })
+  locale?: string = undefined;
+
+  @UnifiedField({
+    description: 'Assembly order (ascending)',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  order?: number = undefined;
+}

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

@@ -0,0 +1,74 @@
+import type { AiToolContext, IAiTool } from './ai-tool.interface';
+import type { CoreAiPromptInput } from '../inputs/core-ai-prompt.input';
+import type { CoreAiResponse } from '../models/core-ai-response.model';
+
+/**
+ * Decision returned by a `preToolUse` hook. `block: true` aborts the tool call
+ * with a translated error; `block: false` (or undefined) lets it run. Returning
+ * `args` replaces the original tool arguments — useful for input sanitization or
+ * PII redaction. Returning nothing is equivalent to `{ block: false }`.
+ */
+export interface AiHookPreDecision {
+  /** Replace the tool arguments before execution. */
+  args?: Record<string, any>;
+  /** Block the tool call entirely. */
+  block?: boolean;
+  /** Human-readable reason for blocking — surfaced as the tool error. */
+  reason?: string;
+}
+
+/**
+ * Lifecycle event payload passed to all hook methods.
+ */
+export interface AiHookEvent {
+  /** The full prompt input the orchestrator is running. */
+  input: CoreAiPromptInput;
+  /** The user context (currentUser, serviceOptions, language). */
+  toolContext: AiToolContext;
+}
+
+/**
+ * Lifecycle hook a project can register to observe or gate the agent loop without
+ * forking the orchestrator. Hooks are dispatched in registration order; the first
+ * hook returning `{ block: true }` aborts the tool call.
+ *
+ * Implement any subset of the methods. Register the hook as a NestJS provider that
+ * extends {@link AiHookBase} — it self-registers in the global {@link AiHookRegistry}
+ * on module init.
+ *
+ * **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.
+ */
+export interface IAiHook {
+  /** Unique hook name (for diagnostics and deterministic ordering). */
+  readonly name: string;
+
+  /**
+   * Called BEFORE a tool runs. Can block the call, modify the args, or just
+   * observe (return undefined). Errors thrown here are swallowed — hooks are
+   * best-effort and must not crash a prompt run.
+   */
+  preToolUse?(
+    call: { arguments: Record<string, any>; name: string },
+    tool: IAiTool,
+    event: AiHookEvent,
+  ): Promise<AiHookPreDecision | undefined> | AiHookPreDecision | undefined;
+
+  /**
+   * Called AFTER a tool ran (success or failure). Pure notification — the result
+   * is not modifiable. Useful for audit/webhook/metrics integration.
+   */
+  postToolUse?(
+    call: { arguments: Record<string, any>; name: string },
+    tool: IAiTool,
+    result: { result: unknown; success: boolean },
+    event: AiHookEvent,
+  ): Promise<void> | void;
+
+  /** Called at the start of a prompt run, before any LLM call. */
+  sessionStart?(event: AiHookEvent): Promise<void> | void;
+
+  /** Called at the end of a prompt run, with the final response (or partial state). */
+  stop?(response: CoreAiResponse, event: AiHookEvent): Promise<void> | void;
+}

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

@@ -0,0 +1,49 @@
+import { IAiTool } from './ai-tool.interface';
+
+/**
+ * Runtime context passed to every placeholder resolver. Mirrors the data a
+ * prompt build has on hand (current user, in-scope tools, etc.) — keep it
+ * narrow on purpose so resolvers stay testable and don't reach into the
+ * orchestrator's internals.
+ */
+export interface AiPlaceholderContext {
+  /** Pre-computed catalog string (formatted tool list with parameter schema). */
+  toolCatalog?: string;
+  /** Tools the current user is allowed to use this turn. */
+  tools?: IAiTool[];
+  /** Current user (may be undefined for system contexts). */
+  user?: { id?: string; roles?: string[]; [key: string]: any };
+}
+
+/**
+ * A placeholder registered with {@link CoreAiPlaceholderRegistry}.
+ *
+ * Placeholders are referenced in slot / prompt content via `{{name}}`. At
+ * render time the registry calls each placeholder's {@link resolve} with the
+ * current context and inlines the returned string. Unknown placeholder names
+ * render as the empty string (forward-compatible — old content survives
+ * placeholder removal without crashing).
+ */
+export interface IAiPlaceholder {
+  /**
+   * Human-readable description for the admin UI (shown next to the name in
+   * the placeholder helper sidebar). Keep it short — one sentence.
+   */
+  description: string;
+  /** Optional example value rendered in the UI tooltip. */
+  example?: string;
+  /** Placeholder name without curly braces (e.g. `'roles'` matches `{{roles}}`). */
+  name: string;
+  /**
+   * Compute the placeholder's string value for the current context. Sync or
+   * async; missing context values should yield `''` rather than throw.
+   */
+  resolve(ctx: AiPlaceholderContext): Promise<string> | string;
+}
+
+/** Public metadata shape returned by the placeholders API (no `resolve`). */
+export interface AiPlaceholderInfo {
+  description: string;
+  example?: string;
+  name: string;
+}

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

@@ -0,0 +1,112 @@
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { ServiceOptions } from '../../../common/interfaces/service-options.interface';
+
+/**
+ * Execution context handed to a tool when the LLM invokes it.
+ *
+ * The {@link serviceOptions} carry the authenticated user, so tools that call a
+ * {@link CrudService} run with the caller's permissions — the LLM can never
+ * escalate beyond what the user is allowed to do.
+ */
+export interface AiToolContext {
+  /** Authenticated user (shortcut for `serviceOptions.currentUser`). */
+  currentUser?: { [key: string]: any; id: string; roles?: string[] };
+
+  /** Accept-Language of the original request. */
+  language?: string;
+
+  /**
+   * ServiceOptions to forward to downstream services. Contains `currentUser`,
+   * so authorization, field filtering and tenant context are preserved.
+   */
+  serviceOptions: ServiceOptions;
+}
+
+/**
+ * Result of a tool's pre-flight authorization check ({@link IAiTool.authorize}).
+ */
+export interface AiToolAuthorization {
+  /** Whether the user may run the tool with these arguments. */
+  allowed: boolean;
+
+  /** Optional human-readable reason when not allowed. */
+  reason?: string;
+}
+
+/**
+ * Normalized result of a tool execution that is fed back to the LLM.
+ */
+export interface AiToolResult {
+  /** Structured payload returned to the model (and optionally the frontend). */
+  data?: unknown;
+
+  /** Optional human-readable message. */
+  message?: string;
+
+  /** Whether the tool ran successfully. */
+  success: boolean;
+}
+
+/**
+ * A backend capability the LLM may call — the "MCP-like" building block.
+ *
+ * Tools self-register in the global {@link AiToolRegistry} (typically from
+ * `onModuleInit`), so projects can add or override tools from any module without
+ * DI-scope constraints. Implement this interface directly or extend the
+ * convenience base class {@link AiTool}.
+ *
+ * ## Security
+ *
+ * - {@link roles} is a first-line visibility filter: tools the user may not use
+ *   are never even offered to the LLM.
+ * - The TRUE authorization gate is {@link execute}: tools must route data access
+ *   through a {@link CrudService} using `context.serviceOptions` so `@Restricted`,
+ *   `securityCheck()` and field filtering still apply.
+ */
+export interface IAiTool {
+  /** Description shown to the LLM — the primary signal for when to use the tool. */
+  readonly description: string;
+
+  /**
+   * 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`.
+   */
+  readonly destructive?: boolean;
+
+  /**
+   * Whether the tool changes data (create/update/delete). Confirmation for
+   * 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.
+   */
+  readonly mutating?: boolean;
+
+  /**
+   * Optional pre-flight authorization check used by plan mode (and recommended
+   * for data-level checks). MUST NOT mutate anything — it only decides whether
+   * the user may run the tool with these arguments (e.g. load the target record
+   * and verify ownership). When omitted, only the registry role filter applies.
+   */
+  authorize?(args: Record<string, any>, context: AiToolContext): Promise<AiToolAuthorization | boolean>;
+
+  /** Unique tool name (snake_case recommended, stable across versions). */
+  readonly name: string;
+
+  /** JSON schema of the tool's input arguments (JSON-schema shape). */
+  readonly parameters: Record<string, any>;
+
+  /**
+   * Roles required to see and run the tool. Use {@link RoleEnum.S_EVERYONE} for
+   * public tools, {@link RoleEnum.S_USER} for any authenticated user, or real
+   * roles (e.g. `RoleEnum.ADMIN`) for privileged tools.
+   */
+  readonly roles: (RoleEnum | string)[];
+
+  /**
+   * Execute the tool. MUST enforce real authorization by routing through a
+   * service with `context.serviceOptions`.
+   */
+  execute(args: Record<string, any>, context: AiToolContext): Promise<AiToolResult | unknown>;
+}