@lenne.tech/nest-server 11.25.5 → 11.26.0

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

@@ -0,0 +1,94 @@
+import { Injectable, Logger } from '@nestjs/common';
+
+import { AiToolContext } from '../interfaces/ai-tool.interface';
+import { AiToolRegistry, AiToolUser } from '../tools/ai-tool.registry';
+
+/**
+ * MCP tool descriptor (name + description + JSON-schema input).
+ */
+export interface McpToolDescriptor {
+  description: string;
+  inputSchema: Record<string, any>;
+  name: string;
+}
+
+/**
+ * MCP tool-call result in the SDK content shape.
+ */
+export interface McpCallResult {
+  content: { text: string; type: 'text' }[];
+  isError?: boolean;
+}
+
+/**
+ * Exposes the {@link AiToolRegistry} as a Model Context Protocol (MCP) server so
+ * external MCP clients (e.g. desktop MCP clients) can use the same backend tools with
+ * the same role gating as the internal orchestrator.
+ *
+ * The MCP server is created per session and bound to the authenticating user, so
+ * `tools/list` and `tools/call` are filtered to that user's permitted tools and
+ * executed with their permissions (via each tool's `execute()` → CrudService).
+ *
+ * The `@modelcontextprotocol/sdk` is imported lazily in {@link createServer} so it
+ * is only loaded when MCP is actually enabled — keeping the core lean.
+ */
+@Injectable()
+export class CoreAiMcpService {
+  protected readonly logger = new Logger(CoreAiMcpService.name);
+
+  constructor(protected readonly toolRegistry: AiToolRegistry) {}
+
+  /**
+   * List the MCP tool descriptors the user is allowed to use.
+   */
+  mcpListTools(user: AiToolUser | null | undefined): McpToolDescriptor[] {
+    return this.toolRegistry
+      .forUser(user)
+      .map((tool) => ({ description: tool.description, inputSchema: tool.parameters, name: tool.name }));
+  }
+
+  /**
+   * Execute an MCP tool call with the user's permissions. Returns an MCP content
+   * result; unknown/forbidden tools and execution errors yield `isError: true`.
+   */
+  async mcpCallTool(
+    user: AiToolUser | null | undefined,
+    name: string,
+    args: Record<string, any>,
+  ): Promise<McpCallResult> {
+    const tool = this.toolRegistry.forUser(user).find((t) => t.name === name);
+    if (!tool) {
+      return { content: [{ text: `Unknown or not permitted tool: ${name}`, type: 'text' }], isError: true };
+    }
+    const context: AiToolContext = {
+      currentUser: (user ?? undefined) as AiToolContext['currentUser'],
+      serviceOptions: { currentUser: (user ?? undefined) as AiToolContext['currentUser'] },
+    };
+    try {
+      const result = await tool.execute(args ?? {}, context);
+      return { content: [{ text: JSON.stringify(result), type: 'text' }] };
+    } catch (err) {
+      this.logger.warn(`MCP tool "${name}" failed: ${(err as Error).message}`);
+      return { content: [{ text: (err as Error).message, type: 'text' }], isError: true };
+    }
+  }
+
+  /**
+   * Create a low-level MCP server bound to a user. Uses the JSON-schema tool
+   * definitions directly (no zod conversion needed). The SDK is imported lazily.
+   */
+  async createServer(user: AiToolUser): Promise<any> {
+    const { Server } = await import('@modelcontextprotocol/sdk/server/index.js');
+    const { CallToolRequestSchema, ListToolsRequestSchema } = await import('@modelcontextprotocol/sdk/types.js');
+
+    // Loosely typed to decouple from the SDK's strict request/result types.
+    const server: any = new Server({ name: 'lt-nest-server-ai', version: '1.0.0' }, { capabilities: { tools: {} } });
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: this.mcpListTools(user) }));
+    server.setRequestHandler(CallToolRequestSchema, async (request: any) =>
+      this.mcpCallTool(user, request.params.name, request.params.arguments ?? {}),
+    );
+
+    return server;
+  }
+}

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

@@ -0,0 +1,43 @@
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { InjectModel } from '@nestjs/mongoose';
+import { Model } from 'mongoose';
+
+import { CrudService } from '../../../common/services/crud.service';
+import { CoreModelConstructor } from '../../../common/types/core-model-constructor.type';
+import { AiModeDocument, CoreAiMode } from '../models/core-ai-mode.model';
+
+export const AI_MODE_MODEL = 'AiMode';
+export const AI_MODE_CLASS = 'AI_MODE_CLASS';
+
+/**
+ * Named-mode store. See {@link CoreAiMode}. Override via
+ * `CoreModule.forRoot(env, { ai: { modeService } })`.
+ */
+@Injectable()
+export class CoreAiModeService extends CrudService<CoreAiMode, CoreAiMode, CoreAiMode> {
+  protected readonly logger = new Logger(CoreAiModeService.name);
+
+  constructor(
+    @InjectModel(AI_MODE_MODEL) protected override readonly mainDbModel: Model<AiModeDocument>,
+    @Inject(AI_MODE_CLASS) protected override readonly mainModelConstructor: CoreModelConstructor<CoreAiMode>,
+  ) {
+    super();
+  }
+
+  /** Lookup a mode by `name`. Returns `null` if missing or disabled. */
+  async getByName(name: string): Promise<CoreAiMode | null> {
+    if (!name) {
+      return null;
+    }
+    try {
+      const row = await this.mainDbModel
+        .findOne({ enabled: { $ne: false }, name })
+        .lean<CoreAiMode>()
+        .exec();
+      return row || null;
+    } catch (err) {
+      this.logger.warn(`Failed to load mode "${name}": ${(err as Error).message}`);
+      return null;
+    }
+  }
+}

package/src/core/modules/ai/services/core-ai-placeholder.registry.ts

@@ -0,0 +1,123 @@
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
+
+import { ConfigService } from '../../../common/services/config.service';
+import { AiPlaceholderContext, AiPlaceholderInfo, IAiPlaceholder } from '../interfaces/ai-placeholder.interface';
+import { CoreAiPromptHintService } from './core-ai-prompt-hint.service';
+
+/**
+ * Runtime registry of `{{placeholder}}` resolvers used by slots and user
+ * prompts. The framework registers a small set of system placeholders on boot
+ * (`roles`, `tools`, `toolCatalog`, `documentation`, `learnedHints`, `userId`);
+ * projects can add their own via {@link register} from any provider.
+ *
+ * Why dynamic and not hard-coded in the frontend: the placeholder list is
+ * served via `GET /ai/placeholders`, so admins see EVERY currently-supported
+ * placeholder (incl. project-specific ones) — without requiring a frontend
+ * change when the backend gets new ones. Resolvers stay in TypeScript (no
+ * eval, no DB-stored function bodies), which keeps the surface secure and
+ * straightforward.
+ *
+ * Override / extend via `CoreModule.forRoot(env, { ai: { placeholderRegistry } })`
+ * or by injecting and calling `register()` from a project provider.
+ */
+@Injectable()
+export class CoreAiPlaceholderRegistry implements OnModuleInit {
+  protected readonly logger = new Logger(CoreAiPlaceholderRegistry.name);
+  protected readonly placeholders = new Map<string, IAiPlaceholder>();
+
+  constructor(protected readonly hintService?: CoreAiPromptHintService) {}
+
+  onModuleInit(): void {
+    this.registerDefaults();
+  }
+
+  /**
+   * Register a placeholder. Repeated calls with the same `name` overwrite the
+   * previous resolver — projects can replace system placeholders if they need
+   * different semantics.
+   */
+  register(placeholder: IAiPlaceholder): void {
+    if (!placeholder?.name) {
+      this.logger.warn('Refusing to register a placeholder with no name.');
+      return;
+    }
+    this.placeholders.set(placeholder.name, placeholder);
+  }
+
+  /** Remove a placeholder by name. Returns true if it was present. */
+  unregister(name: string): boolean {
+    return this.placeholders.delete(name);
+  }
+
+  /** Public metadata of every registered placeholder, sorted by name. */
+  list(): AiPlaceholderInfo[] {
+    return [...this.placeholders.values()]
+      .map((p) => ({ description: p.description, example: p.example, name: p.name }))
+      .sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  /**
+   * Resolve every registered placeholder for `ctx` and return a flat record
+   * `{ name: value }` suitable for `{{token}}` substitution.
+   */
+  async resolveAll(ctx: AiPlaceholderContext): Promise<Record<string, string>> {
+    const out: Record<string, string> = {};
+    for (const p of this.placeholders.values()) {
+      try {
+        const value = await p.resolve(ctx);
+        out[p.name] = value === null || value === undefined ? '' : String(value);
+      } catch (err) {
+        this.logger.warn(`Placeholder ${p.name} failed to resolve: ${(err as Error).message}`);
+        out[p.name] = '';
+      }
+    }
+    return out;
+  }
+
+  /**
+   * Built-in system placeholders. Override this method in a subclass to swap
+   * defaults; project-specific additions should use {@link register} from a
+   * provider's `onModuleInit` for clearer separation.
+   */
+  protected registerDefaults(): void {
+    this.register({
+      description: 'Comma-separated list of the current user roles (e.g. "admin, editor"). "none" when empty.',
+      example: 'admin, editor',
+      name: 'roles',
+      resolve: (ctx) => (ctx.user?.roles?.length ? ctx.user.roles.join(', ') : 'none'),
+    });
+    this.register({
+      description: 'Comma-separated list of the tools the current user may use this turn.',
+      example: 'get_user, find_users',
+      name: 'tools',
+      resolve: (ctx) => (ctx.tools?.length ? ctx.tools.map((t) => t.name).join(', ') : 'none'),
+    });
+    this.register({
+      description: 'Full tool catalog with names, descriptions and parameter schemas (LLM-readable).',
+      name: 'toolCatalog',
+      resolve: (ctx) => ctx.toolCatalog ?? '',
+    });
+    this.register({
+      description:
+        'System documentation injected into the prompt (from the `ai.documentation` config or a project override).',
+      name: 'documentation',
+      resolve: () => ConfigService.get<string>('ai.documentation') || '',
+    });
+    this.register({
+      description:
+        'Admin-approved hints from the governed learning loop, scoped to the tools in use this turn. Empty when nothing applies.',
+      name: 'learnedHints',
+      resolve: async (ctx) => {
+        if (!this.hintService) return '';
+        const learned = await this.hintService.approvedHints((ctx.tools || []).map((t) => t.name));
+        return learned.length ? learned.map((h) => `- ${h}`).join('\n') : '';
+      },
+    });
+    this.register({
+      description: 'Current user id (empty when no user is in context).',
+      example: '6a16c51530d808eb40a93d66',
+      name: 'userId',
+      resolve: (ctx) => ctx.user?.id || '',
+    });
+  }
+}

package/src/core/modules/ai/services/core-ai-prompt-builder.service.ts

@@ -0,0 +1,228 @@
+import { Injectable, Optional } from '@nestjs/common';
+
+import { ConfigService } from '../../../common/services/config.service';
+import { IAiTool } from '../interfaces/ai-tool.interface';
+import { LlmToolSchema } from '../interfaces/llm-provider.interface';
+import { CoreAiPlaceholderRegistry } from './core-ai-placeholder.registry';
+import { CoreAiPromptHintService } from './core-ai-prompt-hint.service';
+import { CoreAiSlotService, getSystemDefaultSlots, ResolvedPromptFragment } from './core-ai-slot.service';
+
+/** Options for a prompt build (locale for template/hint selection). */
+export interface BuildPromptOptions {
+  language?: string;
+  /** Named agent mode (e.g. 'support', 'audit') — exposes as a `mode:<name>` scope to filter fragments. */
+  mode?: string;
+}
+
+/**
+ * Builds the system prompt and tool catalog for a prompt run.
+ *
+ * The prompt is assembled from keyed fragments: built-in {@link defaultFragments}
+ * overlaid by admin-editable rows from {@link CoreAiSlotService}, plus
+ * governed learned hints from {@link CoreAiPromptHintService}. Nothing is hard-coded
+ * and unreachable — admins and the learning loop can adjust every fragment. Override
+ * this class via `CoreModule.forRoot(env, { ai: { promptBuilder } })` for custom
+ * composition (domain context, RAG, tone).
+ *
+ * Placeholders rendered at build time: `{{documentation}}`, `{{roles}}`, `{{tools}}`,
+ * `{{toolCatalog}}`, `{{learnedHints}}`, `{{userId}}`.
+ */
+@Injectable()
+export class CoreAiPromptBuilderService {
+  /** Keys that belong only to the auto (step-by-step) execution mode. */
+  protected readonly autoOnlyKeys = ['output_contract', 'plan_protocol', 'tool_catalog', 'tool_protocol_emulated'];
+
+  /** Default base system prompt (used when `ai.systemPrompt` is not configured). */
+  protected readonly defaultSystemPrompt =
+    'You are a helpful assistant integrated into a business application. ' +
+    'Answer concisely and only use information you can obtain through the provided tools. ' +
+    'Never invent data. If a request cannot be fulfilled with the available tools, say so.';
+
+  /** Keys that describe tool calling (skipped when the user has no tools). */
+  protected readonly toolKeys = ['output_contract', 'plan_protocol', 'tool_catalog', 'tool_protocol_emulated'];
+
+  constructor(
+    @Optional() protected readonly templateService?: CoreAiSlotService,
+    @Optional() protected readonly hintService?: CoreAiPromptHintService,
+    @Optional() protected readonly placeholderRegistry?: CoreAiPlaceholderRegistry,
+  ) {}
+
+  /**
+   * Build the full system prompt for an auto-mode run, assembled from the effective
+   * prompt fragments (defaults + admin overrides) with placeholders rendered and
+   * governed learned hints injected.
+   */
+  async buildSystemPrompt(
+    tools: IAiTool[],
+    supportsNativeTools: boolean,
+    user?: { id?: string; roles?: string[] },
+    options?: BuildPromptOptions,
+  ): Promise<string> {
+    const capability = supportsNativeTools ? 'native' : 'emulated';
+    const fragments = await this.resolveFragments(
+      capability,
+      options?.language,
+      this.computeScopes(tools, user, options),
+    );
+    const context = await this.renderContext(tools, user);
+    return this.assemble(
+      fragments.filter((f) => f.key !== 'plan_protocol'),
+      context,
+      tools.length,
+    );
+  }
+
+  /**
+   * Build the system prompt for plan mode: the model must return a COMPLETE ordered
+   * plan of tool calls as JSON instead of executing step by step. Shares the base /
+   * documentation / permissions / anti-hallucination / error / learned-hints fragments
+   * and uses the `plan_protocol` fragment instead of the auto-mode tool protocol.
+   */
+  async buildPlanSystemPrompt(
+    tools: IAiTool[],
+    user?: { id?: string; roles?: string[] },
+    options?: BuildPromptOptions,
+  ): Promise<string> {
+    const fragments = await this.resolveFragments(
+      'emulated',
+      options?.language,
+      this.computeScopes(tools, user, options),
+    );
+    const context = await this.renderContext(tools, user);
+    const planFragments = fragments.filter((f) => f.key === 'plan_protocol' || !this.autoOnlyKeys.includes(f.key));
+    return this.assemble(planFragments, context, tools.length);
+  }
+
+  /**
+   * Map tools to native tool schemas (used only when the provider supports it).
+   */
+  buildToolSchemas(tools: IAiTool[]): LlmToolSchema[] {
+    return tools.map((t) => ({ description: t.description, name: t.name, parameters: t.parameters }));
+  }
+
+  /**
+   * Built-in default prompt fragments. `content` may contain `{{placeholders}}`.
+   * Override to ship different defaults (admins can also override per-key in the DB
+   * via {@link CoreAiSlotService}).
+   */
+  protected defaultFragments(): ResolvedPromptFragment[] {
+    return getSystemDefaultSlots(ConfigService.get<string>('ai.systemPrompt') || this.defaultSystemPrompt);
+  }
+
+  /**
+   * Optional system documentation injected into the prompt. Reads `ai.documentation`
+   * by default; override to supply RAG results / API docs.
+   */
+  protected getDocumentation(): string | undefined {
+    return ConfigService.get<string>('ai.documentation') || undefined;
+  }
+
+  /**
+   * Resolve the effective fragments: built-in defaults overlaid by admin DB rows
+   * (when the template service is wired). Falls back to defaults only otherwise.
+   */
+  protected async resolveFragments(
+    capability: string,
+    locale?: string,
+    scopes?: string[],
+  ): Promise<ResolvedPromptFragment[]> {
+    const defaults = this.defaultFragments();
+    const activeScopes = scopes ?? [];
+    if (!this.templateService) {
+      return defaults
+        .filter((f) => !f.capability || f.capability === 'all' || f.capability === capability)
+        .filter((f) => !f.scope || activeScopes.includes(f.scope))
+        .sort((a, b) => a.order - b.order);
+    }
+    return this.templateService.resolveFragments(defaults, { capability, locale, scopes: activeScopes });
+  }
+
+  /**
+   * Compute the active scope tags for a run: `tool:<name>` for each tool in scope,
+   * `role:<name>` for each user role, and `mode:<name>` if a named mode is active.
+   * Used to filter scoped prompt fragments via {@link CoreAiSlotService.resolveFragments}.
+   */
+  protected computeScopes(
+    tools: IAiTool[],
+    user?: { id?: string; roles?: string[] },
+    options?: BuildPromptOptions & { mode?: string },
+  ): string[] {
+    const scopes: string[] = [];
+    for (const tool of tools || []) {
+      if (tool?.name) {
+        scopes.push(`tool:${tool.name}`);
+      }
+    }
+    for (const role of user?.roles || []) {
+      scopes.push(`role:${role}`);
+    }
+    if (options?.mode) {
+      scopes.push(`mode:${options.mode}`);
+    }
+    return scopes;
+  }
+
+  /**
+   * Compute placeholder values for the run. Resolves via {@link CoreAiPlaceholderRegistry}
+   * when wired, so project-registered placeholders are honored automatically; falls
+   * back to a hard-coded record when no registry is available.
+   */
+  protected async renderContext(
+    tools: IAiTool[],
+    user?: { id?: string; roles?: string[] },
+  ): Promise<Record<string, string>> {
+    // Deferred tool-schemas (#13): with many tools the full JSON-Schema catalog can
+    // dominate the system prompt. When `ai.deferToolSchemas` is on, the catalog
+    // emits ONLY the tool names + short descriptions; the LLM uses the built-in
+    // `search_tools` meta-tool to fetch the parameter schema for a tool on demand.
+    const defer = ConfigService.get<boolean>('ai.deferToolSchemas') === true;
+    const toolCatalog = defer
+      ? (tools.map((t) => `- ${t.name}: ${t.description}`).join('\n') || '(none)') +
+        '\n\n[Schemas deferred. Call `search_tools` with the tool name to fetch its parameter schema BEFORE you call it.]'
+      : tools
+          .map((t) => `- ${t.name}: ${t.description}\n  parameters (JSON schema): ${JSON.stringify(t.parameters)}`)
+          .join('\n') || '(none)';
+
+    if (this.placeholderRegistry) {
+      return this.placeholderRegistry.resolveAll({ toolCatalog, tools, user });
+    }
+
+    // Fallback when the registry isn't wired (legacy / unit-test paths).
+    const learned = this.hintService ? await this.hintService.approvedHints(tools.map((t) => t.name)) : [];
+    return {
+      documentation: this.getDocumentation() || '',
+      learnedHints: learned.length ? learned.map((h) => `- ${h}`).join('\n') : '',
+      roles: user?.roles?.length ? user.roles.join(', ') : 'none',
+      toolCatalog,
+      tools: tools.map((t) => t.name).join(', ') || 'none',
+      userId: user?.id || '',
+    };
+  }
+
+  /** Render placeholders, drop empty/irrelevant fragments, and join. */
+  protected assemble(fragments: ResolvedPromptFragment[], context: Record<string, string>, toolCount: number): string {
+    const parts: string[] = [];
+    for (const fragment of fragments) {
+      // Skip fragments whose driving placeholder is empty or that need tools.
+      if (fragment.key === 'documentation' && !context.documentation) {
+        continue;
+      }
+      if (fragment.key === 'learned_hints' && !context.learnedHints) {
+        continue;
+      }
+      if (this.toolKeys.includes(fragment.key) && toolCount === 0) {
+        continue;
+      }
+      const rendered = this.render(fragment.content, context).trim();
+      if (rendered) {
+        parts.push(rendered);
+      }
+    }
+    return parts.join('\n\n');
+  }
+
+  /** Replace `{{placeholder}}` tokens with their values (unknown tokens become ''). */
+  protected render(template: string, context: Record<string, string>): string {
+    return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (_match, key: string) => context[key] ?? '');
+  }
+}

package/src/core/modules/ai/services/core-ai-prompt-hint.service.ts

@@ -0,0 +1,133 @@
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { InjectModel } from '@nestjs/mongoose';
+import { Model } from 'mongoose';
+
+import { ConfigService } from '../../../common/services/config.service';
+import { CrudService } from '../../../common/services/crud.service';
+import { CoreModelConstructor } from '../../../common/types/core-model-constructor.type';
+import { CoreAiPromptHintCreateInput } from '../inputs/core-ai-prompt-hint-create.input';
+import { CoreAiPromptHintInput } from '../inputs/core-ai-prompt-hint.input';
+import { AiPromptHintDocument, CoreAiPromptHint } from '../models/core-ai-prompt-hint.model';
+
+/** Mongoose injection token for the prompt-hint model. */
+export const AI_PROMPT_HINT_MODEL = 'AiPromptHint';
+
+/** DI token for the prompt-hint model constructor. */
+export const AI_PROMPT_HINT_CLASS = 'AI_PROMPT_HINT_CLASS';
+
+/** A failure signal recorded by the orchestrator for the learning loop. */
+export interface AiPromptFeedbackSignal {
+  /** Generated guidance to add to the prompt to avoid the failure next time. */
+  content: string;
+  /** Optional scope (e.g. a tool name); empty = global. */
+  scope?: string;
+  /** Failure-pattern id (e.g. 'tool_error', 'hallucinated_execution', 'parse_failure', 'denied'). */
+  trigger: string;
+}
+
+/** Resolved `ai.promptLearning` config. */
+interface PromptLearningConfig {
+  autoApply: boolean;
+  enabled: boolean;
+  minOccurrences: number;
+}
+
+/**
+ * CRUD + governed self-improvement loop for learned prompt hints.
+ *
+ * The orchestrator reports failures via {@link recordSignal}; recurring patterns are
+ * aggregated into {@link CoreAiPromptHint} rows. By default new hints are `suggested`
+ * and only affect the prompt once an admin approves them; with
+ * `ai.promptLearning.autoApply` they are created `approved`. {@link approvedHints}
+ * feeds the active guidance into the prompt builder.
+ *
+ * Learning can never relax security — hints only ADD textual guidance; permissions and
+ * tool gating are always enforced backend-side regardless of the prompt.
+ */
+@Injectable()
+export class CoreAiPromptHintService extends CrudService<
+  CoreAiPromptHint,
+  CoreAiPromptHintCreateInput,
+  CoreAiPromptHintInput
+> {
+  protected readonly logger = new Logger(CoreAiPromptHintService.name);
+
+  constructor(
+    @InjectModel(AI_PROMPT_HINT_MODEL) protected override readonly mainDbModel: Model<AiPromptHintDocument>,
+    @Inject(AI_PROMPT_HINT_CLASS)
+    protected override readonly mainModelConstructor: CoreModelConstructor<CoreAiPromptHint>,
+  ) {
+    super();
+  }
+
+  /**
+   * Return the active learned guidance for a run: enabled, `approved` hints whose
+   * scope is global or matches one of the run's tool names.
+   */
+  async approvedHints(scopes: string[] = []): Promise<string[]> {
+    if (!this.config().enabled) {
+      return [];
+    }
+    try {
+      const rows = await this.mainDbModel
+        .find({ enabled: { $ne: false }, scope: { $in: [null, '', ...scopes] }, status: 'approved' })
+        .sort({ occurrences: -1 })
+        .lean<CoreAiPromptHint[]>()
+        .exec();
+      return rows.map((r) => r.content).filter((c): c is string => !!c?.trim());
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Record a failure signal. Best-effort: aggregates by (trigger, scope), increments
+   * the occurrence counter and creates/updates the hint. Never throws — feedback must
+   * not break a prompt run.
+   */
+  async recordSignal(signal: AiPromptFeedbackSignal): Promise<void> {
+    const config = this.config();
+    if (!config.enabled || !signal?.trigger || !signal?.content) {
+      return;
+    }
+    const scope = signal.scope || '';
+    try {
+      const existing = await this.mainDbModel
+        .findOne({ scope, trigger: signal.trigger })
+        .lean<CoreAiPromptHint>()
+        .exec();
+      if (existing) {
+        const occurrences = (existing.occurrences ?? 1) + 1;
+        const update: Record<string, unknown> = { occurrences };
+        // Auto-approve once the threshold is reached (config) and not already decided.
+        if (config.autoApply && existing.status === 'suggested' && occurrences >= config.minOccurrences) {
+          update.status = 'approved';
+        }
+        await this.mainDbModel.updateOne({ _id: (existing as any)._id }, { $set: update }).exec();
+        return;
+      }
+      const status = config.autoApply && config.minOccurrences <= 1 ? 'approved' : 'suggested';
+      await this.mainDbModel.create({
+        content: signal.content,
+        occurrences: 1,
+        scope,
+        status,
+        trigger: signal.trigger,
+      });
+    } catch (err) {
+      this.logger.debug(`recordSignal skipped: ${(err as Error).message}`);
+    }
+  }
+
+  /** Resolve the `ai.promptLearning` config with safe defaults. */
+  protected config(): PromptLearningConfig {
+    const raw = ConfigService.get<{ autoApply?: boolean; enabled?: boolean; minOccurrences?: number }>(
+      'ai.promptLearning',
+    );
+    return {
+      autoApply: raw?.autoApply === true,
+      enabled: raw?.enabled !== false,
+      minOccurrences: typeof raw?.minOccurrences === 'number' && raw.minOccurrences > 0 ? raw.minOccurrences : 1,
+    };
+  }
+}