@lenne.tech/nest-server 11.25.6 → 11.26.0

package/src/core/modules/ai/models/core-ai-prompt-hint.model.ts

@@ -0,0 +1,98 @@
+import { ObjectType } from '@nestjs/graphql';
+import { Schema as MongooseSchema, SchemaFactory } from '@nestjs/mongoose';
+import { Document } from 'mongoose';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { CorePersistenceModel } from '../../../common/models/core-persistence.model';
+
+export type AiPromptHintDocument = CoreAiPromptHint & Document;
+
+/**
+ * A learned prompt hint produced by the governed self-improvement loop
+ * ({@link CoreAiPromptFeedbackService}). When a recurring failure pattern is detected
+ * (tool errors, denied actions, parse failures, claimed-but-not-executed actions),
+ * a hint is recorded and, once **approved** (or auto-approved when
+ * `ai.promptLearning.autoApply` is on), injected into the system prompt so the model
+ * avoids the same mistake next time.
+ *
+ * Hints only ever ADD guidance — they can never relax the security core (permissions,
+ * tool gating), which is always enforced backend-side independently of the prompt.
+ */
+@MongooseSchema({ collection: 'aiPromptHints', timestamps: true })
+@ObjectType({ description: 'Learned AI prompt hint from the governed self-improvement loop' })
+@Restricted(RoleEnum.ADMIN)
+export class CoreAiPromptHint extends CorePersistenceModel {
+  /**
+   * The guidance text injected into the prompt when approved + enabled.
+   */
+  @UnifiedField({
+    description: 'Guidance text added to the prompt when approved',
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  content: string = undefined;
+
+  /**
+   * Whether the hint is active (independent of approval status).
+   */
+  @UnifiedField({
+    description: 'Whether the hint is active',
+    isOptional: true,
+    mongoose: { default: true },
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  enabled?: boolean = undefined;
+
+  /**
+   * How often the underlying failure pattern was observed.
+   */
+  @UnifiedField({
+    description: 'Number of times the failure pattern was observed',
+    isOptional: true,
+    mongoose: { default: 1 },
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  occurrences?: number = undefined;
+
+  /**
+   * Optional scope the hint applies to (e.g. a tool name); empty = global.
+   */
+  @UnifiedField({
+    description: 'Scope the hint applies to (e.g. a tool name); empty = global',
+    isOptional: true,
+    mongoose: { index: true },
+    roles: RoleEnum.ADMIN,
+  })
+  scope?: string = undefined;
+
+  /**
+   * Governance status: 'suggested' (default), 'approved' or 'rejected'. Only
+   * 'approved' + enabled hints reach the prompt.
+   */
+  @UnifiedField({
+    description: "Governance status: 'suggested', 'approved' or 'rejected'",
+    isOptional: true,
+    mongoose: { default: 'suggested', index: true },
+    roles: RoleEnum.ADMIN,
+  })
+  status?: string = undefined;
+
+  /**
+   * Failure-pattern identifier that produced this hint (e.g. 'tool_error',
+   * 'hallucinated_execution', 'parse_failure', 'denied').
+   */
+  @UnifiedField({
+    description: 'Failure-pattern identifier that produced the hint',
+    mongoose: { index: true },
+    roles: RoleEnum.ADMIN,
+  })
+  trigger: string = undefined;
+}
+
+export const AiPromptHintSchema = SchemaFactory.createForClass(CoreAiPromptHint);
+// One aggregated hint per (trigger, scope).
+AiPromptHintSchema.index({ scope: 1, trigger: 1 }, { unique: true });

package/src/core/modules/ai/models/core-ai-prompt.model.ts

@@ -0,0 +1,120 @@
+import { ObjectType } from '@nestjs/graphql';
+import { Schema as MongooseSchema, SchemaFactory } from '@nestjs/mongoose';
+import { Document } from 'mongoose';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { CorePersistenceModel } from '../../../common/models/core-persistence.model';
+
+export type AiPromptDocument = CoreAiPrompt & Document;
+
+/**
+ * User-facing prompt — a short, named piece of text the user can insert into
+ * the chat input with one click. Different from the {@link CoreAiPromptInput}
+ * mutation payload (which carries a single user question to the AI) and from
+ * {@link CoreAiSlot} (the admin-edited building blocks of the SYSTEM prompt).
+ *
+ * Visibility (enforced in {@link CoreAiPromptService.listVisible} + this
+ * model's {@link securityCheck}):
+ * - `scope: 'user'`   → only the `ownerId` user sees it ("private").
+ * - `scope: 'tenant'` → all members of `tenantId` see it ("public" within
+ *   the tenant; without multi-tenancy this is effectively workspace-wide).
+ *
+ * Mutations are owner-only.
+ */
+@MongooseSchema({ collection: 'aiPrompts', timestamps: true })
+@ObjectType({ description: 'User-facing AI prompt (re-usable user prompt)' })
+@Restricted(RoleEnum.S_USER)
+export class CoreAiPrompt extends CorePersistenceModel {
+  /** The text inserted into the chat input. May contain `{{placeholders}}`. */
+  @UnifiedField({ description: 'The prompt text', mongoose: true, roles: RoleEnum.S_USER })
+  content: string = undefined;
+
+  /** Optional description. */
+  @UnifiedField({ description: 'Description', isOptional: true, mongoose: true, roles: RoleEnum.S_USER })
+  description?: string = undefined;
+
+  /** Whether the prompt is active (disabled prompts are hidden from the picker). */
+  @UnifiedField({
+    description: 'Whether the prompt is active',
+    isOptional: true,
+    mongoose: { default: true },
+    roles: RoleEnum.S_USER,
+    type: () => Boolean,
+  })
+  enabled?: boolean = undefined;
+
+  /** Optional icon hint for the UI (lucide name or single emoji). */
+  @UnifiedField({
+    description: 'Icon hint (e.g. lucide name or emoji)',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.S_USER,
+  })
+  icon?: string = undefined;
+
+  /** Display label shown in the prompt picker. */
+  @UnifiedField({ description: 'Display label', mongoose: { index: true }, roles: RoleEnum.S_USER })
+  name: string = undefined;
+
+  /** Owner user id (the creator). Set automatically on create. */
+  @UnifiedField({
+    description: 'Owner user id',
+    mongoose: { index: true },
+    roles: RoleEnum.S_USER,
+  })
+  ownerId: string = undefined;
+
+  /** Sort order in the picker (ascending). */
+  @UnifiedField({
+    description: 'Sort order',
+    isOptional: true,
+    mongoose: { default: 100 },
+    roles: RoleEnum.S_USER,
+    type: () => Number,
+  })
+  order?: number = undefined;
+
+  /**
+   * Visibility scope: `'user'` (only the owner — "private") or `'tenant'`
+   * (members of the owner's tenant — "public").
+   */
+  @UnifiedField({
+    description: "Visibility scope ('user' = private, 'tenant' = public)",
+    mongoose: { default: 'user', index: true },
+    roles: RoleEnum.S_USER,
+  })
+  scope: string = undefined;
+
+  /** Tenant id when scope = 'tenant' (set from the creator's tenant at create time). */
+  @UnifiedField({
+    description: 'Tenant id (when scope = "tenant")',
+    isOptional: true,
+    mongoose: { index: true },
+    roles: RoleEnum.S_USER,
+  })
+  tenantId?: string = undefined;
+
+  /**
+   * Filter prompts out of read responses the current user is not allowed to see.
+   * Update/delete authorization is enforced by the service layer.
+   */
+  override securityCheck(user: any, _force?: boolean): this {
+    if (!user) {
+      return undefined as any;
+    }
+    if (this.scope === 'tenant') {
+      const userTenantId = user.tenantId || user.currentTenantId || (user.tenantIds || [])[0];
+      if (this.ownerId === user.id || (this.tenantId && this.tenantId === String(userTenantId))) {
+        return this;
+      }
+      return undefined as any;
+    }
+    return this.ownerId === user.id ? this : (undefined as any);
+  }
+}
+
+export const AiPromptSchema = SchemaFactory.createForClass(CoreAiPrompt);
+// One prompt per (owner, name) — keeps the picker tidy.
+AiPromptSchema.index({ ownerId: 1, name: 1 }, { unique: true });

package/src/core/modules/ai/models/core-ai-response.model.ts

@@ -0,0 +1,119 @@
+import { Field, Int, ObjectType } from '@nestjs/graphql';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { JSON } from '../../../common/scalars/json.scalar';
+import { CoreAiAction } from './core-ai-action.model';
+import { CoreAiBudgetSummary } from './core-ai-usage-info.model';
+import { CoreAiUsage } from './core-ai-usage.model';
+
+/**
+ * Structured response of an AI prompt.
+ *
+ * The frontend renders {@link text} as the natural-language answer, may render
+ * {@link data} as structured output (tables/cards), and can show {@link actions}
+ * for transparency about what the assistant did.
+ */
+@ObjectType({ description: 'Structured response of an AI prompt' })
+@Restricted(RoleEnum.S_EVERYONE)
+export class CoreAiResponse {
+  /**
+   * Tool actions executed while answering.
+   */
+  @Field(() => [CoreAiAction], { description: 'Tool actions executed while answering', nullable: true })
+  actions?: CoreAiAction[];
+
+  /**
+   * Compact token-budget summary (this prompt's cost, remaining/used, reset time).
+   */
+  @Field(() => CoreAiBudgetSummary, { description: 'Compact token-budget summary', nullable: true })
+  budget?: CoreAiBudgetSummary;
+
+  /**
+   * Id of the AI connection used.
+   */
+  @Field(() => String, { description: 'Id of the AI connection used', nullable: true })
+  connectionId?: string;
+
+  /**
+   * Conversation id for multi-turn continuation.
+   */
+  @Field(() => String, { description: 'Conversation id for multi-turn continuation', nullable: true })
+  conversationId?: string;
+
+  /**
+   * Whether the run was aborted because the user lacked permission for at least
+   * one planned action (plan mode, all-or-nothing). Nothing was executed.
+   */
+  @Field(() => Boolean, { description: 'Whether the run was aborted due to missing permissions', nullable: true })
+  denied?: boolean;
+
+  /**
+   * Planned actions the user is NOT permitted to perform (when `denied`).
+   */
+  @Field(() => [CoreAiAction], { description: 'Planned actions the user may not perform', nullable: true })
+  deniedActions?: CoreAiAction[];
+
+  /**
+   * Optional structured data the frontend can render.
+   */
+  @Field(() => JSON, { description: 'Optional structured data for the frontend to render', nullable: true })
+  data?: unknown;
+
+  /**
+   * Number of agent-loop iterations performed.
+   */
+  @Field(() => Int, { description: 'Number of agent-loop iterations performed', nullable: true })
+  iterations?: number;
+
+  /**
+   * The planned actions (plan mode), for transparency.
+   */
+  @Field(() => [CoreAiAction], { description: 'Planned actions (plan mode)', nullable: true })
+  plan?: CoreAiAction[];
+
+  /**
+   * Mutating/destructive tool actions awaiting confirmation. Re-send the prompt
+   * with `confirm: true` to execute them.
+   */
+  @Field(() => [CoreAiAction], {
+    description: 'Actions awaiting confirmation',
+    nullable: true,
+  })
+  pendingActions?: CoreAiAction[];
+
+  /**
+   * Optional clarifying question raised by the assistant via the built-in
+   * `ask_user_question` tool. When set, the run paused to collect more input from
+   * the user instead of guessing — the client should render this and send the user's
+   * answer as the next prompt to continue the conversation.
+   */
+  @Field(() => JSON, { description: 'Pending clarifying question from the assistant', nullable: true })
+  pendingQuestion?: { options?: { label: string; value: string }[]; question: string };
+
+  /**
+   * Whether the response is awaiting confirmation of destructive actions.
+   */
+  @Field(() => Boolean, { description: 'Whether confirmation of destructive actions is required', nullable: true })
+  requiresConfirmation?: boolean;
+
+  /**
+   * Natural-language answer for the user.
+   */
+  @Field(() => String, { description: 'Natural-language answer for the user' })
+  text: string;
+
+  /**
+   * Token usage (best effort).
+   */
+  @Field(() => CoreAiUsage, { description: 'Token usage (best effort)', nullable: true })
+  usage?: CoreAiUsage;
+
+  /**
+   * Context-window utilization at the end of the run. Used by frontends to render
+   * a "closing-circle" indicator when the conversation approaches the model's limit.
+   * `total` is the model's window size; `used` is the assembled-messages token estimate.
+   */
+  @Field(() => JSON, { description: 'Context-window utilization (used/total tokens)', nullable: true })
+  contextWindow?: { total: number; used: number };
+}

package/src/core/modules/ai/models/core-ai-slot.model.ts

@@ -0,0 +1,146 @@
+import { ObjectType } from '@nestjs/graphql';
+import { Schema as MongooseSchema, SchemaFactory } from '@nestjs/mongoose';
+import { Document } from 'mongoose';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { CorePersistenceModel } from '../../../common/models/core-persistence.model';
+
+export type AiSlotDocument = CoreAiSlot & Document;
+
+/**
+ * Admin-editable building block of the SYSTEM prompt.
+ *
+ * The system prompt is assembled from keyed slots (see `CoreAiPromptBuilderService`):
+ * each {@link key} is a logical slot (e.g. `base`, `permissions`, `anti_hallucination`,
+ * `output_contract`, `tool_protocol_emulated`). The framework ships sensible built-in
+ * defaults for every key, so the module works with zero rows; a row here **overrides**
+ * the default for its key (optionally scoped by `locale`/`capability`).
+ *
+ * Tenancy: when multi-tenancy is active, an admin's slot is tenant-scoped — it only
+ * applies to prompts running in that admin's tenant. Without multi-tenancy, slots are
+ * effectively system-wide. The framework's built-in (`isSystem = true`) defaults are
+ * NOT stored in this collection; admin "overrides" of a built-in are regular rows
+ * matching the key.
+ *
+ * `content` may contain `{{placeholders}}` (see {@link CoreAiPlaceholderRegistry} for
+ * the runtime-resolved list).
+ */
+@MongooseSchema({ collection: 'aiSlots', timestamps: true })
+@ObjectType({ description: 'Admin-editable building block (fragment) of the AI system prompt' })
+@Restricted(RoleEnum.ADMIN)
+export class CoreAiSlot extends CorePersistenceModel {
+  /**
+   * Capability filter: 'all' (default), 'native' or 'emulated' — limits the slot
+   * to runs with that tool-calling mode.
+   */
+  @UnifiedField({
+    description: "Capability scope: 'all', 'native' or 'emulated'",
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  capability?: string = undefined;
+
+  /**
+   * Slot text. May contain `{{placeholders}}` (see placeholder registry).
+   */
+  @UnifiedField({
+    description: 'Slot text — supports placeholder tokens; the active registry is served by GET /ai/placeholders',
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  content: string = undefined;
+
+  /**
+   * Admin-facing description of what this slot does.
+   */
+  @UnifiedField({
+    description: 'Admin-facing description of the slot',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  description?: string = undefined;
+
+  /**
+   * Whether the slot is active (disabled slots are skipped — used to "hide" a
+   * built-in default for a specific tenant without losing the row).
+   */
+  @UnifiedField({
+    description: 'Whether the slot is included in the prompt',
+    isOptional: true,
+    mongoose: { default: true },
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  enabled?: boolean = undefined;
+
+  /**
+   * Logical slot key (e.g. `base`, `permissions`, `anti_hallucination`).
+   * A row whose `key` matches a built-in system slot overrides it for the slot's tenant.
+   */
+  @UnifiedField({
+    description: "Logical prompt slot key (e.g. 'base', 'permissions', 'anti_hallucination')",
+    mongoose: { index: true },
+    roles: RoleEnum.ADMIN,
+  })
+  key: string = undefined;
+
+  /**
+   * Optional locale ('en', 'de', …). When set, the slot is only used for that
+   * language; otherwise it applies to all languages.
+   */
+  @UnifiedField({
+    description: "Locale (e.g. 'en', 'de'); empty = all languages",
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  locale?: string = undefined;
+
+  /**
+   * Assembly order (ascending). Lower numbers appear earlier in the prompt.
+   */
+  @UnifiedField({
+    description: 'Assembly order (ascending)',
+    isOptional: true,
+    mongoose: { default: 100 },
+    roles: RoleEnum.ADMIN,
+    type: () => Number,
+  })
+  order?: number = undefined;
+
+  /**
+   * Optional scope-filter this slot applies to. Empty/undefined = always applies.
+   * Recognized prefixes: `tool:<name>` (only when that tool is in scope), `role:<name>`
+   * (only when the user has that role), `mode:<name>` (only when running in this named
+   * mode — see {@link CoreAiMode}). Multiple filters can be expressed by creating
+   * multiple rows with the same key.
+   */
+  @UnifiedField({
+    description: "Scope filter (e.g. 'tool:get_user', 'role:admin', 'mode:support'); empty = always",
+    isOptional: true,
+    mongoose: { index: true },
+    roles: RoleEnum.ADMIN,
+  })
+  scope?: string = undefined;
+
+  /**
+   * Tenant id the slot applies to. Auto-set from the creating admin's tenant when
+   * multi-tenancy is active. Without multi-tenancy this stays undefined and the
+   * slot is effectively system-wide.
+   */
+  @UnifiedField({
+    description: 'Tenant id the slot applies to (auto-set; undefined = system-wide)',
+    isOptional: true,
+    mongoose: { index: true },
+    roles: RoleEnum.ADMIN,
+  })
+  tenantId?: string = undefined;
+}
+
+export const AiSlotSchema = SchemaFactory.createForClass(CoreAiSlot);
+// Compound index for the common lookup (effective slots by key + locale + capability + tenant).
+AiSlotSchema.index({ key: 1, locale: 1, capability: 1, tenantId: 1 });

package/src/core/modules/ai/models/core-ai-tool-grant.model.ts

@@ -0,0 +1,87 @@
+import { ObjectType } from '@nestjs/graphql';
+import { Schema as MongooseSchema, SchemaFactory } from '@nestjs/mongoose';
+import { Document } from 'mongoose';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { CorePersistenceModel } from '../../../common/models/core-persistence.model';
+
+export type AiToolGrantDocument = CoreAiToolGrant & Document;
+
+/**
+ * Persistent permission decision so end users don't have to re-confirm the same
+ * mutating action over and over. When the user confirms a mutating tool with
+ * `prompt.input.rememberDecision: 'user' | 'tenant' | 'conversation'`, the
+ * orchestrator persists a grant here. Subsequent calls to the same tool by the
+ * same scope skip the confirmation gate — until the grant expires or an admin
+ * revokes it.
+ *
+ * Grants only ever say "skip the confirmation gate" — they never relax the
+ * permission model itself (`@Restricted`, `@Roles`, `authorize()` and scoped
+ * tool-policies still apply). `destructive` tools are excluded from grants by
+ * convention: irreversible actions always confirm.
+ */
+@MongooseSchema({ collection: 'aiToolGrants', timestamps: true })
+@ObjectType({ description: 'Persistent permission decision for a mutating tool' })
+@Restricted(RoleEnum.ADMIN)
+export class CoreAiToolGrant extends CorePersistenceModel {
+  /** Decision: only 'allow' is persisted today; 'deny' is reserved for future use. */
+  @UnifiedField({
+    description: "Decision ('allow' or 'deny')",
+    isOptional: true,
+    mongoose: { default: 'allow' },
+    roles: RoleEnum.ADMIN,
+  })
+  decision?: string = undefined;
+
+  /** Whether the grant is active (an admin can deactivate without deleting). */
+  @UnifiedField({
+    description: 'Whether the grant is active',
+    isOptional: true,
+    mongoose: { default: true },
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  enabled?: boolean = undefined;
+
+  /** Optional TTL — when set, the grant auto-expires via a Mongo TTL index. */
+  @UnifiedField({
+    description: 'Optional expiry timestamp',
+    isOptional: true,
+    mongoose: { index: { expireAfterSeconds: 0 } },
+    roles: RoleEnum.ADMIN,
+    type: () => Date,
+  })
+  expiresAt?: Date = undefined;
+
+  /**
+   * Reference id for the scope: user id, tenant id, or conversation id.
+   */
+  @UnifiedField({
+    description: 'Reference id for the scope (user/tenant/conversation id)',
+    mongoose: { index: true },
+    roles: RoleEnum.ADMIN,
+  })
+  refId: string = undefined;
+
+  /** Scope: 'user' (this user, anywhere), 'tenant' (this tenant), 'conversation' (just this thread). */
+  @UnifiedField({
+    description: "Scope: 'user', 'tenant' or 'conversation'",
+    mongoose: { index: true },
+    roles: RoleEnum.ADMIN,
+  })
+  scope: string = undefined;
+
+  /** The tool name this grant applies to. */
+  @UnifiedField({
+    description: 'Tool name the grant applies to',
+    mongoose: { index: true },
+    roles: RoleEnum.ADMIN,
+  })
+  tool: string = undefined;
+}
+
+export const AiToolGrantSchema = SchemaFactory.createForClass(CoreAiToolGrant);
+// One active grant per (scope, refId, tool).
+AiToolGrantSchema.index({ scope: 1, refId: 1, tool: 1 }, { unique: true });

package/src/core/modules/ai/models/core-ai-tool-policy.model.ts

@@ -0,0 +1,115 @@
+import { Field, ObjectType } from '@nestjs/graphql';
+import { Schema as MongooseSchema, SchemaFactory } from '@nestjs/mongoose';
+import { Document } from 'mongoose';
+
+import { Restricted } from '../../../common/decorators/restricted.decorator';
+import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { CorePersistenceModel } from '../../../common/models/core-persistence.model';
+import { JSON } from '../../../common/scalars/json.scalar';
+
+export type AiToolPolicyDocument = CoreAiToolPolicy & Document;
+
+/**
+ * A fine-grained allow/deny/ask rule against a tool's arguments. See
+ * {@link CoreAiToolPolicy}.
+ */
+@ObjectType({ description: 'A scoped allow/deny/ask rule for a tool call' })
+export class CoreAiToolPolicyRule {
+  /** 'allow' (run without gate), 'deny' (refuse), or 'ask' (route through the confirmation gate). */
+  @Field(() => String, { description: "Decision: 'allow', 'deny' or 'ask'" })
+  action: string;
+
+  /** Which argument key the pattern matches against (e.g. `sql`, `collection`). */
+  @Field(() => String, { description: 'Argument key the pattern matches against' })
+  argument: string;
+
+  /** RegExp source matched against `String(arguments[argument])`. */
+  @Field(() => String, { description: 'RegExp source matched against the argument value' })
+  pattern: string;
+
+  /** Optional flags for the RegExp (e.g. 'i'). */
+  @Field(() => String, { description: 'Optional RegExp flags', nullable: true })
+  flags?: string;
+
+  /** Optional human-readable reason — surfaced as the deny/ask message. */
+  @Field(() => String, { description: 'Optional human-readable reason', nullable: true })
+  reason?: string;
+}
+
+/**
+ * Admin-editable, fine-grained allow/deny/ask rules against tool calls. The
+ * confirmation/permission model stays as-is on top — this layer ADDS extra
+ * gating against the arguments of an otherwise-permitted call, without forcing
+ * a project to wrap their tools in custom logic.
+ *
+ * Evaluation order per matching policy: every `deny` rule wins (immediately),
+ * then `ask`, then `allow`. No matching rule → default = behave as before
+ * (tool's own `mutating`/`destructive` flags decide).
+ *
+ * Scope chain: `tool` (always) optionally narrowed by `role`, `tenant` or
+ * `user`. A more specific scope wins over a more generic one. Hints only ever
+ * tighten or relax the confirmation gate; the underlying permission model
+ * (`@Restricted`, `@Roles`, `authorize()`) is enforced regardless.
+ */
+@MongooseSchema({ collection: 'aiToolPolicies', timestamps: true })
+@ObjectType({ description: 'Admin-editable scoped policy for a tool call' })
+@Restricted(RoleEnum.ADMIN)
+export class CoreAiToolPolicy extends CorePersistenceModel {
+  /** Whether the policy is active. */
+  @UnifiedField({
+    description: 'Whether the policy is active',
+    isOptional: true,
+    mongoose: { default: true },
+    roles: RoleEnum.ADMIN,
+    type: () => Boolean,
+  })
+  enabled?: boolean = undefined;
+
+  /** Admin-facing label for the policy (just for UX, never read by code). */
+  @UnifiedField({
+    description: 'Admin-facing label',
+    isOptional: true,
+    mongoose: true,
+    roles: RoleEnum.ADMIN,
+  })
+  label?: string = undefined;
+
+  /** Reference id for the scope: empty when scope is 'global' or 'tool'. */
+  @UnifiedField({
+    description: 'Reference id for the scope (user/tenant id or role name)',
+    isOptional: true,
+    mongoose: { index: true },
+    roles: RoleEnum.ADMIN,
+  })
+  refId?: string = undefined;
+
+  /** The rule set evaluated against the call's arguments. */
+  @UnifiedField({
+    description: 'Rule set',
+    isOptional: true,
+    mongoose: { default: [] },
+    roles: RoleEnum.ADMIN,
+    type: () => JSON,
+  })
+  rules?: { action: string; argument: string; flags?: string; pattern: string; reason?: string }[] = undefined;
+
+  /** Scope: 'tool' (any user), 'role', 'tenant' or 'user'. */
+  @UnifiedField({
+    description: "Scope: 'tool', 'role', 'tenant' or 'user'",
+    mongoose: { index: true },
+    roles: RoleEnum.ADMIN,
+  })
+  scope: string = undefined;
+
+  /** The tool name this policy applies to. */
+  @UnifiedField({
+    description: 'Tool name the policy applies to',
+    mongoose: { index: true },
+    roles: RoleEnum.ADMIN,
+  })
+  tool: string = undefined;
+}
+
+export const AiToolPolicySchema = SchemaFactory.createForClass(CoreAiToolPolicy);
+AiToolPolicySchema.index({ scope: 1, refId: 1, tool: 1 });