@tiledesk/tiledesk-server 2.29.0 → 3.0.0

package/CHANGELOG.md

@@ -5,8 +5,24 @@
 🚀        IN PRODUCTION                        🚀
 (https://www.npmjs.com/package/@tiledesk/tiledesk-server/v/2.3.77) 
 
+
+# 3.0.0
+- Introduced the `aiGenerations` module for agent history and restoration of versions created or modified via AI, with retention options and cache invalidation per agent.
+- Atomic agent creation and editing: blocks are validated before saving, with rollback on errors and all changes (including AI edits and restores from previous versions or published releases) are revisioned.
+- Management of draft versions: manual checkpoints, automatic backups, links to published releases, comparison of changes, and dry-run to check for missing objects during restore.
+- Added optional listeners to keep history clean (e.g., delete history when the agent is deleted) and to create automatic backups after manual changes.
+- Improved V3 agent management: version (`ds_version`) and connectors (`connectors`) are now direct agent fields (no longer in `attributes`), with new GET/PUT endpoints for connector lists, automatic promotion of old properties, and checks on concurrent edit and list validity.
+- More flexible PATCH and PUT: attribute PATCH no longer rejects new V3 bot fields but "promotes" them, accepts preconditions via both header and query param (also for CORS gateways).
+- Maintained compatibility for pre-V3 agents: no impact on existing models and behaviors.
+- Improved V3 bot management: the `ds_version` and `connectors` fields are now direct properties of the bot, no longer in `attributes`.
+- Added new `GET` and `PUT` APIs on `/faq_kb/:id/connectors` to read or update connectors, with validation, concurrency control via `If-Match`, and support only for V3 agents.
+- During export, import, fork, publish, restore, and subagents, V3 fields are kept correctly or promoted if found in legacy JSON.
+- PATCH on attributes now rejects `dsVersion` and `connectors` written in the old style.
+- No changes for previous/non-V3 agents.
+- Added support for returning the blocks list (`GET /:projectid/faq`) without repeating the bot object in each row via the `populate=false` query param. Default behavior remains unchanged.
+
 # 2.29.0
-- Added support Subagents
+- Added support for Subagents
 - Bumped tybot-connector version to 2.3.0
 
 # 2.28.2

package/app.js

@@ -280,7 +280,7 @@ if (process.env.ENABLE_ALTERNATIVE_CORS_MIDDLEWARE === "true") {
   app.use(function (req, res, next) {
     res.header("Access-Control-Allow-Origin", "*"); //qui dice cequens attento
     // var request_cors_header = req.headers[""]
-    res.header("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept, Authorization, x-xsrf-token");
+    res.header("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept, Authorization, x-xsrf-token, If-Match");
     res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS')
     next();
   });

package/config/native_mcp/native_mcp_servers.json

@@ -14,5 +14,12 @@
         "native": true,
         "transport": "streamable_http",
         "description": "Tiledesk Data Table is a MCP server that allows you to manage data tables in the Tiledesk platform."
+    },
+    {
+        "id": "tiledesk-docsparse",
+        "name": "Tiledesk Docsparse",
+        "url": "https://stage.eks.tiledesk.com/mcp-tools/docsparse/mcp",
+        "transport": "streamable_http",
+        "description": "Tiledesk Docsparse is a MCP server that extracts the text of documents (PDF, Word, Excel, PowerPoint, CSV, email) from a URL, with OCR for scanned pages."
     }
 ]

package/controllers/chatbot.controller.js

@@ -5,6 +5,7 @@ const AppError = require("../utils/AppError");
 const intentsController = require("./intents.controller");
 const botEvent = require("../event/botEvent");
 const winston = require("../config/winston");
+const v3FlowService = require("../services/v3FlowService");
 
 const IMPORT_OVERRIDE_FIELDS = [
   "webhook_enabled",
@@ -51,10 +52,23 @@ class ChatbotController {
       subtype: subagent.subtype,
       description: subagent.description,
       attributes: subagent.attributes,
+      ...this._v3Fields(subagent),
       intents: (subagent.intents || []).map((intent) => this._sanitizeIntent(intent))
     };
   }
 
+  /** `ds_version` and `connectors` of a V3 agent, for the export; nothing for any other agent. */
+  _v3Fields(chatbot) {
+    const fields = {};
+    if (chatbot && chatbot.ds_version !== undefined && chatbot.ds_version !== null) {
+      fields.ds_version = chatbot.ds_version;
+    }
+    if (chatbot && chatbot.connectors !== undefined && chatbot.connectors !== null) {
+      fields.connectors = chatbot.connectors;
+    }
+    return fields;
+  }
+
   export(chatbot, intents, intentsOnly, subagents) {
     const sanitizedIntents = (intents || []).map((intent) => this._sanitizeIntent(intent));
 
@@ -72,6 +86,7 @@ class ChatbotController {
       subtype: chatbot.subtype,
       description: chatbot.description,
       attributes: chatbot.attributes,
+      ...this._v3Fields(chatbot),
       parent_id: chatbot.parent_id,
       intents: sanitizedIntents,
       subagents: (subagents || []).map((subagent) => this._sanitizeSubagent(subagent))
@@ -211,6 +226,8 @@ class ChatbotController {
       webhook_url: subagentJson.webhook_url,
       webhook_enabled: subagentJson.webhook_enabled,
       attributes: subagentJson.attributes,
+      ds_version: subagentJson.ds_version,
+      connectors: subagentJson.connectors,
       parent_id: parent_id.toString(),
       id_project: id_project.toString(),
       template: "empty"
@@ -227,7 +244,8 @@ class ChatbotController {
       if (select) {
         query = query.select(select);
       } else {
-        query = query.sort({ createdAt: -1 });
+        // Whole sub agents (export, restore): a V3 sub agent needs its connectors list too.
+        query = query.select('+connectors').sort({ createdAt: -1 });
       }
       return await query.lean().exec();
     } catch (err) {
@@ -311,7 +329,7 @@ class ChatbotController {
   async getChatbot(chatbot_id, id_project) {
     let chatbot;
     try {
-      chatbot = await Chatbot.findOne({ _id: chatbot_id, id_project: id_project });
+      chatbot = await Chatbot.findOne({ _id: chatbot_id, id_project: id_project }).select('+connectors');
     } catch (err) {
       winston.error("(ChatbotController) getChatbot error: ", err);
       throw new AppError(500, `Error finding chatbot with id ${chatbot_id}`);
@@ -325,7 +343,7 @@ class ChatbotController {
   async getChatbotById(chatbot_id) {
     let chatbot;
     try {
-      chatbot = await Chatbot.findById(chatbot_id);
+      chatbot = await Chatbot.findById(chatbot_id).select('+connectors');
     } catch (err) {
       winston.error("(ChatbotController) getChatbotById error: ", err);
       throw new AppError(500, `Error finding chatbot with id ${chatbot_id}`);
@@ -382,6 +400,7 @@ class ChatbotController {
       this._rewriteRulesParticipants(payload.attributes, subagent._id);
       subagent.attributes = payload.attributes;
     }
+    this._applyV3Fields(subagent, payload);
 
     try {
       subagent = await Chatbot.findByIdAndUpdate(subagent._id, subagent, { new: true });
@@ -453,10 +472,50 @@ class ChatbotController {
     });
   }
 
+  /** `ds_version` and `connectors` from an import payload onto a bot; nothing when the payload has none. */
+  _applyV3Fields(chatbot, payload) {
+    if (!payload) {
+      return;
+    }
+    if (payload.ds_version !== undefined && payload.ds_version !== null) {
+      chatbot.ds_version = payload.ds_version;
+    }
+    if (payload.connectors !== undefined && payload.connectors !== null) {
+      chatbot.connectors = payload.connectors;
+    }
+  }
+
+  /**
+   * A JSON exported before the two fields existed is promoted; a malformed list is refused before
+   * anything is written; a V3 agent whose JSON has no list (blocks still written the V2 way) is
+   * converted here, so it is stored in V3 form like any other.
+   */
+  _prepareImportedV3(json) {
+    v3FlowService.promoteLegacyJson(json);
+    const targets = [json, ...(Array.isArray(json.subagents) ? json.subagents : [])];
+    for (const target of targets) {
+      if (!target || !v3FlowService.isV3(target)) {
+        continue;
+      }
+      if (target.connectors === undefined || target.connectors === null) {
+        if (Array.isArray(target.intents)) {
+          target.connectors = v3FlowService.toV3Flow(target.intents).connectors;
+          winston.verbose("(ChatbotController) V3 import without a connectors list: built from the blocks, " + target.connectors.items.length + " records");
+        }
+        continue;
+      }
+      const errors = v3FlowService.validateConnectors(target.connectors);
+      if (errors.length > 0) {
+        throw new AppError(400, "Invalid connectors list: " + errors.join("; "));
+      }
+    }
+  }
+
   async import(json, id_project, chatbot_id, create, replace, overwrite, user_id, skipSubagents) {
     let chatbot;
     const sourceParentId = this._sourceId(json);
     this._stripImportedIdentity(json);
+    this._prepareImportedV3(json);
 
     if (create) {
       json.template = "empty";
@@ -488,6 +547,7 @@ class ChatbotController {
         this._rewriteRulesParticipants(json.attributes, chatbot._id);
         chatbot.attributes = json.attributes;
       }
+      this._applyV3Fields(chatbot, json);
 
       try {
         chatbot = await Chatbot.findByIdAndUpdate(chatbot._id, chatbot, { new: true });

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tiledesk/tiledesk-server",
   "description": "The Tiledesk server module",
-  "version": "2.29.0",
+  "version": "3.0.0",
   "scripts": {
     "start": "node ./bin/www",
     "pretest": "mongodb-runner start",

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)) };

package/pubmodules/aiGenerations/models/faqKbRevision.js

@@ -0,0 +1,51 @@
+/**
+ * Revisione di un agente (chatbot): la storia delle versioni della bozza.
+ *
+ * Collection `faq_kb_revisions`, fuori dal percorso dei messaggi. Ogni record porta,
+ * tranne che per le `release`, uno snapshot compresso dell'agente (blocchi e impostazioni,
+ * senza `attributes.globals`) e l'impronta dei blocchi. Le revisioni `ai_*` portano anche
+ * il prompt, il riassunto dell'intervista e il Blueprint della generazione.
+ */
+const mongoose = require('mongoose');
+const Schema = mongoose.Schema;
+
+const KINDS = ['ai_create', 'ai_edit', 'checkpoint', 'auto', 'restore', 'release'];
+const REASONS = ['before_ai_edit', 'before_restore', 'manual_changes', 'in_place', 'as_copy'];
+
+const SnapshotSchema = new Schema({
+  encoding: { type: String, default: 'gzip+json' },
+  data: { type: Buffer },
+  bytes: { type: Number },
+  intents: { type: Number }
+}, { _id: false });
+
+const FaqKbRevisionSchema = new Schema({
+  revision_id: { type: String, required: true },
+  id_project: { type: String, required: true, index: true },
+  id_faq_kb: { type: String, required: true, index: true },
+  seq: { type: Number, required: true, min: 1 },
+  kind: { type: String, enum: KINDS, required: true, index: true },
+  reason: { type: String, enum: REASONS.concat([null]), default: null },
+  note: { type: String, maxlength: 500 },
+  parent_id: { type: String, default: null },
+  ai: { type: Object },
+  snapshot: { type: SnapshotSchema },
+  contentHash: { type: String, default: null },
+  release_id: { type: String, default: null },
+  publishedAt: { type: Date },
+  createdBy: { type: String, required: true }
+}, {
+  timestamps: true,
+  collection: 'faq_kb_revisions'
+});
+
+FaqKbRevisionSchema.index({ id_project: 1, id_faq_kb: 1, seq: 1 }, { unique: true });
+FaqKbRevisionSchema.index({ id_project: 1, revision_id: 1 }, { unique: true });
+FaqKbRevisionSchema.index({ id_project: 1, id_faq_kb: 1, createdAt: -1 });
+
+const FaqKbRevision = mongoose.model('faq_kb_revision', FaqKbRevisionSchema);
+
+FaqKbRevision.KINDS = KINDS;
+FaqKbRevision.REASONS = REASONS;
+
+module.exports = FaqKbRevision;