@tiledesk/tiledesk-server 2.28.2 → 3.0.0

package/pubmodules/aiGenerations/services/agentWriter.js

@@ -0,0 +1,286 @@
+/**
+ * Le scritture sull'agente: creazione, sostituzione dei blocchi, operazioni sui blocchi.
+ * Usa i model e il servizio esistenti (`faq_kb`, `faq`, `faqService`) senza modificarli.
+ *
+ * Gli eventi (`faqbot.*`, `faq.*`) NON vengono emessi qui: chi chiama li emette dopo che
+ * la scrittura è andata a buon fine (dopo il commit, con le transazioni), con `emitEvents`.
+ */
+const winston = require('../../../config/winston');
+const Faq_kb = require('../../../models/faq_kb');
+const Faq = require('../../../models/faq');
+const faqService = require('../../../services/faqService');
+const botEvent = require('../../../event/botEvent');
+const faqBotEvent = require('../../../event/faqBotEvent');
+
+class WriteError extends Error {
+  constructor(status, message, details) {
+    super(message);
+    this.status = status;
+    this.details = details;
+  }
+}
+
+/** Il documento `faq` da un blocco nel formato dell'export (come importjson). */
+function intentDoc(intent, ctx) {
+  return {
+    id_faq_kb: String(ctx.id_faq_kb),
+    id_project: ctx.id_project,
+    createdBy: ctx.createdBy,
+    intent_display_name: intent.intent_display_name,
+    intent_id: intent.intent_id,
+    question: intent.question,
+    answer: intent.answer,
+    reply: intent.reply,
+    form: intent.form,
+    enabled: intent.enabled,
+    webhook_enabled: intent.webhook_enabled,
+    language: intent.language,
+    actions: intent.actions,
+    attributes: intent.attributes,
+    agents_available: intent.agents_available
+  };
+}
+
+/** Le regole in `attributes` che citano il bot come partecipante vanno ripuntate sul nuovo id (come importjson). */
+function rewriteRules(attributes, bot_id) {
+  if (!attributes || !Array.isArray(attributes.rules)) return attributes;
+  attributes.rules.forEach(rule => {
+    const message = rule && rule.do && rule.do[0] && rule.do[0].message;
+    if (message && Array.isArray(message.participants) && message.participants.length) {
+      message.participants[0] = 'bot_' + bot_id;
+    }
+  });
+  return attributes;
+}
+
+/** Gli errori di un insertMany non ordinato, in forma leggibile. */
+function bulkErrors(err) {
+  const writeErrors = (err && (err.writeErrors || (err.result && err.result.getWriteErrors && err.result.getWriteErrors()))) || [];
+  if (!writeErrors.length) return [{ message: err && err.message }];
+  return writeErrors.map(e => ({
+    index: e.index,
+    code: e.code,
+    message: e.errmsg || e.message,
+    intent_display_name: e.err && e.err.op && e.err.op.intent_display_name
+  }));
+}
+
+class AgentWriter {
+
+  /**
+   * Crea un agente e i suoi blocchi. Se un blocco fallisce, cancella tutto e lancia un WriteError.
+   * Restituisce { kb, faqs }.
+   */
+  async createAgent(id_project, createdBy, agent) {
+    const data = {
+      name: agent.name,
+      description: agent.description,
+      language: agent.language || 'en',
+      type: agent.type || 'tilebot',
+      subtype: agent.subtype || 'chatbot',
+      webhook_enabled: !!agent.webhook_enabled,
+      webhook_url: agent.webhook_url,
+      mainCategory: agent.mainCategory,
+      intentsEngine: agent.intentsEngine,
+      template: 'empty',
+      attributes: agent.attributes || {}
+    };
+
+    // I blocchi si validano PRIMA di creare l'agente: quasi tutti gli errori si fermano qui,
+    // senza scrivere nulla.
+    await this.validateBlocks(agent.intents || [], { id_faq_kb: 'validation', id_project: id_project, createdBy: createdBy });
+
+    let kb;
+    try {
+      kb = await faqService.create(id_project, createdBy, data);
+    } catch (err) {
+      throw new WriteError(500, 'Error creating chatbot', { error: String(err) });
+    }
+
+    try {
+      if (data.attributes && Array.isArray(data.attributes.rules) && data.attributes.rules.length) {
+        rewriteRules(data.attributes, kb._id);
+        kb = await Faq_kb.findByIdAndUpdate(kb._id, { attributes: data.attributes }, { new: true }).exec();
+      }
+      const faqs = await this.insertBlocks(String(kb._id), id_project, createdBy, agent.intents || [], null);
+      return { kb: kb, faqs: faqs };
+    } catch (err) {
+      winston.error('(aiGenerations) createAgent failed, removing chatbot ' + kb._id + ': ' + err.message);
+      await this.removeAgent(kb._id);
+      if (err instanceof WriteError) throw err;
+      throw new WriteError(500, 'Error creating chatbot blocks', { error: err.message });
+    }
+  }
+
+  /**
+   * Rimuove un agente appena creato e i suoi blocchi (rollback della creazione).
+   * Il listener di tilebot su `faqbot.create` aggiorna l'url con un upsert asincrono: se arriva dopo
+   * la cancellazione, lascia un documento con il solo url. Una seconda pulizia, poco dopo, toglie
+   * quel documento, riconoscibile perché senza nome.
+   */
+  async removeAgent(kb_id) {
+    await Faq.deleteMany({ id_faq_kb: String(kb_id) }).exec().catch(() => null);
+    await Faq_kb.findByIdAndDelete(kb_id).exec().catch(() => null);
+    setTimeout(() => {
+      Faq_kb.deleteOne({ _id: kb_id, name: { $exists: false } }).exec()
+        .then(result => { if (result && result.deletedCount) winston.debug('(aiGenerations) removed upsert leftover of ' + kb_id); })
+        .catch(() => null);
+    }, 2000).unref();
+  }
+
+  /**
+   * Validazione esplicita dei blocchi con il model: con `ordered: false` mongoose salterebbe in
+   * silenzio i documenti non validi. Qui si rifiuta tutto, e si dice quali blocchi e perché.
+   */
+  async validateBlocks(intents, ctx) {
+    const invalid = [];
+    await Promise.all(intents.map((intent, index) => {
+      const doc = intentDoc(intent, ctx);
+      return new Faq(doc).validate().catch(err => {
+        invalid.push({ index: index, intent_display_name: doc.intent_display_name, message: err.message });
+      });
+    }));
+    if (invalid.length) {
+      invalid.sort((a, b) => a.index - b.index);
+      throw new WriteError(422, 'Some blocks are not valid', { blocks: invalid });
+    }
+  }
+
+  /**
+   * Inserisce i blocchi sotto `id_faq_kb`. Non ordinato: si sa esattamente quali sono falliti.
+   * Se uno fallisce, i blocchi inseriti da questa chiamata vengono tolti e si lancia un WriteError 422.
+   */
+  async insertBlocks(id_faq_kb, id_project, createdBy, intents, session) {
+    if (!intents.length) return [];
+    const ctx = { id_faq_kb: id_faq_kb, id_project: id_project, createdBy: createdBy };
+    await this.validateBlocks(intents, ctx);
+    const docs = intents.map(intent => intentDoc(intent, ctx));
+
+    const options = { ordered: false };
+    if (session) options.session = session;
+    try {
+      const saved = await Faq.insertMany(docs, options);
+      if (saved.length !== docs.length) {
+        throw new Error('inserted ' + saved.length + ' of ' + docs.length + ' blocks');
+      }
+      return saved.map(doc => (typeof doc.toObject === 'function' ? doc.toObject() : doc));
+    } catch (err) {
+      const errors = bulkErrors(err);
+      winston.error('(aiGenerations) insertBlocks failed for ' + id_faq_kb + ': ' + JSON.stringify(errors));
+      if (!session) {
+        await Faq.deleteMany({ id_faq_kb: id_faq_kb }).exec().catch(() => null);
+      }
+      throw new WriteError(422, 'Some blocks could not be saved', { blocks: errors });
+    }
+  }
+
+  /**
+   * Sostituisce i blocchi dell'agente con quelli dello snapshot, con gli stessi intent_id.
+   * - Con la sessione (transazione): cancella e inserisce nella stessa transazione.
+   * - Senza: inserisce prima in staging (validazione e indici falliscono lì, senza toccare la bozza),
+   *   poi cancella i blocchi correnti e sposta lo staging sull'agente. Se lo spostamento fallisce,
+   *   rimette i blocchi di prima.
+   * Restituisce { removed, inserted } con i documenti, per gli eventi.
+   */
+  async replaceBlocks(kb, snapshot, id_project, createdBy, session) {
+    const id_faq_kb = String(kb._id);
+    const current = await Faq.find({ id_faq_kb: id_faq_kb }).session(session || null).lean().exec();
+
+    if (session) {
+      await Faq.deleteMany({ id_faq_kb: id_faq_kb }).session(session).exec();
+      const inserted = await this.insertBlocks(id_faq_kb, id_project, createdBy, snapshot.intents || [], session);
+      return { removed: current, inserted: inserted };
+    }
+
+    const staging = id_faq_kb + '~restore~' + Date.now();
+    await this.insertBlocks(staging, id_project, createdBy, snapshot.intents || [], null);
+
+    await Faq.deleteMany({ id_faq_kb: id_faq_kb }).exec();
+    try {
+      await Faq.updateMany({ id_faq_kb: staging }, { $set: { id_faq_kb: id_faq_kb } }).exec();
+    } catch (err) {
+      winston.error('(aiGenerations) replaceBlocks swap failed for ' + id_faq_kb + ', restoring previous blocks: ' + err.message);
+      await Faq.deleteMany({ id_faq_kb: { $in: [id_faq_kb, staging] } }).exec().catch(() => null);
+      if (current.length) await Faq.insertMany(current, { ordered: false }).catch(e => winston.error('(aiGenerations) recovery failed: ' + e.message));
+      throw new WriteError(500, 'Error replacing blocks, previous blocks restored', { error: err.message });
+    }
+    const inserted = await Faq.find({ id_faq_kb: id_faq_kb }).lean().exec();
+    return { removed: current, inserted: inserted };
+  }
+
+  /** Aggiorna i campi dell'agente dallo snapshot. I `globals` correnti restano. */
+  async updateAgentFromSnapshot(kb, snapshot, session) {
+    const currentAttributes = (kb.attributes && typeof kb.attributes === 'object') ? kb.attributes : {};
+    const attributes = Object.assign({}, snapshot.attributes || {});
+    if (currentAttributes.globals !== undefined) attributes.globals = currentAttributes.globals;
+    rewriteRules(attributes, kb._id);
+    const update = { attributes: attributes, modified: true };
+    ['name', 'description', 'language', 'webhook_enabled', 'webhook_url'].forEach(field => {
+      if (snapshot[field] !== undefined) update[field] = snapshot[field];
+    });
+    const options = { new: true };
+    if (session) options.session = session;
+    return Faq_kb.findByIdAndUpdate(kb._id, update, options).exec();
+  }
+
+  async setModified(kb_id, session) {
+    const options = { new: true };
+    if (session) options.session = session;
+    return Faq_kb.findByIdAndUpdate(kb_id, { modified: true }, options).exec();
+  }
+
+  /**
+   * Applica operazioni sui blocchi (come `ops_update`, ma attese e con gli errori riportati):
+   * `{ type: 'post' | 'put' | 'delete', intent }`. `put` e `delete` trovano il blocco per `intent_id`
+   * (o per `_id`). Restituisce { created, updated, deleted } con i documenti.
+   */
+  async applyOperations(kb, operations, id_project, createdBy, session) {
+    const id_faq_kb = String(kb._id);
+    const result = { created: [], updated: [], deleted: [] };
+    const options = session ? { session: session } : {};
+
+    for (let i = 0; i < operations.length; i++) {
+      const op = operations[i] || {};
+      const intent = op.intent || {};
+      const selector = intent.intent_id ? { id_faq_kb: id_faq_kb, intent_id: intent.intent_id } : { id_faq_kb: id_faq_kb, _id: intent._id };
+      try {
+        if (op.type === 'post') {
+          const created = await Faq.create([intentDoc(intent, { id_faq_kb: id_faq_kb, id_project: id_project, createdBy: createdBy })], options);
+          result.created.push(created[0].toObject());
+        } else if (op.type === 'put') {
+          const fields = intentDoc(intent, { id_faq_kb: id_faq_kb, id_project: id_project, createdBy: createdBy });
+          delete fields.createdBy;
+          Object.keys(fields).forEach(key => { if (fields[key] === undefined) delete fields[key]; });
+          const updated = await Faq.findOneAndUpdate(selector, { $set: fields }, Object.assign({ new: true }, options)).exec();
+          if (!updated) throw new WriteError(404, 'Block not found for put', { index: i, intent_id: intent.intent_id });
+          result.updated.push(updated.toObject());
+        } else if (op.type === 'delete') {
+          const deleted = await Faq.findOneAndDelete(selector, options).exec();
+          if (!deleted) throw new WriteError(404, 'Block not found for delete', { index: i, intent_id: intent.intent_id });
+          result.deleted.push(deleted.toObject());
+        } else {
+          throw new WriteError(400, 'Unknown operation type', { index: i, type: op.type });
+        }
+      } catch (err) {
+        if (err instanceof WriteError) throw err;
+        const status = err && err.code === 11000 ? 409 : 500;
+        throw new WriteError(status, 'Operation ' + i + ' (' + op.type + ') failed', { index: i, error: err.message });
+      }
+    }
+    return result;
+  }
+
+  /** Emette gli eventi che svuotano la cache e avvisano gli iscritti, come fanno le rotte esistenti. */
+  emitEvents(events) {
+    (events.deletedFaqs || []).forEach(faq => faqBotEvent.emit('faq.delete', faq));
+    (events.createdFaqs || []).forEach(faq => faqBotEvent.emit('faq.create', faq));
+    (events.updatedFaqs || []).forEach(faq => faqBotEvent.emit('faq.update', faq));
+    if (events.updatedBot) botEvent.emit('faqbot.update', events.updatedBot);
+    if (events.createdBot) botEvent.emit('faqbot.created', events.createdBot);
+  }
+}
+
+module.exports = new AgentWriter();
+module.exports.AgentWriter = AgentWriter;
+module.exports.WriteError = WriteError;
+module.exports.intentDoc = intentDoc;

package/pubmodules/aiGenerations/services/atomic.js

@@ -0,0 +1,70 @@
+/**
+ * Esecuzione atomica dove il database lo consente.
+ *
+ * Con MongoDB in replica set (Atlas in produzione e stage) le scritture di una operazione
+ * girano in una transazione: riescono o falliscono insieme. Senza replica set (sviluppo,
+ * test con mongodb-runner) la funzione gira senza sessione e chi la usa applica la strategia
+ * di staging e scambio, con la revisione automatica come rete di sicurezza.
+ *
+ * `AI_GENERATIONS_TRANSACTIONS=false` spegne le transazioni anche in replica set;
+ * `=true` le forza (utile per provare il ramo su un replica set locale).
+ */
+const mongoose = require('mongoose');
+const winston = require('../../../config/winston');
+
+let supported = null;
+
+async function detect() {
+  const forced = process.env.AI_GENERATIONS_TRANSACTIONS;
+  if (forced === 'true') return true;
+  if (forced === 'false') return false;
+  try {
+    const admin = mongoose.connection.db.admin();
+    let info;
+    try {
+      info = await admin.command({ hello: 1 });
+    } catch (e) {
+      info = await admin.command({ isMaster: 1 });
+    }
+    return !!(info && (info.setName || info.msg === 'isdbgrid'));
+  } catch (err) {
+    winston.warn('(aiGenerations) unable to detect replica set, transactions disabled: ' + err.message);
+    return false;
+  }
+}
+
+/** True se le transazioni sono disponibili. Il risultato è calcolato una volta sola. */
+async function supportsTransactions() {
+  if (supported === null) {
+    supported = await detect();
+    winston.info('(aiGenerations) transactions ' + (supported ? 'enabled' : 'disabled'));
+  }
+  return supported;
+}
+
+/** Per i test: azzera il rilevamento. */
+function reset() {
+  supported = null;
+}
+
+/**
+ * Esegue `fn(session)`. Con le transazioni disponibili `session` è una sessione in transazione,
+ * altrimenti è null. Il valore restituito da `fn` è il valore restituito da `run`.
+ */
+async function run(fn) {
+  if (!(await supportsTransactions())) {
+    return fn(null);
+  }
+  const session = await mongoose.startSession();
+  let result;
+  try {
+    await session.withTransaction(async () => {
+      result = await fn(session);
+    });
+  } finally {
+    session.endSession();
+  }
+  return result;
+}
+
+module.exports = { run, supportsTransactions, reset };

package/pubmodules/aiGenerations/services/references.js

@@ -0,0 +1,78 @@
+/**
+ * Prova a secco del ripristino: i riferimenti esterni di uno snapshot che nel progetto non esistono più.
+ * Dipartimenti (per nome), knowledge base (per id), tabelle (per id) e altri agenti (per id).
+ * Solo letture.
+ */
+const mongoose = require('mongoose');
+const Department = require('../../../models/department');
+const { Namespace } = require('../../../models/kb_setting');
+const { Table } = require('../../../models/dataTable');
+const Faq_kb = require('../../../models/faq_kb');
+
+const isObjectId = (id) => typeof id === 'string' && /^[0-9a-fA-F]{24}$/.test(id) && mongoose.Types.ObjectId.isValid(id);
+
+/** I riferimenti esterni dei blocchi dello snapshot, per tipo. */
+function collectReferences(snapshot) {
+  const refs = { department: [], knowledge_base: [], data_table: [], chatbot: [] };
+  (snapshot && Array.isArray(snapshot.intents) ? snapshot.intents : []).forEach(intent => {
+    const name = intent.intent_display_name;
+    (Array.isArray(intent.actions) ? intent.actions : []).forEach(action => {
+      if (!action || typeof action !== 'object') return;
+      switch (action._tdActionType) {
+        case 'department':
+          if (action.depName) refs.department.push({ value: String(action.depName), intent_display_name: name });
+          break;
+        case 'askgptv2':
+        case 'add_kb_content':
+          if (action.namespace && !action.namespaceAsName) refs.knowledge_base.push({ value: String(action.namespace), intent_display_name: name });
+          break;
+        case 'data_table':
+          if (action.tableId) refs.data_table.push({ value: String(action.tableId), intent_display_name: name });
+          break;
+        case 'replacebotv3':
+          if (action.botId && !action.useSlug) refs.chatbot.push({ value: String(action.botId), intent_display_name: name });
+          break;
+        default:
+          break;
+      }
+    });
+  });
+  return refs;
+}
+
+/**
+ * @returns {Promise<Array<{ kind: string, value: string, intent_display_name: string }>>} i riferimenti mancanti
+ */
+async function missingReferences(snapshot, id_project) {
+  const refs = collectReferences(snapshot);
+  const missing = [];
+  const values = (list) => Array.from(new Set(list.map(r => r.value)));
+
+  if (refs.department.length) {
+    const names = values(refs.department);
+    const found = await Department.find({ id_project: id_project, name: { $in: names } }, { name: 1 }).lean().exec();
+    const ok = new Set(found.map(d => d.name));
+    refs.department.filter(r => !ok.has(r.value)).forEach(r => missing.push({ kind: 'department', ...r }));
+  }
+  if (refs.knowledge_base.length) {
+    const ids = values(refs.knowledge_base);
+    const found = await Namespace.find({ id_project: id_project, id: { $in: ids } }, { id: 1 }).lean().exec();
+    const ok = new Set(found.map(n => String(n.id)));
+    refs.knowledge_base.filter(r => !ok.has(r.value)).forEach(r => missing.push({ kind: 'knowledge_base', ...r }));
+  }
+  if (refs.data_table.length) {
+    const ids = values(refs.data_table).filter(isObjectId);
+    const found = ids.length ? await Table.find({ id_project: id_project, _id: { $in: ids } }, { _id: 1 }).lean().exec() : [];
+    const ok = new Set(found.map(t => String(t._id)));
+    refs.data_table.filter(r => !ok.has(r.value)).forEach(r => missing.push({ kind: 'data_table', ...r }));
+  }
+  if (refs.chatbot.length) {
+    const ids = values(refs.chatbot).filter(isObjectId);
+    const found = ids.length ? await Faq_kb.find({ id_project: id_project, _id: { $in: ids }, trashed: { $ne: true } }, { _id: 1 }).lean().exec() : [];
+    const ok = new Set(found.map(b => String(b._id)));
+    refs.chatbot.filter(r => !ok.has(r.value)).forEach(r => missing.push({ kind: 'chatbot', ...r }));
+  }
+  return missing;
+}
+
+module.exports = { collectReferences, missingReferences };

package/pubmodules/aiGenerations/services/revisionService.js

@@ -0,0 +1,169 @@
+/**
+ * Le revisioni: lettura dello stato corrente di un agente, creazione dei record, conservazione.
+ * Scrive solo su `faq_kb_revisions`; legge `faq_kbs` e `faqs`.
+ */
+const uuidv4 = require('uuid/v4');
+const winston = require('../../../config/winston');
+const Faq_kb = require('../../../models/faq_kb');
+const Faq = require('../../../models/faq');
+const FaqKbRevision = require('../models/faqKbRevision');
+const snapshotUtil = require('./snapshot');
+
+const MAX_PER_AGENT = Number(process.env.AI_GENERATIONS_MAX_PER_AGENT) || 50;
+const MAX_CHECKPOINTS = Number(process.env.AI_GENERATIONS_MAX_CHECKPOINTS) || 20;
+const AUTO_TTL_DAYS = Number(process.env.AI_GENERATIONS_AUTO_TTL_DAYS) || 30;
+
+/** Proiezione leggera per le liste: niente snapshot, prompt finale e Blueprint. */
+const LIGHT_PROJECTION = { 'snapshot.data': 0, 'ai.request.finalPrompt': 0, 'ai.result.blueprint': 0 };
+
+class RevisionService {
+
+  /** L'agente del progetto, oppure null. */
+  async getAgent(id_project, id_faq_kb, session) {
+    const query = Faq_kb.findOne({ _id: id_faq_kb, id_project: id_project });
+    if (session) query.session(session);
+    return query.exec();
+  }
+
+  /** I blocchi dell'agente, come documenti lean. */
+  async getBlocks(id_faq_kb, session) {
+    const query = Faq.find({ id_faq_kb: id_faq_kb }).sort({ createdAt: 1, _id: 1 }).lean();
+    if (session) query.session(session);
+    return query.exec();
+  }
+
+  /** Lo stato corrente: agente, blocchi, snapshot e impronta. */
+  async currentState(kb, session) {
+    const faqs = await this.getBlocks(String(kb._id), session);
+    const kbObject = typeof kb.toObject === 'function' ? kb.toObject() : kb;
+    const snapshot = snapshotUtil.buildSnapshot(kbObject, faqs);
+    return { kb, faqs, snapshot, contentHash: snapshotUtil.hashIntents(snapshot.intents) };
+  }
+
+  /** L'ultima revisione dell'agente, con o senza filtro; null se non ce ne sono. */
+  async lastRevision(id_project, id_faq_kb, filter, session) {
+    const query = FaqKbRevision.findOne(Object.assign({ id_project: id_project, id_faq_kb: id_faq_kb }, filter || {})).sort({ seq: -1 });
+    if (session) query.session(session);
+    return query.exec();
+  }
+
+  async getRevision(id_project, revision_id, session) {
+    const query = FaqKbRevision.findOne({ id_project: id_project, revision_id: revision_id });
+    if (session) query.session(session);
+    return query.exec();
+  }
+
+  /**
+   * Crea una revisione. `data.snapshot`, se presente, è lo snapshot in chiaro e viene compresso qui.
+   * La sequenza è calcolata all'interno; in caso di concorrenza sullo stesso numero si riprova.
+   */
+  async create(data, session) {
+    const doc = {
+      revision_id: uuidv4(),
+      id_project: data.id_project,
+      id_faq_kb: String(data.id_faq_kb),
+      kind: data.kind,
+      reason: data.reason || null,
+      note: data.note ? String(data.note).slice(0, 500) : undefined,
+      parent_id: data.parent_id || null,
+      ai: data.ai,
+      contentHash: data.contentHash || null,
+      release_id: data.release_id || null,
+      publishedAt: data.publishedAt,
+      createdBy: data.createdBy
+    };
+    if (data.snapshot) {
+      doc.snapshot = snapshotUtil.compress(data.snapshot);
+    }
+
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const last = await this.lastRevision(doc.id_project, doc.id_faq_kb, null, session);
+      doc.seq = last ? last.seq + 1 : 1;
+      try {
+        const saved = await FaqKbRevision.create([doc], session ? { session: session } : {});
+        return saved[0];
+      } catch (err) {
+        if (err && err.code === 11000 && attempt < 2) {
+          winston.debug('(aiGenerations) sequence collision, retrying: ' + doc.seq);
+          continue;
+        }
+        throw err;
+      }
+    }
+  }
+
+  /** La revisione senza lo snapshot binario, il prompt finale e il Blueprint. */
+  light(revision) {
+    if (!revision) return null;
+    const obj = typeof revision.toObject === 'function' ? revision.toObject() : JSON.parse(JSON.stringify(revision));
+    if (obj.snapshot) delete obj.snapshot.data;
+    if (obj.ai && obj.ai.request) delete obj.ai.request.finalPrompt;
+    if (obj.ai && obj.ai.result) delete obj.ai.result.blueprint;
+    return obj;
+  }
+
+  /** La revisione completa, con lo snapshot decompresso in `snapshotData` se richiesto. */
+  full(revision, withSnapshot) {
+    if (!revision) return null;
+    const obj = typeof revision.toObject === 'function' ? revision.toObject() : JSON.parse(JSON.stringify(revision));
+    if (withSnapshot && revision.snapshot && revision.snapshot.data) {
+      obj.snapshotData = snapshotUtil.decompress(revision.snapshot);
+    }
+    if (obj.snapshot) delete obj.snapshot.data;
+    return obj;
+  }
+
+  async list(id_project, id_faq_kb, page, limit) {
+    const filter = { id_project: id_project, id_faq_kb: id_faq_kb };
+    const [items, total] = await Promise.all([
+      FaqKbRevision.find(filter, LIGHT_PROJECTION).sort({ seq: -1 }).skip(page * limit).limit(limit).lean().exec(),
+      FaqKbRevision.countDocuments(filter).exec()
+    ]);
+    return { items: items, total: total, page: page, limit: limit };
+  }
+
+  async deleteAll(id_project, id_faq_kb) {
+    return this.deleteByFilter({ id_project: id_project, id_faq_kb: id_faq_kb });
+  }
+
+  async deleteByFilter(filter) {
+    const result = await FaqKbRevision.deleteMany(filter).exec();
+    return result.deletedCount || 0;
+  }
+
+  /**
+   * Conservazione per agente: si tengono tutte le revisioni AI e le release, le ultime
+   * MAX_CHECKPOINTS `checkpoint`, le `auto` più recenti di AUTO_TTL_DAYS giorni, e in tutto
+   * al più MAX_PER_AGENT record (si tolgono prima le più vecchie che non sono AI né release).
+   * Non tocca mai l'ultima revisione, di qualunque tipo.
+   */
+  async prune(id_project, id_faq_kb) {
+    const filter = { id_project: id_project, id_faq_kb: id_faq_kb };
+    const all = await FaqKbRevision.find(filter, { revision_id: 1, kind: 1, seq: 1, createdAt: 1 }).sort({ seq: -1 }).lean().exec();
+    if (!all.length) return 0;
+    const latest = all[0].revision_id;
+    const toDelete = new Set();
+
+    const checkpoints = all.filter(r => r.kind === 'checkpoint');
+    checkpoints.slice(MAX_CHECKPOINTS).forEach(r => toDelete.add(r.revision_id));
+
+    const autoLimit = Date.now() - AUTO_TTL_DAYS * 24 * 60 * 60 * 1000;
+    all.filter(r => r.kind === 'auto' && new Date(r.createdAt).getTime() < autoLimit).forEach(r => toDelete.add(r.revision_id));
+
+    const remaining = all.filter(r => !toDelete.has(r.revision_id));
+    if (remaining.length > MAX_PER_AGENT) {
+      const excess = remaining.length - MAX_PER_AGENT;
+      const removable = remaining.filter(r => ['checkpoint', 'auto', 'restore'].indexOf(r.kind) !== -1).reverse();
+      removable.slice(0, excess).forEach(r => toDelete.add(r.revision_id));
+    }
+    toDelete.delete(latest);
+    if (!toDelete.size) return 0;
+    const result = await FaqKbRevision.deleteMany({ id_project: id_project, revision_id: { $in: Array.from(toDelete) } }).exec();
+    winston.debug('(aiGenerations) pruned ' + result.deletedCount + ' revisions of ' + id_faq_kb);
+    return result.deletedCount || 0;
+  }
+}
+
+module.exports = new RevisionService();
+module.exports.RevisionService = RevisionService;
+module.exports.LIGHT_PROJECTION = LIGHT_PROJECTION;