@lenne.tech/nest-server 11.25.6 → 11.26.0

package/src/core/modules/ai/hooks/ai-hook.registry.ts

@@ -0,0 +1,119 @@
+import { Injectable, Logger } from '@nestjs/common';
+
+import { AiHookEvent, AiHookPreDecision, IAiHook } from '../interfaces/ai-hook.interface';
+import { IAiTool } from '../interfaces/ai-tool.interface';
+import { CoreAiResponse } from '../models/core-ai-response.model';
+
+/**
+ * Global registry of AI lifecycle hooks (PreToolUse / PostToolUse / SessionStart /
+ * Stop). Hooks are dispatched in registration order — the first PreToolUse hook
+ * returning `{ block: true }` aborts the tool call.
+ *
+ * Hooks register themselves on module init (via the {@link AiHookBase} base
+ * class). Override or override the dispatch order by extending this registry and
+ * supplying it through `CoreModule.forRoot(env, { ai: { hookRegistry } })`.
+ */
+@Injectable()
+export class AiHookRegistry {
+  private readonly hooks: IAiHook[] = [];
+  private readonly logger = new Logger(AiHookRegistry.name);
+
+  /** Register a hook. Idempotent on `name`. */
+  register(hook: IAiHook): void {
+    if (!hook?.name) {
+      return;
+    }
+    if (this.hooks.some((h) => h.name === hook.name)) {
+      return;
+    }
+    this.hooks.push(hook);
+    this.logger.debug(`Registered AI hook: ${hook.name}`);
+  }
+
+  /** All registered hooks, in registration order. */
+  list(): IAiHook[] {
+    return [...this.hooks];
+  }
+
+  /**
+   * Run every `preToolUse` hook against a tool call. Returns the first blocking
+   * decision (or one with an `args` override). Errors are swallowed and logged.
+   */
+  async runPreToolUse(
+    call: { arguments: Record<string, any>; name: string },
+    tool: IAiTool,
+    event: AiHookEvent,
+  ): Promise<AiHookPreDecision> {
+    let merged: AiHookPreDecision = {};
+    for (const hook of this.hooks) {
+      if (!hook.preToolUse) {
+        continue;
+      }
+      try {
+        const decision = await hook.preToolUse(call, tool, event);
+        if (!decision) {
+          continue;
+        }
+        if (decision.args) {
+          // Each subsequent hook sees the rewritten args (chained sanitization).
+          call.arguments = decision.args;
+          merged.args = decision.args;
+        }
+        if (decision.block) {
+          merged = { ...merged, block: true, reason: decision.reason || merged.reason };
+          break;
+        }
+      } catch (err) {
+        this.logger.warn(`AI hook "${hook.name}" preToolUse error (ignored): ${(err as Error).message}`);
+      }
+    }
+    return merged;
+  }
+
+  /** Notify all `postToolUse` hooks. Errors are swallowed. */
+  async runPostToolUse(
+    call: { arguments: Record<string, any>; name: string },
+    tool: IAiTool,
+    result: { result: unknown; success: boolean },
+    event: AiHookEvent,
+  ): Promise<void> {
+    for (const hook of this.hooks) {
+      if (!hook.postToolUse) {
+        continue;
+      }
+      try {
+        await hook.postToolUse(call, tool, result, event);
+      } catch (err) {
+        this.logger.warn(`AI hook "${hook.name}" postToolUse error (ignored): ${(err as Error).message}`);
+      }
+    }
+  }
+
+  /** Notify all `sessionStart` hooks. */
+  async runSessionStart(event: AiHookEvent): Promise<void> {
+    for (const hook of this.hooks) {
+      if (!hook.sessionStart) {
+        continue;
+      }
+      try {
+        await hook.sessionStart(event);
+      } catch (err) {
+        this.logger.warn(`AI hook "${hook.name}" sessionStart error (ignored): ${(err as Error).message}`);
+      }
+    }
+  }
+
+  /** Notify all `stop` hooks. */
+  async runStop(response: CoreAiResponse, event: AiHookEvent): Promise<void> {
+    for (const hook of this.hooks) {
+      if (!hook.stop) {
+        continue;
+      }
+      try {
+        await hook.stop(response, event);
+      } catch (err) {
+        this.logger.warn(`AI hook "${hook.name}" stop error (ignored): ${(err as Error).message}`);
+      }
+    }
+  }
+}

package/src/core/modules/ai/index.ts

@@ -0,0 +1,70 @@
+// AI module public API
+export * from './core-ai-mcp.controller';
+export * from './helpers/ai-mcp-oauth.helper';
+export * from './core-ai.controller';
+export * from './core-ai.module';
+export * from './core-ai.resolver';
+export * from './inputs/core-ai-budget-limit-create.input';
+export * from './inputs/core-ai-budget-limit.input';
+export * from './inputs/core-ai-connection-create.input';
+export * from './inputs/core-ai-connection-preference.input';
+export * from './inputs/core-ai-connection.input';
+export * from './inputs/core-ai-conversation-create.input';
+export * from './inputs/core-ai-conversation.input';
+export * from './inputs/core-ai-prompt-hint-create.input';
+export * from './inputs/core-ai-prompt-hint.input';
+export * from './inputs/core-ai-prompt-create.input';
+export * from './inputs/core-ai-prompt-update.input';
+export * from './inputs/core-ai-slot-create.input';
+export * from './inputs/core-ai-slot-update.input';
+export * from './inputs/core-ai-prompt.input';
+export * from './hooks/ai-hook.base';
+export * from './hooks/ai-hook.registry';
+export * from './interfaces/ai-hook.interface';
+export * from './interfaces/ai-placeholder.interface';
+export * from './interfaces/ai-tool.interface';
+export * from './interfaces/llm-provider.interface';
+export * from './interfaces/resolved-ai-connection.interface';
+export * from './models/core-ai-action.model';
+export * from './models/core-ai-available-connection.model';
+export * from './models/core-ai-budget-limit.model';
+export * from './models/core-ai-connection-preference.model';
+export * from './models/core-ai-connection.model';
+export * from './models/core-ai-conversation.model';
+export * from './models/core-ai-interaction.model';
+export * from './models/core-ai-message.model';
+export * from './models/core-ai-prompt-hint.model';
+export * from './models/core-ai-prompt.model';
+export * from './models/core-ai-slot.model';
+export * from './models/core-ai-tool-grant.model';
+export * from './models/core-ai-mode.model';
+export * from './models/core-ai-tool-policy.model';
+export * from './models/core-ai-response.model';
+export * from './models/core-ai-usage-info.model';
+export * from './models/core-ai-usage.model';
+export * from './providers/claude-cli.provider';
+export * from './providers/llm-provider.factory';
+export * from './providers/openai-compatible.provider';
+export * from './services/ai-crypto.service';
+export * from './services/core-ai-budget.service';
+export * from './services/core-ai-connection-preference.service';
+export * from './services/core-ai-connection-resolver.service';
+export * from './services/core-ai-connection.service';
+export * from './services/core-ai-conversation.service';
+export * from './services/core-ai-interaction.service';
+export * from './services/core-ai-mcp-oauth.service';
+export * from './services/core-ai-mcp.service';
+export * from './services/core-ai-placeholder.registry';
+export * from './services/core-ai-prompt-builder.service';
+export * from './services/core-ai-prompt-hint.service';
+export * from './services/core-ai-prompt.service';
+export * from './services/core-ai-slot.service';
+export * from './services/core-ai-tool-grant.service';
+export * from './services/core-ai-mcp-client.service';
+export * from './services/core-ai-mode.service';
+export * from './services/core-ai-tool-policy.service';
+export * from './services/core-ai.service';
+export * from './tools/ai-tool.base';
+export * from './tools/ai-tool.registry';
+export * from './tools/ask-user-question.tool';
+export * from './tools/search-tools.tool';

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

@@ -0,0 +1,27 @@
+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';
+import { CoreAiBudgetLimitInput } from './core-ai-budget-limit.input';
+
+/**
+ * Input to create an AI budget limit. `scope` and `refId` are required.
+ */
+@InputType({ description: 'Input to create an AI budget limit', isAbstract: true })
+@Restricted(RoleEnum.ADMIN)
+export class CoreAiBudgetLimitCreateInput extends CoreAiBudgetLimitInput {
+  @UnifiedField({
+    description: 'Id of the user or tenant this limit applies to',
+    roles: RoleEnum.ADMIN,
+  })
+  override refId: string = undefined;
+
+  @UnifiedField({
+    description: "Scope of the limit: 'user' or 'tenant'",
+    roles: RoleEnum.ADMIN,
+    validator: () => [IsIn(['tenant', 'user'])],
+  })
+  override scope: string = undefined;
+}

package/src/core/modules/ai/inputs/core-ai-budget-limit.input.ts

@@ -0,0 +1,52 @@
+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 budget limit (all fields optional).
+ */
+@InputType({ description: 'Input to update an AI budget limit', isAbstract: true })
+@Restricted(RoleEnum.ADMIN)
+export class CoreAiBudgetLimitInput {
+  @UnifiedField({
+    description: 'Maximum number of prompts per reset period (0/undefined = unlimited)',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  maxPrompts?: number = undefined;
+
+  @UnifiedField({
+    description: 'Maximum number of tokens per reset period (0/undefined = unlimited)',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  maxTokens?: number = undefined;
+
+  @UnifiedField({
+    description: "Reset period: 'day', 'month' or 'none'",
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    validator: () => [IsIn(['day', 'month', 'none'])],
+  })
+  period?: string = undefined;
+
+  @UnifiedField({
+    description: 'Id of the user or tenant this limit applies to',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+  })
+  refId?: string = undefined;
+
+  @UnifiedField({
+    description: "Scope of the limit: 'user' or 'tenant'",
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    validator: () => [IsIn(['tenant', 'user'])],
+  })
+  scope?: string = undefined;
+}

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

@@ -0,0 +1,32 @@
+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 { CoreAiConnectionInput } from './core-ai-connection.input';
+
+/**
+ * Input to create a new AI connection. Makes `baseUrl`, `model` and `name`
+ * required while inheriting the optional fields from {@link CoreAiConnectionInput}.
+ */
+@InputType({ description: 'Input to create a new AI connection', isAbstract: true })
+@Restricted(RoleEnum.ADMIN)
+export class CoreAiConnectionCreateInput extends CoreAiConnectionInput {
+  @UnifiedField({
+    description: 'Base URL of the OpenAI-compatible endpoint',
+    roles: RoleEnum.ADMIN,
+  })
+  override baseUrl: string = undefined;
+
+  @UnifiedField({
+    description: 'Model id sent to the backend (e.g. gpt-oss-120b)',
+    roles: RoleEnum.ADMIN,
+  })
+  override model: string = undefined;
+
+  @UnifiedField({
+    description: 'Human-readable connection name',
+    roles: RoleEnum.ADMIN,
+  })
+  override name: string = undefined;
+}

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

@@ -0,0 +1,42 @@
+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 create/update an AI connection preference (tenant/user default or
+ * tenant-enforced). Admin-managed; user self-service goes through a dedicated
+ * mutation that only sets the caller's own user preference.
+ */
+@InputType({ description: 'Input for an AI connection preference', isAbstract: true })
+@Restricted(RoleEnum.ADMIN)
+export class CoreAiConnectionPreferenceInput {
+  @UnifiedField({
+    description: 'The selected connection id',
+    roles: RoleEnum.ADMIN,
+  })
+  connectionId: string = undefined;
+
+  @UnifiedField({
+    description: 'Whether the tenant connection is enforced (tenant scope only)',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  enforced?: boolean = undefined;
+
+  @UnifiedField({
+    description: 'The tenant id or user id this preference belongs to',
+    roles: RoleEnum.ADMIN,
+  })
+  refId: string = undefined;
+
+  @UnifiedField({
+    description: "Scope of the preference: 'tenant' or 'user'",
+    roles: RoleEnum.ADMIN,
+    validator: () => [IsIn(['tenant', 'user'])],
+  })
+  scope: string = undefined;
+}

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

@@ -0,0 +1,235 @@
+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';
+
+/**
+ * Input to update an AI connection. All fields are optional (patch semantics).
+ *
+ * HINT: All properties must be initialized with `undefined` so they are picked up
+ * via `Object.keys` for mapping and never overwrite existing DB values.
+ */
+@InputType({ description: 'Input to update an AI connection', isAbstract: true })
+@Restricted(RoleEnum.ADMIN)
+export class CoreAiConnectionInput {
+  /**
+   * Plaintext API key. Encrypted at rest, never returned. Pass an empty string
+   * to clear the stored key; omit the field to leave it untouched.
+   */
+  @UnifiedField({
+    description: 'Plaintext API key (encrypted at rest, never returned; empty string clears it)',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+  })
+  apiKey?: string = undefined;
+
+  /**
+   * Name of an environment variable used as API-key fallback.
+   */
+  @UnifiedField({
+    description: 'Name of the environment variable used as API-key fallback',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+  })
+  apiKeyEnv?: string = undefined;
+
+  /**
+   * Base URL of the OpenAI-compatible endpoint.
+   */
+  @UnifiedField({
+    description: 'Base URL of the OpenAI-compatible endpoint',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+  })
+  baseUrl?: string = undefined;
+
+  /**
+   * Capability tags of the model.
+   */
+  @UnifiedField({
+    description: 'Capability tags of the model',
+    isArray: true,
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => String,
+  })
+  capabilities?: string[] = undefined;
+
+  /**
+   * Default maximum number of tokens for completions.
+   */
+  @UnifiedField({
+    description: 'Default maximum number of tokens for completions',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  defaultMaxTokens?: number = undefined;
+
+  @UnifiedField({
+    description: 'Total context window (tokens) the model supports; enables context-overflow handling',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  contextWindow?: number = undefined;
+
+  /**
+   * Default sampling temperature for completions.
+   */
+  @UnifiedField({
+    description: 'Default sampling temperature for completions',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  defaultTemperature?: number = undefined;
+
+  /** Provider-side soft user quota (tokens) used when no hard budget is set. */
+  @UnifiedField({
+    description: 'Provider-side soft user quota (tokens) used when no hard budget is set',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  defaultUserMaxTokens?: number = undefined;
+
+  /** Period for the provider-side soft user quota (`day` | `month` | `none`). */
+  @UnifiedField({
+    description: 'Period for the provider-side soft user quota (day | month | none)',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+  })
+  defaultUserMaxPeriod?: string = undefined;
+
+  /**
+   * Human-readable description.
+   */
+  @UnifiedField({
+    description: 'Human-readable description of the connection',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+  })
+  description?: string = undefined;
+
+  /**
+   * Whether the connection is enabled.
+   */
+  @UnifiedField({
+    description: 'Whether the connection is enabled',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  enabled?: boolean = undefined;
+
+  /**
+   * Admin-enforced for all tenants (overrides user/client/tenant selection).
+   */
+  @UnifiedField({
+    description: 'Admin-enforced for all tenants',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  enforced?: boolean = undefined;
+
+  /**
+   * Tenant ids for which this connection is admin-enforced.
+   */
+  @UnifiedField({
+    description: 'Tenant ids for which this connection is admin-enforced',
+    isArray: true,
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => String,
+  })
+  enforcedTenantIds?: string[] = undefined;
+
+  /**
+   * Whether this is the default connection.
+   */
+  @UnifiedField({
+    description: 'Whether this is the default connection',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  isDefault?: boolean = undefined;
+
+  /**
+   * Model id sent to the backend.
+   */
+  @UnifiedField({
+    description: 'Model id sent to the backend (e.g. gpt-oss-120b)',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+  })
+  model?: string = undefined;
+
+  /**
+   * Human-readable connection name.
+   */
+  @UnifiedField({
+    description: 'Human-readable connection name',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+  })
+  name?: string = undefined;
+
+  /**
+   * Provider type.
+   */
+  @UnifiedField({
+    description: 'Provider type (e.g. openai-compatible)',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+  })
+  providerType?: string = undefined;
+
+  /**
+   * Whether the backend supports native JSON/structured-output mode.
+   */
+  @UnifiedField({
+    description: 'Whether the backend supports native JSON/structured-output mode',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  supportsJsonResponse?: boolean = undefined;
+
+  /**
+   * Whether the backend supports native function/tool calling.
+   */
+  @UnifiedField({
+    description: 'Whether the backend supports native function/tool calling',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  supportsNativeTools?: boolean = undefined;
+
+  /**
+   * Whether the model supports vision (image input).
+   */
+  @UnifiedField({
+    description: 'Whether the model supports vision (image input)',
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  supportsVision?: boolean = undefined;
+
+  /**
+   * Tenant ids this connection is available to (empty = all tenants).
+   */
+  @UnifiedField({
+    description: 'Tenant ids this connection is available to (empty = all tenants)',
+    isArray: true,
+    isOptional: true,
+    roles: RoleEnum.ADMIN,
+    type: () => String,
+  })
+  tenantIds?: string[] = undefined;
+}

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

@@ -0,0 +1,13 @@
+import { InputType } from '@nestjs/graphql';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { CoreAiConversationInput } from './core-ai-conversation.input';
+
+/**
+ * Input to create a new AI conversation (same shape as the update input; both
+ * fields are optional). Separate class to allow project-specific extension.
+ */
+@InputType({ description: 'Input to create a new AI conversation', isAbstract: true })
+@Restricted(RoleEnum.S_USER)
+export class CoreAiConversationCreateInput extends CoreAiConversationInput {}

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

@@ -0,0 +1,33 @@
+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';
+
+/**
+ * Input to create or update an AI conversation. Messages are not set here — they
+ * are appended by the orchestrator during prompt runs.
+ */
+@InputType({ description: 'Input to create or update an AI conversation', isAbstract: true })
+@Restricted(RoleEnum.S_USER)
+export class CoreAiConversationInput {
+  /**
+   * Optional default connection for the conversation.
+   */
+  @UnifiedField({
+    description: 'Optional default AI connection id for the conversation',
+    isOptional: true,
+    roles: RoleEnum.S_USER,
+  })
+  connectionId?: string = undefined;
+
+  /**
+   * Human-readable title.
+   */
+  @UnifiedField({
+    description: 'Human-readable title',
+    isOptional: true,
+    roles: RoleEnum.S_USER,
+  })
+  title?: string = undefined;
+}

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

@@ -0,0 +1,50 @@
+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 creating a {@link CoreAiPrompt}. `ownerId`/`tenantId` are set
+ * automatically by the service from the current user — never from the client.
+ */
+@InputType({ description: 'Input to create a user prompt' })
+@Restricted(RoleEnum.S_USER)
+export class CoreAiPromptCreateInput extends CoreInput {
+  @UnifiedField({ description: 'The prompt text', 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', roles: RoleEnum.S_USER })
+  name: string = undefined;
+
+  @UnifiedField({
+    description: 'Sort order',
+    isOptional: true,
+    roles: RoleEnum.S_USER,
+    type: () => Number,
+  })
+  order?: number = undefined;
+
+  /** `'user'` (default, "private") | `'tenant'` ("public" within the tenant). */
+  @UnifiedField({
+    description: "Visibility scope ('user' = private, 'tenant' = public)",
+    isOptional: true,
+    roles: RoleEnum.S_USER,
+  })
+  scope?: string = undefined;
+}