@tiledesk/tiledesk-server 2.29.0 → 3.0.0

package/pubmodules/aiGenerations/services/snapshot.js

@@ -0,0 +1,109 @@
+/**
+ * Snapshot e impronta di un agente. Funzioni pure: nessun accesso al database.
+ *
+ * - Lo snapshot ha la forma dell'export (`GET /faq_kb/exportjson/:id`), senza `attributes.globals`.
+ * - L'impronta (`contentHash`) è lo sha256 dei blocchi normalizzati: ordinati per `intent_id`,
+ *   senza posizione e colore, con le chiavi in ordine. Due agenti con la stessa impronta hanno
+ *   gli stessi blocchi, a prescindere da come sono disposti sul canvas.
+ */
+const crypto = require('crypto');
+const zlib = require('zlib');
+
+const ENCODING = 'gzip+json';
+
+/** Campi del blocco che non entrano nell'export (come in exportjson). */
+const INTENT_OMIT = ['_id', 'id', 'id_project', 'topic', 'status', 'chatbot_id', 'createdBy', 'createdAt', 'updatedAt', '__v', 'id_faq_kb', 'faq_kb'];
+
+/** Campi dell'agente che entrano nello snapshot. */
+const KB_FIELDS = ['name', 'description', 'language', 'webhook_enabled', 'webhook_url', 'type', 'subtype'];
+
+function omit(obj, keys) {
+  const out = {};
+  Object.keys(obj || {}).forEach(key => {
+    if (keys.indexOf(key) === -1) out[key] = obj[key];
+  });
+  return out;
+}
+
+function clone(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+/** Un blocco come nell'export. */
+function exportIntent(faq) {
+  return clone(omit(faq, INTENT_OMIT));
+}
+
+/** Gli attributes dell'agente senza i globals, che possono contenere segreti. */
+function attributesWithoutGlobals(attributes) {
+  return omit(attributes || {}, ['globals']);
+}
+
+/** Lo snapshot di un agente, dai documenti `faq_kb` e `faq` (lean o toObject). */
+function buildSnapshot(kb, faqs) {
+  const snapshot = {};
+  KB_FIELDS.forEach(field => {
+    if (kb[field] !== undefined) snapshot[field] = clone(kb[field]);
+  });
+  snapshot.attributes = clone(attributesWithoutGlobals(kb.attributes));
+  snapshot.intents = (faqs || []).map(exportIntent);
+  return snapshot;
+}
+
+/** JSON con le chiavi in ordine, a ogni livello: la stessa struttura dà sempre la stessa stringa. */
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return '[' + value.map(stableStringify).join(',') + ']';
+  const keys = Object.keys(value).filter(key => value[key] !== undefined).sort();
+  return '{' + keys.map(key => JSON.stringify(key) + ':' + stableStringify(value[key])).join(',') + '}';
+}
+
+/** Il blocco senza ciò che riguarda solo il disegno sul canvas. */
+function normalizeIntent(intent) {
+  const normalized = exportIntent(intent);
+  if (normalized.attributes && typeof normalized.attributes === 'object') {
+    normalized.attributes = omit(normalized.attributes, ['position', 'color']);
+  }
+  return normalized;
+}
+
+/** L'impronta dei blocchi. */
+function hashIntents(intents) {
+  const normalized = (intents || [])
+    .map(normalizeIntent)
+    .sort((a, b) => String(a.intent_id).localeCompare(String(b.intent_id)));
+  return 'sha256:' + crypto.createHash('sha256').update(stableStringify(normalized)).digest('hex');
+}
+
+/** Lo snapshot compresso, pronto per il record. */
+function compress(snapshot) {
+  const json = JSON.stringify(snapshot);
+  return {
+    encoding: ENCODING,
+    data: zlib.gzipSync(Buffer.from(json, 'utf8')),
+    bytes: Buffer.byteLength(json, 'utf8'),
+    intents: Array.isArray(snapshot.intents) ? snapshot.intents.length : 0
+  };
+}
+
+/** Lo snapshot decompresso da un record; null se il record non ne ha uno. */
+function decompress(stored) {
+  if (!stored || !stored.data) return null;
+  const buffer = Buffer.isBuffer(stored.data) ? stored.data : Buffer.from(stored.data.buffer || stored.data);
+  if (stored.encoding && stored.encoding !== ENCODING) {
+    throw new Error('Unsupported snapshot encoding ' + stored.encoding);
+  }
+  return JSON.parse(zlib.gunzipSync(buffer).toString('utf8'));
+}
+
+module.exports = {
+  ENCODING,
+  buildSnapshot,
+  exportIntent,
+  attributesWithoutGlobals,
+  normalizeIntent,
+  hashIntents,
+  stableStringify,
+  compress,
+  decompress
+};

package/pubmodules/aiGenerations/test/aiGenerationsRoute.js

@@ -0,0 +1,503 @@
+/**
+ * Test del modulo aiGenerations.
+ *
+ * Il modulo si accende con AI_GENERATIONS_ENABLED=true. Questo file la imposta prima di caricare
+ * l'app, quindi lanciato da solo (`npx mocha pubmodules/aiGenerations/test/*.js --exit`) prova
+ * tutte le rotte. Nella suite completa l'app è già caricata da altri file: se la variabile non era
+ * nell'ambiente, il modulo non è montato e qui si verifica solo che le rotte rispondano 404.
+ */
+process.env.NODE_ENV = 'test';
+if (process.env.AI_GENERATIONS_ENABLED === undefined) process.env.AI_GENERATIONS_ENABLED = 'true';
+if (process.env.AI_GENERATIONS_CLEANUP_ENABLED === undefined) process.env.AI_GENERATIONS_CLEANUP_ENABLED = 'true';
+if (process.env.AI_GENERATIONS_AUTOSNAPSHOT_ENABLED === undefined) process.env.AI_GENERATIONS_AUTOSNAPSHOT_ENABLED = 'true';
+if (process.env.AI_GENERATIONS_AUTOSNAPSHOT_DEBOUNCE_MS === undefined) process.env.AI_GENERATIONS_AUTOSNAPSHOT_DEBOUNCE_MS = '60000';
+if (process.env.AI_GENERATIONS_AUTOSNAPSHOT_RECENT_MS === undefined) process.env.AI_GENERATIONS_AUTOSNAPSHOT_RECENT_MS = '200';
+
+const chai = require('chai');
+const chaiHttp = require('chai-http');
+const expect = chai.expect;
+chai.use(chaiHttp);
+
+const server = require('../../../app');
+const pubModulesManager = require('../../pubModulesManager');
+const userService = require('../../../services/userService');
+const projectService = require('../../../services/projectService');
+const Faq = require('../../../models/faq');
+const Faq_kb = require('../../../models/faq_kb');
+const FaqKbRevision = require('../models/faqKbRevision');
+const snapshotUtil = require('../services/snapshot');
+const botEvent = require('../../../event/botEvent');
+const faqBotEvent = require('../../../event/faqBotEvent');
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+const listeners = require('../listeners');
+
+const BASE = '/modules/ai-generations';
+const mounted = !!pubModulesManager.aiGenerationsRoute;
+// Lanciato da solo con la variabile accesa, il modulo DEVE essere montato: altrimenti e' fallito al caricamento.
+if (process.env.AI_GENERATIONS_ENABLED === 'true' && !mounted && !process.env.AI_GENERATIONS_TEST_EXPECT_OFF) {
+  throw new Error('aiGenerations module is enabled but not mounted: check the server log for "error initializing aiGenerations module"');
+}
+
+function sampleAgent(name) {
+  const intent = (id, displayName, actions, next) => ({
+    intent_id: id,
+    intent_display_name: displayName,
+    enabled: true,
+    webhook_enabled: false,
+    language: 'it',
+    actions: actions,
+    attributes: { position: { x: 100, y: 100 }, color: 'blue', nextBlockAction: { _tdActionType: 'intent', intentName: next || '' }, connectors: {} }
+  });
+  return {
+    name: name || 'Prenotazione tavolo',
+    description: 'test',
+    language: 'it',
+    attributes: { variables: { people: 'people' } },
+    intents: [
+      Object.assign(intent('i-start', 'start', [{ _tdActionType: 'intent', intentName: '#i-welcome' }]), { question: '\\start' }),
+      intent('i-welcome', 'Benvenuto', [{ _tdActionType: 'reply', text: 'Ciao! Vuoi prenotare un tavolo?' }], '#i-people'),
+      intent('i-people', 'Quante persone', [{ _tdActionType: 'capture_user_reply', assignReplyTo: 'people', goToIntent: '#i-confirm' }]),
+      intent('i-confirm', 'Conferma', [{ _tdActionType: 'reply', text: 'Tavolo per {{people}} prenotato.' }]),
+      intent('i-fallback', 'Fallback', [{ _tdActionType: 'reply', text: 'Non ho capito.' }]),
+      Object.assign(intent('i-default', 'defaultFallback', []), { question: 'defaultFallback' })
+    ]
+  };
+}
+
+const sampleAi = {
+  request: { initialPrompt: 'un bot che prenota tavoli', finalPrompt: 'PROMPT FINALE', finalPromptEdited: false, interview: { questions: 3 } },
+  result: { blueprint: { start: 'welcome', blocks: [] }, blueprintVersion: 'blueprint-2', idMap: { welcome: 'i-welcome' }, model: 'test-model' }
+};
+
+async function newProject(name) {
+  const email = 'test-aigen-' + Date.now() + '-' + Math.round(Math.random() * 1e6) + '@email.com';
+  const pwd = 'pwd';
+  const user = await userService.signup(email, pwd, 'Test', 'User');
+  const project = await projectService.create(name || 'test-aigen', user._id);
+  return { email: email, pwd: pwd, user: user, project: project, id: String(project._id) };
+}
+
+function api(ctx) {
+  return {
+    post: (path, body) => chai.request(server).post('/' + ctx.id + BASE + path).auth(ctx.email, ctx.pwd).send(body || {}),
+    get: (path) => chai.request(server).get('/' + ctx.id + BASE + path).auth(ctx.email, ctx.pwd),
+    del: (path) => chai.request(server).delete('/' + ctx.id + BASE + path).auth(ctx.email, ctx.pwd)
+  };
+}
+
+async function createAgent(ctx, name) {
+  const res = await api(ctx).post('/agents', { agent: sampleAgent(name), ai: sampleAi });
+  expect(res).to.have.status(201);
+  return res.body;
+}
+
+describe('aiGenerations module', function () {
+  this.timeout(30000);
+
+  if (!mounted) {
+    it('is not mounted without AI_GENERATIONS_ENABLED: routes answer 404', async () => {
+      const ctx = await newProject();
+      const res = await api(ctx).get('/');
+      expect(res).to.have.status(404);
+    });
+    return;
+  }
+
+  it('reports its status', async () => {
+    const ctx = await newProject();
+    const res = await api(ctx).get('/');
+    expect(res).to.have.status(200);
+    expect(res.body.enabled).to.equal(true);
+    expect(res.body.transactions).to.be.a('boolean');
+  });
+
+  it('refuses a non-admin', async () => {
+    const ctx = await newProject();
+    const other = await newProject();
+    const res = await chai.request(server).get('/' + ctx.id + BASE + '/').auth(other.email, other.pwd);
+    expect(res.status).to.be.oneOf([401, 403]);
+  });
+
+  describe('POST /agents', () => {
+
+    it('creates the chatbot, its blocks and revision 1 atomically', async () => {
+      const ctx = await newProject();
+      const body = await createAgent(ctx);
+      expect(body.bot_id).to.be.a('string');
+      expect(body.revision.seq).to.equal(1);
+      expect(body.revision.kind).to.equal('ai_create');
+      expect(body.revision.contentHash).to.match(/^sha256:/);
+      expect(body.revision.snapshot.intents).to.equal(6);
+      expect(body.revision.snapshot.data).to.equal(undefined);
+      expect(body.revision.ai.request.finalPrompt).to.equal(undefined);
+      expect(body.revision.ai.result.blueprint).to.equal(undefined);
+
+      const faqs = await Faq.find({ id_faq_kb: body.bot_id }).lean().exec();
+      expect(faqs.length).to.equal(6);
+      expect(faqs.map(f => f.intent_id).sort()).to.deep.equal(['i-confirm', 'i-default', 'i-fallback', 'i-people', 'i-start', 'i-welcome']);
+      expect(faqs.every(f => f.id_project === ctx.id)).to.equal(true);
+
+      const kb = await Faq_kb.findById(body.bot_id).lean().exec();
+      expect(kb.name).to.equal('Prenotazione tavolo');
+      expect(kb.attributes.aiGeneration).to.equal(undefined);
+
+      const stored = await FaqKbRevision.findOne({ revision_id: body.revision.revision_id }).exec();
+      expect(stored.ai.request.finalPrompt).to.equal('PROMPT FINALE');
+      const snapshot = snapshotUtil.decompress(stored.snapshot);
+      expect(snapshot.intents.length).to.equal(6);
+      expect(snapshot.name).to.equal('Prenotazione tavolo');
+      expect(snapshot.attributes.globals).to.equal(undefined);
+    });
+
+    it('validates the body', async () => {
+      const ctx = await newProject();
+      let res = await api(ctx).post('/agents', { ai: sampleAi });
+      expect(res).to.have.status(400);
+      const agent = sampleAgent();
+      agent.intents[1].intent_display_name = 'start';
+      res = await api(ctx).post('/agents', { agent: agent });
+      expect(res).to.have.status(400);
+      expect(res.body.details.intent_display_name).to.equal('start');
+    });
+
+    it('leaves nothing behind when a block cannot be saved', async () => {
+      const ctx = await newProject();
+      const agent = sampleAgent('Agente rifiutato');
+      // Un blocco che il model rifiuta: `enabled` non convertibile in booleano.
+      agent.intents[2].enabled = 'not-a-boolean';
+      const res = await api(ctx).post('/agents', { agent: agent });
+      expect(res).to.have.status(422);
+      expect(res.body.details.blocks[0].intent_display_name).to.equal('Quante persone');
+      // Il progetto crea da solo un bot di default, quindi si conta solo l'agente rifiutato.
+      expect(await Faq_kb.countDocuments({ id_project: ctx.id, name: 'Agente rifiutato' }).exec()).to.equal(0);
+      expect(await Faq.countDocuments({ id_project: ctx.id, intent_id: 'i-welcome' }).exec()).to.equal(0);
+      const revisions = await FaqKbRevision.countDocuments({ id_project: ctx.id }).exec();
+      expect(revisions).to.equal(0);
+    });
+  });
+
+  describe('hash, checkpoint, list', () => {
+
+    it('tracks manual changes with the hash', async () => {
+      const ctx = await newProject();
+      const created = await createAgent(ctx);
+      let res = await api(ctx).get('/agents/' + created.bot_id + '/hash');
+      expect(res).to.have.status(200);
+      expect(res.body.contentHash).to.equal(created.revision.contentHash);
+      expect(res.body.modified).to.equal(false);
+
+      // Spostare un blocco non cambia l'impronta
+      await Faq.updateOne({ id_faq_kb: created.bot_id, intent_id: 'i-welcome' }, { $set: { 'attributes.position': { x: 999, y: 999 } } }).exec();
+      res = await api(ctx).get('/agents/' + created.bot_id + '/hash');
+      expect(res.body.modified).to.equal(false);
+
+      // Cambiare un testo sì
+      await Faq.updateOne({ id_faq_kb: created.bot_id, intent_id: 'i-welcome' }, { $set: { actions: [{ _tdActionType: 'reply', text: 'Testo cambiato' }] } }).exec();
+      res = await api(ctx).get('/agents/' + created.bot_id + '/hash');
+      expect(res.body.modified).to.equal(true);
+      expect(res.body.contentHash).to.not.equal(created.revision.contentHash);
+    });
+
+    it('saves a checkpoint and lists the history without heavy fields', async () => {
+      const ctx = await newProject();
+      const created = await createAgent(ctx);
+      let res = await api(ctx).post('/agents/' + created.bot_id + '/revisions', { note: 'Prima della demo' });
+      expect(res).to.have.status(201);
+      expect(res.body.revision.seq).to.equal(2);
+      expect(res.body.revision.kind).to.equal('checkpoint');
+      expect(res.body.revision.note).to.equal('Prima della demo');
+      expect(res.body.revision.parent_id).to.equal(created.revision.revision_id);
+
+      res = await api(ctx).get('/agents/' + created.bot_id + '/revisions?limit=10');
+      expect(res).to.have.status(200);
+      expect(res.body.total).to.equal(2);
+      expect(res.body.items[0].seq).to.equal(2);
+      expect(res.body.items[1].snapshot.data).to.equal(undefined);
+      expect(res.body.items[1].ai.request.finalPrompt).to.equal(undefined);
+      expect(res.body.items[1].ai.result.blueprint).to.equal(undefined);
+      expect(res.body.items[1].ai.result.idMap.welcome).to.equal('i-welcome');
+
+      res = await api(ctx).get('/revisions/' + created.revision.revision_id + '?snapshot=true');
+      expect(res).to.have.status(200);
+      expect(res.body.ai.request.finalPrompt).to.equal('PROMPT FINALE');
+      expect(res.body.ai.result.blueprint.start).to.equal('welcome');
+      expect(res.body.snapshotData.intents.length).to.equal(6);
+      expect(res.body.snapshot.data).to.equal(undefined);
+    });
+
+    it('keeps projects apart', async () => {
+      const ctx = await newProject();
+      const other = await newProject();
+      const created = await createAgent(ctx);
+      let res = await api(other).get('/agents/' + created.bot_id + '/revisions');
+      expect(res).to.have.status(404);
+      res = await api(other).get('/revisions/' + created.revision.revision_id);
+      expect(res).to.have.status(404);
+      res = await api(other).post('/agents/' + created.bot_id + '/restore', { revision_id: created.revision.revision_id });
+      expect(res).to.have.status(404);
+    });
+  });
+
+  describe('POST /agents/:id/restore', () => {
+
+    it('restores in place, keeps ids, backs up manual changes first, and is reversible', async () => {
+      const ctx = await newProject();
+      const created = await createAgent(ctx);
+      const r1 = created.revision;
+
+      // Modifiche a mano: testo cambiato e blocco nuovo
+      await Faq.updateOne({ id_faq_kb: created.bot_id, intent_id: 'i-welcome' }, { $set: { actions: [{ _tdActionType: 'reply', text: 'Testo delle 11:30' }] } }).exec();
+      await Faq.create({ id_faq_kb: created.bot_id, id_project: ctx.id, createdBy: 'test', intent_id: 'i-orari', intent_display_name: 'Orari', actions: [] });
+      let hash = await api(ctx).get('/agents/' + created.bot_id + '/hash');
+      expect(hash.body.modified).to.equal(true);
+
+      // Impronta sbagliata: 409, niente cambia
+      let res = await api(ctx).post('/agents/' + created.bot_id + '/restore', { revision_id: r1.revision_id, expectedHash: 'sha256:wrong' });
+      expect(res).to.have.status(409);
+      expect(await Faq.countDocuments({ id_faq_kb: created.bot_id }).exec()).to.equal(7);
+
+      // Ripristino della revisione 1
+      res = await api(ctx).post('/agents/' + created.bot_id + '/restore', { revision_id: r1.revision_id, expectedHash: hash.body.contentHash });
+      expect(res).to.have.status(200);
+      expect(res.body.backup.kind).to.equal('auto');
+      expect(res.body.backup.reason).to.equal('before_restore');
+      expect(res.body.backup.seq).to.equal(2);
+      expect(res.body.backup.snapshot.intents).to.equal(7);
+      expect(res.body.revision.kind).to.equal('restore');
+      expect(res.body.revision.reason).to.equal('in_place');
+      expect(res.body.revision.seq).to.equal(3);
+      expect(res.body.revision.parent_id).to.equal(r1.revision_id);
+      expect(res.body.revision.contentHash).to.equal(r1.contentHash);
+
+      const faqs = await Faq.find({ id_faq_kb: created.bot_id }).lean().exec();
+      expect(faqs.length).to.equal(6);
+      const welcome = faqs.find(f => f.intent_id === 'i-welcome');
+      expect(welcome.actions[0].text).to.equal('Ciao! Vuoi prenotare un tavolo?');
+      expect(faqs.find(f => f.intent_id === 'i-orari')).to.equal(undefined);
+      expect(faqs.every(f => f.id_faq_kb === created.bot_id)).to.equal(true);
+      const kb = await Faq_kb.findById(created.bot_id).lean().exec();
+      expect(kb.modified).to.equal(true);
+
+      // Nessun blocco di staging rimasto
+      expect(await Faq.countDocuments({ id_faq_kb: new RegExp('^' + created.bot_id + '~') }).exec()).to.equal(0);
+
+      // Il ripristino è reversibile: si torna alla revisione automatica
+      res = await api(ctx).post('/agents/' + created.bot_id + '/restore', { revision_id: res.body.backup.revision_id });
+      expect(res).to.have.status(200);
+      expect(res.body.backup).to.equal(null); // lo stato corrente coincideva con la revisione 3
+      expect(res.body.revision.seq).to.equal(4);
+      const again = await Faq.find({ id_faq_kb: created.bot_id }).lean().exec();
+      expect(again.length).to.equal(7);
+      expect(again.find(f => f.intent_id === 'i-welcome').actions[0].text).to.equal('Testo delle 11:30');
+    });
+
+    it('keeps the globals of the draft', async () => {
+      const ctx = await newProject();
+      const created = await createAgent(ctx);
+      await Faq_kb.updateOne({ _id: created.bot_id }, { $set: { 'attributes.globals': { API_KEY: 'secret' }, name: 'Rinominato' } }).exec();
+      const res = await api(ctx).post('/agents/' + created.bot_id + '/restore', { revision_id: created.revision.revision_id });
+      expect(res).to.have.status(200);
+      const kb = await Faq_kb.findById(created.bot_id).lean().exec();
+      expect(kb.name).to.equal('Prenotazione tavolo');
+      expect(kb.attributes.globals.API_KEY).to.equal('secret');
+      expect(kb.attributes.variables.people).to.equal('people');
+      const stored = await FaqKbRevision.findOne({ revision_id: res.body.revision.revision_id }).exec();
+      expect(snapshotUtil.decompress(stored.snapshot).attributes.globals).to.equal(undefined);
+    });
+
+    it('restores as a copy into a new chatbot', async () => {
+      const ctx = await newProject();
+      const created = await createAgent(ctx);
+      const res = await api(ctx).post('/agents/' + created.bot_id + '/restore', { revision_id: created.revision.revision_id, as_copy: true });
+      expect(res).to.have.status(201);
+      expect(res.body.bot_id).to.not.equal(created.bot_id);
+      expect(res.body.revision.seq).to.equal(1);
+      expect(res.body.revision.kind).to.equal('restore');
+      expect(res.body.revision.reason).to.equal('as_copy');
+      expect(res.body.revision.parent_id).to.equal(created.revision.revision_id);
+      const copyFaqs = await Faq.find({ id_faq_kb: res.body.bot_id }).lean().exec();
+      expect(copyFaqs.length).to.equal(6);
+      expect(await Faq.countDocuments({ id_faq_kb: created.bot_id }).exec()).to.equal(6);
+      const copy = await Faq_kb.findById(res.body.bot_id).lean().exec();
+      expect(copy.name).to.equal('Prenotazione tavolo (copia)');
+    });
+
+    it('links a release and restores from it', async () => {
+      const ctx = await newProject();
+      const created = await createAgent(ctx);
+      // Una release come la crea la pubblicazione: copia con root_id
+      const release = await Faq_kb.create({ name: 'Prenotazione tavolo', id_project: ctx.id, createdBy: 'test', type: 'tilebot', trashed: true, root_id: created.bot_id, publishedAt: new Date(), release_note: 'v1' });
+      const faqs = await Faq.find({ id_faq_kb: created.bot_id }).lean().exec();
+      await Faq.insertMany(faqs.map(f => Object.assign({}, f, { _id: undefined, id_faq_kb: String(release._id) })));
+
+      let res = await api(ctx).post('/agents/' + created.bot_id + '/revisions/release', { release_id: String(release._id) });
+      expect(res).to.have.status(201);
+      expect(res.body.revision.kind).to.equal('release');
+      expect(res.body.revision.release_id).to.equal(String(release._id));
+      expect(res.body.revision.note).to.equal('v1');
+      res = await api(ctx).post('/agents/' + created.bot_id + '/revisions/release', { release_id: String(release._id) });
+      expect(res).to.have.status(200);
+      expect(res.body.already_linked).to.equal(true);
+
+      const stranger = await Faq_kb.create({ name: 'Altro', id_project: ctx.id, createdBy: 'test', type: 'tilebot' });
+      res = await api(ctx).post('/agents/' + created.bot_id + '/revisions/release', { release_id: String(stranger._id) });
+      expect(res).to.have.status(404);
+
+      // La bozza cambia, poi si ripristina dalla release
+      await Faq.deleteOne({ id_faq_kb: created.bot_id, intent_id: 'i-fallback' }).exec();
+      res = await api(ctx).post('/agents/' + created.bot_id + '/restore', { release_id: String(release._id) });
+      expect(res).to.have.status(200);
+      expect(res.body.backup.kind).to.equal('auto');
+      expect(await Faq.countDocuments({ id_faq_kb: created.bot_id }).exec()).to.equal(6);
+    });
+
+    it('refuses a trashed chatbot and a revision without snapshot', async () => {
+      const ctx = await newProject();
+      const created = await createAgent(ctx);
+      const release = await Faq_kb.create({ name: 'R', id_project: ctx.id, createdBy: 'test', type: 'tilebot', trashed: true, root_id: created.bot_id, publishedAt: new Date() });
+      let res = await api(ctx).post('/agents/' + created.bot_id + '/revisions/release', { release_id: String(release._id) });
+      expect(res).to.have.status(201);
+      res = await api(ctx).post('/agents/' + created.bot_id + '/restore', { revision_id: res.body.revision.revision_id });
+      expect(res).to.have.status(409);
+
+      await Faq_kb.updateOne({ _id: created.bot_id }, { $set: { trashed: true } }).exec();
+      res = await api(ctx).post('/agents/' + created.bot_id + '/restore', { revision_id: created.revision.revision_id });
+      expect(res).to.have.status(409);
+    });
+  });
+
+  describe('POST /agents/:id/restore dry_run', () => {
+    it('lists the external references that no longer exist, without writing', async () => {
+      const ctx = await newProject();
+      const agent = sampleAgent();
+      agent.intents[3].actions = [{ _tdActionType: 'department', depName: 'Ghost department', triggerBot: false }];
+      agent.intents[4].actions = [{ _tdActionType: 'replacebotv3', botId: '5f0000000000000000000000', useSlug: false }];
+      const res0 = await api(ctx).post('/agents', { agent: agent, ai: sampleAi });
+      expect(res0).to.have.status(201);
+      const created = res0.body;
+      await Faq.updateOne({ id_faq_kb: created.bot_id, intent_id: 'i-welcome' }, { $set: { actions: [{ _tdActionType: 'reply', text: 'x' }] } }).exec();
+      const res = await api(ctx).post('/agents/' + created.bot_id + '/restore', { revision_id: created.revision.revision_id, dry_run: true, expectedHash: created.revision.contentHash });
+      expect(res).to.have.status(200);
+      expect(res.body.dry_run).to.equal(true);
+      expect(res.body.changed).to.equal(true);
+      expect(res.body.intents).to.equal(6);
+      const kinds = res.body.missing.map(m => m.kind + ':' + m.value).sort();
+      expect(kinds).to.deep.equal(['chatbot:5f0000000000000000000000', 'department:Ghost department']);
+      expect(await FaqKbRevision.countDocuments({ id_faq_kb: created.bot_id }).exec()).to.equal(1);
+      const faqs = await Faq.find({ id_faq_kb: created.bot_id, intent_id: 'i-welcome' }).lean().exec();
+      expect(faqs[0].actions[0].text).to.equal('x');
+    });
+  });
+
+  describe('listeners (fase F)', () => {
+    it('cleanup: deleting the chatbot deletes its history', async () => {
+      const ctx = await newProject();
+      const created = await createAgent(ctx);
+      const kb = await Faq_kb.findById(created.bot_id).exec();
+      botEvent.emit('faqbot.delete', kb);
+      await sleep(300);
+      expect(await FaqKbRevision.countDocuments({ id_faq_kb: created.bot_id }).exec()).to.equal(0);
+    });
+
+    it('autosnapshot: manual changes produce one auto revision, only if something changed and not right after a module revision', async () => {
+      const ctx = await newProject();
+      const created = await createAgent(ctx);
+      const faq = await Faq.findOne({ id_faq_kb: created.bot_id, intent_id: 'i-welcome' }).exec();
+      // Gli eventi (anche quelli della creazione) lasciano un solo timer in attesa per agente (debounce)
+      faqBotEvent.emit('faq.update', faq);
+      const count = listeners.pendingCount();
+      faqBotEvent.emit('faq.update', faq);
+      expect(listeners.isPending(created.bot_id)).to.equal(true);
+      expect(listeners.pendingCount()).to.equal(count);
+      // Nessun cambiamento reale: nessuna revisione
+      await sleep(250);
+      await listeners.snapshot(created.bot_id);
+      expect(await FaqKbRevision.countDocuments({ id_faq_kb: created.bot_id }).exec()).to.equal(1);
+      // Un cambiamento vero: una revisione automatica
+      await Faq.updateOne({ _id: faq._id }, { $set: { actions: [{ _tdActionType: 'reply', text: 'cambiato a mano' }] } }).exec();
+      await listeners.snapshot(created.bot_id);
+      const revisions = await FaqKbRevision.find({ id_faq_kb: created.bot_id }).sort({ seq: 1 }).lean().exec();
+      expect(revisions.length).to.equal(2);
+      expect(revisions[1].kind).to.equal('auto');
+      expect(revisions[1].reason).to.equal('manual_changes');
+      expect(revisions[1].createdBy).to.equal('system');
+      expect(revisions[1].snapshot.intents).to.equal(6);
+      // Subito dopo una revisione del modulo (qui: quella appena scritta) un altro cambiamento non produce snapshot
+      await Faq.updateOne({ _id: faq._id }, { $set: { actions: [{ _tdActionType: 'reply', text: 'cambiato di nuovo' }] } }).exec();
+      await listeners.snapshot(created.bot_id);
+      expect(await FaqKbRevision.countDocuments({ id_faq_kb: created.bot_id }).exec()).to.equal(2);
+    });
+  });
+
+  describe('POST /agents/:id/edit', () => {
+
+    it('applies operations and records an ai_edit revision with changes', async () => {
+      const ctx = await newProject();
+      const created = await createAgent(ctx);
+      const operations = [
+        { type: 'post', intent: { intent_id: 'i-orari', intent_display_name: 'Orari', actions: [{ _tdActionType: 'reply', text: '12-15, 19-23' }], attributes: {} } },
+        { type: 'put', intent: { intent_id: 'i-confirm', intent_display_name: 'Conferma', actions: [{ _tdActionType: 'reply', text: 'Prenotato!' }] } },
+        { type: 'delete', intent: { intent_id: 'i-fallback' } }
+      ];
+      const res = await api(ctx).post('/agents/' + created.bot_id + '/edit', {
+        operations: operations,
+        ai: { request: { finalPrompt: 'aggiungi gli orari' }, result: { model: 'test-model' } },
+        expectedHash: created.revision.contentHash
+      });
+      expect(res).to.have.status(200);
+      expect(res.body.backup).to.equal(null);
+      expect(res.body.revision.kind).to.equal('ai_edit');
+      expect(res.body.revision.seq).to.equal(2);
+      expect(res.body.changes).to.deep.equal({ added: ['i-orari'], updated: ['i-confirm'], removed: ['i-fallback'] });
+      expect(res.body.revision.ai.result.changes.added).to.deep.equal(['i-orari']);
+
+      const faqs = await Faq.find({ id_faq_kb: created.bot_id }).lean().exec();
+      expect(faqs.length).to.equal(6);
+      expect(faqs.find(f => f.intent_id === 'i-confirm').actions[0].text).to.equal('Prenotato!');
+      expect(faqs.find(f => f.intent_id === 'i-fallback')).to.equal(undefined);
+      expect(faqs.find(f => f.intent_id === 'i-orari').createdBy).to.equal(String(ctx.user._id));
+    });
+
+    it('rejects a stale expectedHash and an unknown block', async () => {
+      const ctx = await newProject();
+      const created = await createAgent(ctx);
+      let res = await api(ctx).post('/agents/' + created.bot_id + '/edit', { operations: [{ type: 'delete', intent: { intent_id: 'i-fallback' } }], expectedHash: 'sha256:stale' });
+      expect(res).to.have.status(409);
+      res = await api(ctx).post('/agents/' + created.bot_id + '/edit', { operations: [{ type: 'delete', intent: { intent_id: 'nope' } }] });
+      expect(res).to.have.status(404);
+      expect(await Faq.countDocuments({ id_faq_kb: created.bot_id }).exec()).to.equal(6);
+    });
+  });
+
+  describe('DELETE /agents/:id/revisions', () => {
+    it('deletes the history of the chatbot only', async () => {
+      const ctx = await newProject();
+      const a = await createAgent(ctx, 'A');
+      const b = await createAgent(ctx, 'B');
+      const res = await api(ctx).del('/agents/' + a.bot_id + '/revisions');
+      expect(res).to.have.status(200);
+      expect(res.body.deleted).to.equal(1);
+      expect(await FaqKbRevision.countDocuments({ id_faq_kb: a.bot_id }).exec()).to.equal(0);
+      expect(await FaqKbRevision.countDocuments({ id_faq_kb: b.bot_id }).exec()).to.equal(1);
+      expect(await Faq.countDocuments({ id_faq_kb: a.bot_id }).exec()).to.equal(6);
+    });
+  });
+
+  describe('snapshot helpers', () => {
+    it('hash ignores position and color and key order', () => {
+      const a = [{ intent_id: '1', intent_display_name: 'x', actions: [{ b: 1, a: 2 }], attributes: { position: { x: 1 }, color: 'red', other: 1 } }];
+      const b = [{ attributes: { other: 1, color: 'blue', position: { x: 9 } }, actions: [{ a: 2, b: 1 }], intent_display_name: 'x', intent_id: '1' }];
+      expect(snapshotUtil.hashIntents(a)).to.equal(snapshotUtil.hashIntents(b));
+      const c = [{ intent_id: '1', intent_display_name: 'x', actions: [{ b: 1, a: 3 }], attributes: { other: 1 } }];
+      expect(snapshotUtil.hashIntents(a)).to.not.equal(snapshotUtil.hashIntents(c));
+    });
+
+    it('compress and decompress round-trip', () => {
+      const snapshot = { name: 'n', attributes: {}, intents: [{ intent_id: '1', intent_display_name: 'x' }] };
+      const stored = snapshotUtil.compress(snapshot);
+      expect(stored.encoding).to.equal('gzip+json');
+      expect(stored.intents).to.equal(1);
+      expect(snapshotUtil.decompress(stored)).to.deep.equal(snapshot);
+    });
+  });
+});

package/pubmodules/pubModulesManager.js

@@ -58,6 +58,8 @@ class PubModulesManager {
 
         this.cannedResponseRoute = undefined;
 
+        this.aiGenerationsRoute = undefined;
+
         this.trigger = undefined;
         this.triggerRoute = undefined;
 
@@ -168,6 +170,11 @@ class PubModulesManager {
             winston.info("ModulesManager canned controller loaded");       
         }
 
+        if (this.aiGenerationsRoute) {
+            app.use('/:projectid/modules/ai-generations', [passport.authenticate(['basic', 'jwt'], { session: false }), validtoken, roleChecker.hasRole('admin')], this.aiGenerationsRoute);
+            winston.info("ModulesManager aiGenerations controller loaded");
+        }
+
         if (this.triggerRoute) {
             app.use('/:projectid/modules/triggers', [passport.authenticate(['basic', 'jwt'], { session: false }), validtoken, roleChecker.hasRole('admin')], this.triggerRoute);
             winston.info("ModulesManager trigger controller loaded");       
@@ -498,6 +505,16 @@ class PubModulesManager {
 
 
 
+        // Storia e ripristino degli agenti: attivo SOLO con AI_GENERATIONS_ENABLED=true
+        if (process.env.AI_GENERATIONS_ENABLED === 'true') {
+            try {
+                this.aiGenerationsRoute = require('./aiGenerations').aiGenerationsRoute;
+                winston.info("ModulesManager aiGenerations initialized");
+            } catch(err) {
+                winston.error("ModulesManager error initializing aiGenerations module", err);
+            }
+        }
+
         try {
             this.cannedResponseRoute = require('./canned').cannedResponseRoute;
             winston.debug("this.cannedResponseRoute:"+ this.cannedResponseRoute);