@tiledesk/tiledesk-server 2.28.2 → 3.0.0

package/controllers/intents.controller.js

@@ -0,0 +1,139 @@
+const Intent = require("../models/faq");
+const AppError = require("../utils/AppError");
+const faqBotEvent = require("../event/faqBotEvent");
+const winston = require("../config/winston");
+
+const INTENT_FIELDS = [
+  "intent_display_name",
+  "intent_id",
+  "question",
+  "answer",
+  "reply",
+  "form",
+  "enabled",
+  "webhook_enabled",
+  "language",
+  "actions",
+  "attributes"
+];
+
+class IntentsController {
+
+  constructor() { }
+
+  _mapIntent(chatbot_id, id_project, user_id, intent) {
+    const mapped = {
+      id_faq_kb: chatbot_id,
+      id_project,
+      createdBy: user_id
+    };
+    for (const field of INTENT_FIELDS) {
+      if (intent[field] !== undefined) {
+        mapped[field] = intent[field];
+      }
+    }
+    return mapped;
+  }
+
+  async create(chatbot_id, id_project, user_id, intent, { skipDuplicates = false } = {}) {
+    try {
+      const faq = await Intent.create(
+        this._mapIntent(chatbot_id, id_project, user_id, intent)
+      );
+      faqBotEvent.emit("faq.create", faq);
+      return faq;
+    } catch (err) {
+      if (err.code === 11000) {
+        if (skipDuplicates) {
+          winston.debug("Skip duplicated intent_display_name");
+          return null;
+        }
+        throw new AppError(409, "Duplicate intent_display_name");
+      }
+      winston.error("(IntentsController) create error: ", err);
+      throw new AppError(500, "Error creating intent");
+    }
+  }
+
+  async createMany(chatbot_id, id_project, user_id, intents, options) {
+    if (!intents?.length) {
+      return [];
+    }
+    const results = await Promise.allSettled(
+      intents.map((intent) =>
+        this.create(chatbot_id, id_project, user_id, intent, options)
+      )
+    );
+    return results
+      .filter((r) => r.status === "fulfilled" && r.value)
+      .map((r) => r.value);
+  }
+
+  async upsert(chatbot_id, id_project, user_id, intent) {
+    try {
+      const savingResult = await Intent.findOneAndUpdate(
+        { id_faq_kb: chatbot_id, intent_display_name: intent.intent_display_name },
+        this._mapIntent(chatbot_id, id_project, user_id, intent),
+        { new: true, upsert: true, rawResult: true }
+      );
+
+      if (!savingResult?.value) {
+        return null;
+      }
+
+      if (savingResult.lastErrorObject?.updatedExisting === true) {
+        winston.verbose("updated existing intent");
+        faqBotEvent.emit("faq.update", savingResult.value);
+      } else {
+        winston.verbose("new intent created");
+        faqBotEvent.emit("faq.create", savingResult.value);
+      }
+
+      return savingResult.value;
+    } catch (err) {
+      winston.error("(IntentsController) upsert error: ", err);
+      throw new AppError(500, "Error upserting intent");
+    }
+  }
+
+  async upsertMany(chatbot_id, id_project, user_id, intents) {
+    if (!intents?.length) {
+      return [];
+    }
+    const results = await Promise.allSettled(
+      intents.map((intent) =>
+        this.upsert(chatbot_id, id_project, user_id, intent)
+      )
+    );
+    return results
+      .filter((r) => r.status === "fulfilled" && r.value)
+      .map((r) => r.value);
+  }
+
+  async deleteByChatbotId(chatbot_id) {
+    try {
+      const result = await Intent.deleteMany({ id_faq_kb: chatbot_id });
+      winston.verbose("All faq for chatbot " + chatbot_id + " deleted successfully");
+      return result;
+    } catch (err) {
+      winston.error("(IntentsController) deleteByChatbotId error: ", err);
+      throw new AppError(500, `Error deleting intents for chatbot ${chatbot_id}`);
+    }
+  }
+
+  async getIntents(chatbot_id) {
+    try {
+      const intents = await Intent
+        .find({ id_faq_kb: chatbot_id })
+        .lean()
+        .exec();
+      return intents;
+    } catch (err) {
+      winston.error("(IntentsController) getIntents error: ", err);
+      throw new AppError(500, `Error finding intents with chatbot id ${chatbot_id}`);
+    }
+  }
+}
+
+const intentsController = new IntentsController();
+module.exports = intentsController;

package/errorCodes.js

@@ -29,7 +29,8 @@ const errorCodes = {
   CHATBOT: {
     BASE_CODE: 12000,
     ERRORS: {
-      DUPLICATE_SLUG: 12001
+      DUPLICATE_SLUG: 12001,
+      SUBAGENT_IN_USE: 12002
     }
   },
   WEBHOOK: {

package/event/botEvent.js

@@ -135,7 +135,9 @@ class BotEvent extends EventEmitter {
                 return;
             }
 
-            await Faq.updateMany({ id_faq_kb: chatbot._id }, { trashed: true, trashedAt: chatbot.trashedAt }).catch((err) => {
+            const trashedAt = chatbot.trashedAt || new Date();
+
+            await Faq.updateMany({ id_faq_kb: chatbot._id }, { trashed: true, trashedAt: trashedAt }).catch((err) => {
                 winston.error("Event faqbot.update.virtual.delete error updating faqs ", err);
             })
 
@@ -143,6 +145,9 @@ class BotEvent extends EventEmitter {
                 winston.error("Error deleting webhook on chatbot deleting: ", err);
             })
 
+            // Soft-delete subagents of the draft chatbot (+ their intents) so TTL applies
+            await trashSubagentsByParentIds([chatbot._id], trashedAt);
+
             let publishedChatbots = await Faq_kb.find({ root_id: chatbot._id }, { _id: 1 }).catch((err) => {
                 winston.error("Event faqbot.update.virtual.delete error getting all published chatbots ", err);
             })
@@ -161,13 +166,16 @@ class BotEvent extends EventEmitter {
                 for (const batch of batches) {
                     await Faq_kb.updateMany(
                         { _id: { $in: batch } },
-                        { $set: { trashed: true, trashedAt: chatbot.trashedAt } }
+                        { $set: { trashed: true, trashedAt: trashedAt } }
                     );
 
                     await Faq.updateMany(
                         { id_faq_kb: { $in: batch } },
-                        { $set: { trashed: true, trashedAt: chatbot.trashedAt } }
+                        { $set: { trashed: true, trashedAt: trashedAt } }
                     );
+
+                    // Soft-delete subagents linked to published copies (+ their intents)
+                    await trashSubagentsByParentIds(batch, trashedAt);
                 
                     await sleep(sleep_ms);
                 }                
@@ -175,6 +183,38 @@ class BotEvent extends EventEmitter {
             }
         })
 
+        async function trashSubagentsByParentIds(parentIds, trashedAt) {
+            if (!parentIds || parentIds.length === 0) {
+                return;
+            }
+
+            const parentIdStrings = parentIds.map(id => id.toString());
+            let subagents = await Faq_kb.find({ parent_id: { $in: parentIdStrings } }, { _id: 1 }).catch((err) => {
+                winston.error("Event faqbot.update.virtual.delete error getting subagents ", err);
+                return [];
+            });
+
+            if (!subagents || subagents.length === 0) {
+                return;
+            }
+
+            const subagentIds = subagents.map(s => s._id);
+
+            await Faq_kb.updateMany(
+                { _id: { $in: subagentIds } },
+                { $set: { trashed: true, trashedAt: trashedAt } }
+            ).catch((err) => {
+                winston.error("Event faqbot.update.virtual.delete error updating subagents ", err);
+            });
+
+            await Faq.updateMany(
+                { id_faq_kb: { $in: subagentIds } },
+                { $set: { trashed: true, trashedAt: trashedAt } }
+            ).catch((err) => {
+                winston.error("Event faqbot.update.virtual.delete error updating subagent faqs ", err);
+            });
+        }
+
         function sleep(ms) {
             return new Promise(resolve => setTimeout(resolve, ms));
           }

package/middleware/errorHandler.js

@@ -0,0 +1,41 @@
+const AppError = require('../utils/AppError');
+const winston = require('../config/winston');
+
+function errorHandler(err, req, res, next) {
+  if (err instanceof AppError) {
+    winston.error(err.message, err);
+    return res.status(err.status).json({
+      success: false,
+      message: err.message
+    });
+  }
+
+  winston.debug("err.name", err.name);
+  if (err.name === "IpDeniedError") {
+    winston.debug("IpDeniedError");
+    return res.status(401).json({ err: "error ip filter" });
+  }
+
+  const realIp = req.headers['x-forwarded-for']?.split(',')[0] || req.headers['x-real-ip'] || req.ip;
+
+  // emitted by multer when the file is too big
+  if (err.code === "LIMIT_FILE_SIZE") {
+    winston.debug("LIMIT_FILE_SIZE");
+    winston.warn(`LIMIT_FILE_SIZE on ${req.originalUrl}`, {
+      limit: process.env.MAX_UPLOAD_FILE_SIZE,
+      ip: req.ip,
+      realIp: realIp
+    });
+    return res.status(413).json({ err: "Content Too Large", limit_file_size: process.env.MAX_UPLOAD_FILE_SIZE });
+  }
+
+  if (err.type === "entity.too.large" || err.name === "PayloadTooLargeError") {
+    winston.warn("Payload too large", { expected: err.expected, limit: err.limit, length: err.length });
+    return res.status(413).json({ err: "Request entity too large", limit: err.limit });
+  }
+
+  winston.error("General error: ", err);
+  return res.status(500).json({ err: "error" });
+}
+
+module.exports = errorHandler;

package/models/chatbotTemplates.js

@@ -18,5 +18,9 @@ module.exports = {
     voice_twilio: {
         default: 'blank_voice_twilio',
         templates: ['empty', 'blank_voice_twilio']
+    },
+    subagent: {
+        default: 'blank_subagent',
+        templates: ['empty', 'blank_subagent']
     }
 }

package/models/faq.js

@@ -192,6 +192,16 @@ FaqSchema.index(
   { partialFilterExpression: { "actions.namespace": { $exists: true } } }
 );
 
+FaqSchema.index(
+  { "actions.botId": 1 },
+  { partialFilterExpression: { "actions.botId": { $exists: true } } }
+);
+
+FaqSchema.index(
+  { "actions.botSlug": 1 },
+  { partialFilterExpression: { "actions.botSlug": { $exists: true } } }
+);
+
 FaqSchema.index(
   { trashedAt: 1 },
   { expireAfterSeconds: trashExpirationTime }

package/models/faq_kb.js

@@ -7,6 +7,26 @@ const { stringify } = require('uuid');
 var defaultFullTextLanguage = process.env.DEFAULT_FULLTEXT_INDEX_LANGUAGE || "none";
 let trashExpirationTime = Number(process.env.CHATBOT_TRASH_TTL_SECONDS) || 60 * 60 * 24 * 30; // 30 days
 
+const ConnectorRecordSchema = new Schema({
+  id: { type: String, required: true },
+  from: {
+    intentId: { type: String, required: true },
+    actionId: { type: String, required: true },
+    slot: { type: String, required: true }
+  },
+  to: {
+    intentId: { type: String, required: true }
+  },
+  kind: { type: String, enum: ['block', 'action', 'button', 'case', 'branch'], required: true },
+  props: { type: Object, required: false }
+}, { _id: false });
+
+const ConnectorsSchema = new Schema({
+  version: { type: Number, required: true },
+  updatedAt: { type: Date, required: false },
+  items: { type: [ConnectorRecordSchema], default: undefined }
+}, { _id: false });
+
 var Faq_kbSchema = new Schema({
   name: {
     type: String,
@@ -77,6 +97,21 @@ var Faq_kbSchema = new Schema({
   attributes: {
     type: Object,
   },
+  /** The Design Studio version the agent was created for: 'v3' for an agent of the Design Studio V3,
+   *  absent for every other agent. Written by whoever creates the agent, never changed afterwards. */
+  ds_version: {
+    type: String,
+    enum: ['v3'],
+    required: false
+  },
+  /** V3 agents only: the connectors list, the only truth about the links between blocks
+   *  (see services/v3FlowService.js). Not selected by default: the lists of bots, the widget and
+   *  the JWT never carry it; the single GET, the export and the engine ask for it explicitly. */
+  connectors: {
+    type: ConnectorsSchema,
+    required: false,
+    select: false
+  },
   createdBy: {
     type: String,
     required: true
@@ -161,6 +196,10 @@ var Faq_kbSchema = new Schema({
   release_note: {
     type: String,
     required: false
+  },
+  parent_id: {
+    type: String,
+    required: false
   }
 },{
   timestamps: true
@@ -248,6 +287,16 @@ Faq_kbSchema.index(
   { unique: true, partialFilterExpression: { slug: { $exists: true } } }
 );
 
+Faq_kbSchema.index(
+  { id_project: 1, subtype: 1 },
+  { partialFilterExpression: { subtype: { $ne: "subagent" } } }
+);
+
+Faq_kbSchema.index(
+  { id_project: 1, parent_id: 1 },
+  { partialFilterExpression: { parent_id: { $exists: true } } }
+);
+
 Faq_kbSchema.index(
   { trashedAt: 1 },
   { expireAfterSeconds: trashExpirationTime }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tiledesk/tiledesk-server",
   "description": "The Tiledesk server module",
-  "version": "2.28.2",
+  "version": "3.0.0",
   "scripts": {
     "start": "node ./bin/www",
     "pretest": "mongodb-runner start",
@@ -49,7 +49,7 @@
     "@tiledesk/tiledesk-rasa-connector": "^1.0.10",
     "@tiledesk/tiledesk-sms-connector": "^0.1.13",
     "@tiledesk/tiledesk-telegram-connector": "^0.1.14",
-    "@tiledesk/tiledesk-tybot-connector": "^2.1.15",
+    "@tiledesk/tiledesk-tybot-connector": "^2.3.0",
     "@tiledesk/tiledesk-voice-twilio-connector": "^0.3.2",
     "@tiledesk/tiledesk-vxml-connector": "^0.1.91",
     "@tiledesk/tiledesk-whatsapp-connector": "1.0.31",

package/pubmodules/aiGenerations/README.md

@@ -0,0 +1,154 @@
+# Modulo `aiGenerations` — storia e ripristino degli agenti
+
+Ogni agente creato o modificato con l'AI conserva la sua storia in una collection a parte, `faq_kb_revisions`, e ogni versione si può ripristinare. Il Design Studio manda al server, in una sola richiesta, l'agente compilato e i dati della generazione (prompt, intervista, Blueprint): il server crea l'agente e i suoi blocchi, salva uno snapshot compresso dell'agente con la sua impronta, e risponde con l'id dell'agente e la revisione 1. Da lì in poi ogni pubblicazione viene collegata alla storia, l'utente può salvare una versione quando vuole, e può ripristinare qualunque revisione o release nella bozza (con gli stessi id dei blocchi) o come agente nuovo. Prima di ogni ripristino o modifica via prompt il server salva da solo la versione corrente, quindi nessuna operazione perde lavoro e ogni ripristino è a sua volta reversibile. Nell'agente non resta nulla: il percorso dei messaggi non è toccato. Il modulo è isolato, si accende con `AI_GENERATIONS_ENABLED=true`, e con la variabile spenta il server è identico a prima.
+
+---
+
+## 1. Attivazione e indipendenza
+
+| Variabile | Default | Effetto |
+|---|---|---|
+| `AI_GENERATIONS_ENABLED` | assente | Con `true` il modulo viene caricato e montato su `/:projectid/modules/ai-generations` (ruolo `admin`). Altrimenti nessuna rotta, nessun model, nessuna collection |
+| `AI_GENERATIONS_TRANSACTIONS` | rilevamento automatico | `true`/`false` forzano l'uso delle transazioni MongoDB. Di default si usano se il database è un replica set |
+| `AI_GENERATIONS_MAX_INTENTS` | 1000 | Blocchi massimi per agente e operazioni massime per modifica |
+| `AI_GENERATIONS_MAX_PER_AGENT` | 50 | Revisioni massime per agente |
+| `AI_GENERATIONS_MAX_CHECKPOINTS` | 20 | Checkpoint manuali conservati per agente |
+| `AI_GENERATIONS_AUTO_TTL_DAYS` | 30 | Giorni di conservazione delle revisioni automatiche |
+| `AI_GENERATIONS_CLEANUP_ENABLED` | assente | Con `true` registra un listener su `faqbot.delete` e `faqbot.deleted`: alla cancellazione di un agente si cancella la sua storia, anche fuori dal DS |
+| `AI_GENERATIONS_AUTOSNAPSHOT_ENABLED` | assente | Con `true` registra un listener su `faq.create`, `faq.update` e `faq.delete`: dopo modifiche a mano ai blocchi si salva una revisione `auto` / `manual_changes`, solo se i blocchi sono cambiati rispetto all'ultima revisione |
+| `AI_GENERATIONS_AUTOSNAPSHOT_DEBOUNCE_MS` | 300000 | Attesa dopo l'ultimo evento prima dello snapshot automatico (un timer per agente) |
+| `AI_GENERATIONS_AUTOSNAPSHOT_RECENT_MS` | = debounce | Una revisione più recente di così è opera del modulo (ripristino, modifica): lo snapshot automatico non scatta |
+
+Il modulo vive tutto in `pubmodules/aiGenerations/`. L'unico aggancio sono tre blocchi in `pubmodules/pubModulesManager.js`, sullo schema del modulo `canned`: il campo nel costruttore, il `require` condizionato in `init()`, il `app.use` in `useUnderProjects()`. Del codice esistente il modulo **usa** i model `faq_kb`, `faq`, `department`, `Namespace` e `Table` (in lettura), il servizio `faqService.create`, e gli emettitori `botEvent` e `faqBotEvent`; non modifica nessuna rotta, nessun model, nessun servizio. Registra listener solo con le due variabili di pulizia e snapshot automatico. Il limite del body è quello globale (`JSON_BODY_LIMIT`, 500 KB di default).
+
+```
+pubmodules/aiGenerations/
+  index.js                      esporta aiGenerationsRoute
+  models/faqKbRevision.js       model 'faq_kb_revision' → collection 'faq_kb_revisions'
+  routes/aiGenerations.js       le rotte
+  services/snapshot.js          snapshot, impronta, compressione (funzioni pure)
+  services/revisionService.js   lettura dello stato, creazione dei record, conservazione
+  services/agentWriter.js       scritture sull'agente: creazione, sostituzione dei blocchi, operazioni
+  services/atomic.js            transazione se disponibile
+  services/references.js        prova a secco: riferimenti esterni mancanti (solo letture)
+  listeners.js                  listener facoltativi: pulizia alla cancellazione, snapshot automatico
+  test/aiGenerationsRoute.js    test
+```
+
+## 2. Il record di revisione
+
+```js
+{
+  revision_id:  "uuid",               // generato dal server
+  id_project:   "…", id_faq_kb: "…",  // sempre dal request, mai dal body
+  seq:          3,                    // ordine nella storia dell'agente (unico per agente)
+  kind:         "restore",            // ai_create | ai_edit | checkpoint | auto | restore | release
+  reason:       "in_place",           // auto: before_ai_edit | before_restore; restore: in_place | as_copy
+  note:         "Ripristino della revisione 1",
+  parent_id:    "uuid",               // la revisione da cui si parte (per restore: quella ripristinata)
+  ai: {                               // solo ai_create e ai_edit: quello che manda il DS, opaco
+    request: { initialPrompt, finalPrompt, finalPromptEdited, interview, assumptions, unsupported },
+    result:  { blueprint, blueprintVersion, idMap, notes, warnings, model, promptVersion,
+               catalogVersion, compilerVersion, changes /* solo ai_edit, calcolato dal server */ }
+  },
+  snapshot: { encoding: "gzip+json", data: <Buffer>, bytes: 41200, intents: 6 },  // tutte tranne release
+  contentHash:  "sha256:…",           // impronta dei blocchi
+  release_id:   "…", publishedAt,     // solo release
+  createdBy:    "…", createdAt, updatedAt
+}
+```
+
+**Lo snapshot** ha la forma dell'export (`GET /faq_kb/exportjson/:id`): `name`, `description`, `language`, `webhook_*`, `type`, `subtype`, `attributes` **senza `globals`** (possono contenere segreti; al ripristino restano quelli correnti), e `intents` con i blocchi completi, `intent_id` compresi.
+
+**L'impronta** è lo sha256 dei blocchi normalizzati: ordinati per `intent_id`, senza `attributes.position` e `attributes.color`, con le chiavi in ordine. Spostare un blocco sul canvas non la cambia; cambiare un testo sì. Serve a due cose: sapere se l'agente è stato modificato a mano dopo l'ultima revisione, e rifiutare un ripristino o una modifica se l'agente è cambiato rispetto a quello che il client aveva visto (`expectedHash`).
+
+## 3. Le rotte
+
+Base: `/:projectid/modules/ai-generations`. Tutte filtrano per `id_project = req.projectid`; `createdBy` è sempre `req.user.id`.
+
+| Rotta | Body | Risposta |
+|---|---|---|
+| `GET /` | — | `{ enabled, transactions, max_intents }` |
+| `POST /agents` | `{ agent, ai, note }` — `agent` nel formato dell'export con `intents[]` | 201 `{ bot_id, chatbot, revision }`; 400 body non valido (nomi o id duplicati); 422 blocchi rifiutati dal model, con l'elenco |
+| `GET /agents/:id/revisions?page&limit` | — | `{ items, total, page, limit }`, ordinati per `seq` decrescente, **leggeri** (senza snapshot, `finalPrompt`, `blueprint`) |
+| `POST /agents/:id/revisions` | `{ note }` | 201 `{ revision }` (checkpoint) |
+| `POST /agents/:id/revisions/release` | `{ release_id }` | 201 `{ revision }`; 200 `{ already_linked: true }` se già collegata; 404 se la release non ha `root_id` = id |
+| `GET /agents/:id/hash` | — | `{ contentHash, intents, revision_id, revision_seq, modified }` |
+| `POST /agents/:id/restore` | `{ revision_id \| release_id, as_copy, expectedHash, note, name, dry_run }` | 200 `{ bot_id, revision, backup }`; con `as_copy` 201 con il nuovo `bot_id`; con `dry_run: true` 200 `{ dry_run, source, intents, contentHash, changed, missing[] }` senza scrivere (i riferimenti a dipartimenti, knowledge base, tabelle e agenti che non esistono più); 409 se `expectedHash` non coincide, se l'agente è cestinato, o se la revisione non ha snapshot |
+| `POST /agents/:id/edit` | `{ operations[], ai, expectedHash, note }` — `operations`: `{ type: post\|put\|delete, intent }` | 200 `{ bot_id, revision, backup, changes }`; 404 blocco non trovato; 409 nome duplicato o hash stantio |
+| `DELETE /agents/:id/revisions` | — | `{ deleted }` |
+| `GET /revisions/:revision_id?snapshot=true` | — | La revisione completa; con `snapshot=true` anche `snapshotData` in chiaro |
+
+Il ruolo richiesto è `admin`, come per la pubblicazione. Un agente di un altro progetto risponde 404.
+
+## 4. Il flusso, passo per passo
+
+### Creazione con l'AI (`POST /agents`)
+
+1. Validazione del body: nome, blocchi non vuoti, nessun `intent_display_name` o `intent_id` duplicato.
+2. Validazione dei blocchi con il model `faq`, **prima** di creare l'agente: gli errori si fermano qui senza scrivere nulla.
+3. `faqService.create` con `template: 'empty'` (emette `faqbot.create`, come l'import); se `attributes.rules` cita il bot, i partecipanti vengono ripuntati sul nuovo id.
+4. `Faq.insertMany` dei blocchi, atteso; se qualcosa fallisce, blocchi e agente vengono rimossi e la risposta è 422 o 500 con il motivo.
+5. Snapshot e impronta dai blocchi appena salvati; revisione `ai_create`, `seq 1`.
+6. Eventi: `faq.create` per ogni blocco e `faqbot.created`.
+7. Risposta 201. Il DS non deve più rileggere i blocchi per verificarli.
+
+### Ripristino in place (`POST /agents/:id/restore`)
+
+1. Carica l'agente (404 se non è del progetto, 409 se cestinato) e la sorgente: lo snapshot della revisione, oppure l'export della release indicata (che deve avere `root_id` = id).
+2. Calcola l'impronta corrente; se `expectedHash` è presente e diverso, 409.
+3. Se l'impronta corrente è diversa dall'ultima revisione con snapshot: revisione **`auto` / `before_restore`** con lo stato corrente. Le modifiche a mano non si perdono mai.
+4. Sostituisce i blocchi con gli **stessi `intent_id`**; aggiorna nome, descrizione, lingua e `attributes` (i `globals` correnti restano), `modified: true`.
+5. Revisione `restore` / `in_place`, con `parent_id` = la revisione ripristinata e il nuovo snapshot.
+6. Eventi: `faq.delete` per ogni blocco tolto, `faq.create` per ogni blocco inserito, `faqbot.update`. Sono gli eventi che svuotano la cache Redis per singolo blocco e per agente e avvisano gli iscritti.
+7. Conservazione (§6) e risposta con `revision` e `backup` (null se non è servito).
+
+La release pubblicata non cambia: per portare il ripristino in produzione si pubblica di nuovo.
+
+### Ripristino come copia (`as_copy: true`)
+
+Crea un agente nuovo dallo snapshot (nome a scelta, altrimenti «… (copia)»), con la stessa procedura della creazione, e apre in quello una storia nuova con una revisione `restore` / `as_copy` che rimanda alla revisione d'origine. L'agente di partenza non è toccato.
+
+### Modifica via prompt (`POST /agents/:id/edit`)
+
+Come il ripristino nei passi 1–3 (con `auto` / `before_ai_edit`), poi applica le operazioni una per una, attese: `post` crea, `put` aggiorna per `intent_id` (o `_id`), `delete` cancella. Un blocco non trovato dà 404, un nome duplicato 409, e senza transazione i blocchi di prima vengono rimessi. La revisione `ai_edit` porta `ai.result.changes = { added, updated, removed }` con gli `intent_id`, calcolato dal server.
+
+### Pubblicazione
+
+Il DS pubblica come oggi (`PUT /faq_kb/:id/publish` restituisce il `bot_id` della release) e poi chiama `POST /agents/:id/revisions/release`. La revisione `release` non ha snapshot: la release è già una copia completa, e si può usare come sorgente di un ripristino.
+
+## 5. Atomicità
+
+| Situazione | Strategia |
+|---|---|
+| **Replica set** (Atlas in produzione e stage): rilevato all'avvio con `hello` → `setName` | Ripristino e modifica girano in `session.withTransaction`: cancellazione, inserimento, aggiornamento dell'agente e revisione riescono o falliscono insieme. Gli eventi si emettono dopo il commit |
+| **Senza replica set** (sviluppo, `mongodb-runner`) | **Staging e scambio**: i blocchi da ripristinare si inseriscono prima sotto un id di staging (`<id>~restore~<timestamp>`), dove validazione e indici unici possono fallire senza toccare la bozza; poi si cancellano i blocchi correnti e si sposta lo staging sull'agente con un `updateMany`. Se lo spostamento fallisce, i blocchi di prima vengono rimessi |
+| **Sempre** | La revisione `auto` prima di qualunque scrittura è la rete di sicurezza: è consultabile e ripristinabile a sua volta |
+| **Creazione** | Validazione prima di scrivere; se l'inserimento fallisce, blocchi e agente vengono rimossi (compreso il documento residuo che il listener di tilebot può ricreare con il suo upsert asincrono dell'url) |
+
+## 6. Conservazione
+
+A ogni checkpoint, ripristino o modifica: si tengono tutte le `ai_create`, `ai_edit` e `release`; le ultime 20 `checkpoint`; le `auto` degli ultimi 30 giorni; in tutto al più 50 record per agente, togliendo prima le `checkpoint`, `auto` e `restore` più vecchie. L'ultima revisione non si tocca mai. `DELETE /agents/:id/revisions` cancella la storia; i record di agenti eliminati fuori dal DS restano orfani e innocui.
+
+## 7. Test
+
+```bash
+# solo il modulo (Redis e MongoDB locali; il .env di sviluppo si può sostituire con DOTENV_PATH)
+AI_GENERATIONS_ENABLED=true NODE_ENV=test npx mocha pubmodules/aiGenerations/test/*.js --exit
+
+# ramo a modulo spento: le rotte rispondono 404
+AI_GENERATIONS_ENABLED=false NODE_ENV=test npx mocha pubmodules/aiGenerations/test/*.js --exit
+```
+
+Nella suite completa (`npm test`) l'app viene caricata dai primi file: il modulo è montato solo se `AI_GENERATIONS_ENABLED=true` è già nell'ambiente; altrimenti il test verifica il ramo a modulo spento. I test (21) coprono: creazione atomica e rollback, validazione, impronta (posizioni ignorate), checkpoint e lista leggera, isolamento fra progetti, ripristino in place con backup automatico e reversibilità, globals conservati, copia, release (collegamento, rifiuto di una release estranea, ripristino da release), agente cestinato, prova a secco, modifica con `changes`, hash stantio, cancellazione della storia, listener di pulizia e di snapshot automatico, snapshot e impronta.
+
+## 8. Fase F: prova a secco, pulizia, snapshot automatico
+
+- **Prova a secco** (`POST /agents/:id/restore` con `dry_run: true`): nessuna scrittura; risponde con i riferimenti dello snapshot che nel progetto non esistono più (`kind`: `department`, `knowledge_base`, `data_table`, `chatbot`, con il valore e il nome del blocco) e con l'impronta corrente. Il DS la chiama prima di ogni ripristino e lo dice all'utente.
+- **Pulizia** (`AI_GENERATIONS_CLEANUP_ENABLED=true`): la storia si cancella con l'agente, anche quando la cancellazione non passa dal DS.
+- **Snapshot automatico** (`AI_GENERATIONS_AUTOSNAPSHOT_ENABLED=true`): un timer per agente (debounce) dopo gli eventi dei blocchi; allo scadere, se l'impronta dei blocchi è diversa dall'ultima revisione e l'ultima revisione non è appena stata scritta dal modulo stesso, si salva una revisione `auto` / `manual_changes` (`createdBy: system`). Mai sulle release, mai sugli id di staging, mai senza una storia già esistente.
+
+## 9. Cosa non c'è ancora
+
+- L'agente **forkato o pubblico** in un altro progetto non porta con sé la storia.
+- Le transazioni sono provate solo con il rilevamento: su un replica set locale il ramo `withTransaction` va collaudato.

package/pubmodules/aiGenerations/index.js

@@ -0,0 +1,7 @@
+const aiGenerationsRoute = require('./routes/aiGenerations');
+const listeners = require('./listeners');
+
+// Listener facoltativi (pulizia alla cancellazione, snapshot automatico): ognuno dietro la sua variabile.
+listeners.register();
+
+module.exports = { aiGenerationsRoute, listeners };

package/pubmodules/aiGenerations/listeners.js

@@ -0,0 +1,96 @@
+/**
+ * Listener facoltativi del modulo (fase F), ognuno dietro la sua variabile d'ambiente:
+ *
+ * - AI_GENERATIONS_CLEANUP_ENABLED=true: alla cancellazione di un agente (`faqbot.delete`, `faqbot.deleted`)
+ *   si cancella la sua storia, anche se la cancellazione non passa dal DS.
+ * - AI_GENERATIONS_AUTOSNAPSHOT_ENABLED=true: dopo modifiche a mano ai blocchi (`faq.create`, `faq.update`,
+ *   `faq.delete`) si salva una revisione `auto` / `manual_changes`, al più una ogni
+ *   AI_GENERATIONS_AUTOSNAPSHOT_DEBOUNCE_MS (default 5 minuti) per agente, e solo se i blocchi sono
+ *   davvero cambiati rispetto all'ultima revisione.
+ *
+ * Con le variabili spente non si registra nulla.
+ */
+const winston = require('../../config/winston');
+const botEvent = require('../../event/botEvent');
+const faqBotEvent = require('../../event/faqBotEvent');
+const Faq_kb = require('../../models/faq_kb');
+const revisionService = require('./services/revisionService');
+
+const DEBOUNCE_MS = Number(process.env.AI_GENERATIONS_AUTOSNAPSHOT_DEBOUNCE_MS) || 5 * 60 * 1000;
+/** Una revisione più recente di così è opera del modulo (ripristino, modifica): non è una modifica a mano. */
+const RECENT_MS = Number(process.env.AI_GENERATIONS_AUTOSNAPSHOT_RECENT_MS) || DEBOUNCE_MS;
+const pending = new Map();
+
+function botIdOf(payload) {
+  const bot = payload && (payload.chatbot || payload);
+  const id = bot && (bot._id || bot.id);
+  return id ? String(id) : null;
+}
+
+async function cleanup(payload) {
+  const id_faq_kb = botIdOf(payload);
+  if (!id_faq_kb) return;
+  try {
+    const bot = payload && (payload.chatbot || payload);
+    const id_project = bot && bot.id_project ? String(bot.id_project) : null;
+    const filter = id_project ? { id_project: id_project, id_faq_kb: id_faq_kb } : { id_faq_kb: id_faq_kb };
+    const result = await revisionService.deleteByFilter(filter);
+    if (result) winston.debug('(aiGenerations) cleanup: deleted ' + result + ' revisions of ' + id_faq_kb);
+  } catch (err) {
+    winston.error('(aiGenerations) cleanup failed for ' + id_faq_kb + ': ' + err.message);
+  }
+}
+
+async function snapshot(id_faq_kb) {
+  pending.delete(id_faq_kb);
+  try {
+    const kb = await Faq_kb.findById(id_faq_kb).exec();
+    if (!kb || kb.trashed === true || kb.root_id) return;  // mai sulle release
+    const state = await revisionService.currentState(kb);
+    const last = await revisionService.lastRevision(String(kb.id_project), id_faq_kb, { contentHash: { $ne: null } });
+    if (!last || last.contentHash === state.contentHash) return;  // niente storia: niente snapshot automatici; niente cambiamenti: niente
+    // Una revisione appena scritta: i blocchi sono cambiati per un ripristino o una modifica del modulo, non a mano
+    if (Date.now() - new Date(last.createdAt).getTime() < RECENT_MS) return;
+    await revisionService.create({
+      id_project: String(kb.id_project),
+      id_faq_kb: kb._id,
+      kind: 'auto',
+      reason: 'manual_changes',
+      note: 'Modifiche a mano dopo la revisione ' + last.seq,
+      parent_id: last.revision_id,
+      snapshot: state.snapshot,
+      contentHash: state.contentHash,
+      createdBy: 'system'
+    });
+    await revisionService.prune(String(kb.id_project), id_faq_kb);
+    winston.debug('(aiGenerations) autosnapshot saved for ' + id_faq_kb);
+  } catch (err) {
+    winston.error('(aiGenerations) autosnapshot failed for ' + id_faq_kb + ': ' + err.message);
+  }
+}
+
+function schedule(faq) {
+  const id_faq_kb = faq && faq.id_faq_kb ? String(faq.id_faq_kb) : null;
+  if (!id_faq_kb || id_faq_kb.indexOf('~') !== -1) return;  // niente sugli id di staging
+  if (pending.has(id_faq_kb)) return;
+  const timer = setTimeout(() => snapshot(id_faq_kb), DEBOUNCE_MS);
+  if (timer.unref) timer.unref();
+  pending.set(id_faq_kb, timer);
+}
+
+function register() {
+  const registered = [];
+  if (process.env.AI_GENERATIONS_CLEANUP_ENABLED === 'true') {
+    botEvent.on('faqbot.delete', cleanup);
+    botEvent.on('faqbot.deleted', cleanup);
+    registered.push('cleanup');
+  }
+  if (process.env.AI_GENERATIONS_AUTOSNAPSHOT_ENABLED === 'true') {
+    ['faq.create', 'faq.update', 'faq.delete'].forEach(name => faqBotEvent.on(name, schedule));
+    registered.push('autosnapshot');
+  }
+  if (registered.length) winston.info('(aiGenerations) listeners: ' + registered.join(', '));
+  return registered;
+}
+
+module.exports = { register, cleanup, snapshot, schedule, DEBOUNCE_MS, RECENT_MS, pendingCount: () => pending.size, isPending: (id) => pending.has(String(id)) };