@tiledesk/tiledesk-server 2.29.0 → 3.0.0

package/routes/faq.js

@@ -655,9 +655,16 @@ router.get('/', roleChecker.hasRoleOrTypes('agent', ['bot', 'subscription']), fu
   //   console.log("result: ", result);
   // })
 
-  return Faq.find(query)
-    .skip(skip).limit(limit)
-    .populate({ path: 'faq_kb' })
+  // Every block carries `faq_kb`, the whole bot read again from the database (virtual of the
+  // model). A caller that already has the bot, such as the Design Studio V3, asks for the blocks
+  // without it (`populate=false`): a list of blocks then weighs the blocks alone, not the bot
+  // repeated in every row. Without the parameter, or with any other value, nothing changes.
+  let faqQuery = Faq.find(query)
+    .skip(skip).limit(limit);
+  if (req.query.populate !== 'false') {
+    faqQuery = faqQuery.populate({ path: 'faq_kb' });
+  }
+  return faqQuery
     .lean()
     .exec(function (err, faqs) {
 

package/routes/faq_kb.js

@@ -23,6 +23,7 @@ const chatbotController = require('../controllers/chatbot.controller');
 const intentsController = require('../controllers/intents.controller');
 const AppError = require('../utils/AppError');
 const asyncHandler = require('../utils/asyncHandler');
+const v3FlowService = require('../services/v3FlowService');
 
 let chatbot_templates_api_url = process.env.CHATBOT_TEMPLATES_API_URL
 
@@ -457,12 +458,81 @@ router.put('/:faq_kbid/language/:language', roleChecker.hasRoleOrTypes('admin',
 
 })
 
+/**
+ * V3 agents: the connectors list, read and written as a whole.
+ * `GET` answers the list (or null for an agent that has none).
+ * `PUT` replaces it: the body is the list (`{ version: 1, items: [...] }`), validated in shape; an
+ * `If-Match` header (or an `if_match` query parameter) carrying the `updatedAt` the client last saw turns a save on top of a newer
+ * list into a 409 that returns the current one, so two editors cannot overwrite each other blindly.
+ * The agent is marked as modified (it has to be published again) and the engine's cache is cleared.
+ * Only a V3 agent has a list: for any other agent the PUT is refused and nothing changes.
+ */
+router.get('/:faq_kbid/connectors', roleChecker.hasRoleOrTypes('admin', ['bot', 'subscription']), asyncHandler(async (req, res) => {
+  const faq_kb = await Faq_kb.findOne({ _id: req.params.faq_kbid, id_project: req.projectid }).select('+connectors').exec();
+  if (!faq_kb) {
+    return res.status(404).send({ success: false, msg: "Chatbot not found with id " + req.params.faq_kbid + " for project " + req.projectid });
+  }
+  return res.json(faq_kb.connectors === undefined ? null : faq_kb.connectors);
+}));
+
+router.put('/:faq_kbid/connectors', roleChecker.hasRoleOrTypes('admin', ['bot', 'subscription']), asyncHandler(async (req, res) => {
+  const chatbot_id = req.params.faq_kbid;
+  const id_project = req.projectid;
+  const collection = req.body;
+
+  const errors = v3FlowService.validateConnectors(collection);
+  if (errors.length > 0) {
+    return res.status(400).send({ success: false, msg: "Invalid connectors list", errors: errors });
+  }
+
+  const faq_kb = await Faq_kb.findOne({ _id: chatbot_id, id_project: id_project }).select('+connectors').exec();
+  if (!faq_kb) {
+    return res.status(404).send({ success: false, msg: "Chatbot not found with id " + chatbot_id + " for project " + id_project });
+  }
+  if (!v3FlowService.isV3(faq_kb)) {
+    return res.status(400).send({ success: false, msg: "The connectors list belongs to V3 agents only (ds_version 'v3')" });
+  }
+
+  // The `updatedAt` the client last saw: `If-Match` header, or `if_match` query parameter for the
+  // clients that cannot send a custom header through a CORS gateway.
+  const expected = req.get('If-Match') || req.query.if_match;
+  const current = faq_kb.connectors && faq_kb.connectors.updatedAt ? new Date(faq_kb.connectors.updatedAt) : null;
+  if (expected && current && new Date(expected).getTime() !== current.getTime()) {
+    winston.verbose("(faq_kb) connectors of " + chatbot_id + " changed since " + expected + ": conflict");
+    return res.status(409).send({ success: false, msg: "The connectors list changed since " + expected, connectors: faq_kb.connectors });
+  }
+
+  faq_kb.connectors = { version: collection.version, updatedAt: new Date(), items: collection.items };
+  faq_kb.modified = true;
+  faq_kb.markModified('connectors');
+  const saved = await faq_kb.save();
+  botEvent.emit('faqbot.update', saved);
+  winston.debug("(faq_kb) connectors of " + chatbot_id + " saved: " + saved.connectors.items.length + " records");
+  return res.json(saved.connectors);
+}));
+
 router.patch('/:faq_kbid/attributes', roleChecker.hasRoleOrTypes('admin', ['bot', 'subscription']), function (req, res) {   //TODO add cache_bot_here
   var data = req.body;
 
   const chatbot_id = req.params.faq_kbid;
   const id_project = req.projectid;
 
+  // The version label and the connectors list are fields of the bot since 15/10/2026, not attributes.
+  // A client still sending them the old way (`dsVersion`, `connectors`) gets them promoted: written
+  // to the fields, removed from the attributes, exactly as the import does. The Design Studio V3
+  // sends them this way on purpose when it repairs an agent saved before that date.
+  let promoted = null;
+  if (v3FlowService.legacyAttributeKeys(data).length > 0) {
+    promoted = { attributes: data };
+    v3FlowService.promoteLegacyJson(promoted);
+    if (promoted.connectors !== undefined && promoted.connectors !== null) {
+      const errors = v3FlowService.validateConnectors(promoted.connectors);
+      if (errors.length > 0) {
+        return res.status(400).send({ success: false, msg: "Invalid connectors list", errors: errors });
+      }
+    }
+  }
+
   // TODO use service method
   Faq_kb.findOne({ _id: chatbot_id, id_project: id_project }, function (err, updatedBot) {
     if (err) {
@@ -487,6 +557,20 @@ router.patch('/:faq_kbid/attributes', roleChecker.hasRoleOrTypes('admin', ['bot'
       updatedBot.attributes[key] = val;
     });
 
+    if (promoted) {
+      if (promoted.ds_version && !updatedBot.ds_version) {
+        updatedBot.ds_version = promoted.ds_version;
+      }
+      if (promoted.connectors !== undefined && promoted.connectors !== null) {
+        updatedBot.connectors = { version: promoted.connectors.version, updatedAt: new Date(), items: promoted.connectors.items };
+        updatedBot.markModified('connectors');
+        updatedBot.modified = true;
+      }
+      delete updatedBot.attributes.dsVersion;
+      delete updatedBot.attributes.connectors;
+      winston.verbose("(faq_kb) attributes of " + chatbot_id + ": dsVersion/connectors promoted to the bot fields");
+    }
+
     winston.debug("updatedBot attributes", updatedBot.attributes)
 
     // https://stackoverflow.com/questions/24054552/mongoose-not-saving-nested-object
@@ -577,7 +661,8 @@ router.get('/:faq_kbid', roleChecker.hasRoleOrTypes('admin', ['bot', 'subscripti
   const chatbot_id = req.params.faq_kbid;
   const id_project = req.projectid;
 
-  Faq_kb.findOne({ _id: chatbot_id, id_project: id_project }, function (err, faq_kb) {   //TODO add cache_bot_here
+  // The single GET is how the Design Studio opens an agent: a V3 agent needs its connectors list here.
+  Faq_kb.findOne({ _id: chatbot_id, id_project: id_project }).select('+connectors').exec(function (err, faq_kb) {   //TODO add cache_bot_here
     if (err) {
       return res.status(500).send({ success: false, msg: 'Error getting object.' });
     }

package/services/faqService.js

@@ -6,6 +6,7 @@ const chatbotTypes = require("../models/chatbotTypes");
 const chatbotTemplates = require("../models/chatbotTemplates");
 const templates = require('../template/chatbot');
 const subagentNotes = require('../template/chatbot/subagent_notes');
+const v3FlowService = require('./v3FlowService');
 
 class FaqService {
 
@@ -79,6 +80,18 @@ class FaqService {
       throw new Error("parent_id is required for subtype 'subagent'");
     }
 
+    // A creation body written the old way (`attributes.dsVersion`, `attributes.connectors`) is promoted
+    // to the fields, as the import does: a client not yet updated still creates a proper V3 agent.
+    v3FlowService.promoteLegacyJson(data);
+
+    if (data.connectors !== undefined && data.connectors !== null) {
+      const errors = v3FlowService.validateConnectors(data.connectors);
+      if (errors.length > 0) {
+        winston.error('(FaqService) invalid connectors list: ' + errors.join('; '));
+        throw new Error('Invalid connectors list: ' + errors.join('; '));
+      }
+    }
+
     let chatbot = this.createChatbotObject(id_project, id_user, data);
 
     let template;
@@ -89,6 +102,22 @@ class FaqService {
       }
     }
 
+    let options = {};
+    if (data.namespace_id) {
+      options.namespace_id = data.namespace_id;
+    }
+
+    // A V3 agent is born in V3 form: the template's blocks lose their V2 destinations and the
+    // connectors list is saved with the bot, so nothing has to be repaired on first open.
+    // A list given by the caller (an import, a fork) wins: the template is not converted then.
+    let templateFaqs = null;
+    if (template && v3FlowService.isV3(chatbot) && (data.connectors === undefined || data.connectors === null)) {
+      const flow = v3FlowService.toV3Flow(templates[template](options));
+      chatbot.connectors = flow.connectors;
+      templateFaqs = flow.intents;
+      winston.debug('(FaqService) template ' + template + ' in V3 form: ' + flow.connectors.items.length + ' connectors');
+    }
+
     let savedChatbot;
     try {
       savedChatbot = await chatbot.save();
@@ -98,11 +127,7 @@ class FaqService {
     }
 
     if (template) {
-      let options = {};
-      if (data.namespace_id) {
-        options.namespace_id = data.namespace_id;
-      }
-      this.createGreetingsAndOperationalsFaqs(savedChatbot._id, savedChatbot.createdBy, savedChatbot.id_project, template, options);
+      this.createGreetingsAndOperationalsFaqs(savedChatbot._id, savedChatbot.createdBy, savedChatbot.id_project, template, options, templateFaqs);
     }
 
     botEvent.emit('faqbot.create', savedChatbot);
@@ -141,7 +166,9 @@ class FaqService {
       createdBy: id_user,
       updatedBy: id_user,
       attributes: data.attributes,
-      parent_id: data.parent_id
+      parent_id: data.parent_id,
+      ds_version: v3FlowService.normalizeDsVersion(data.ds_version),
+      connectors: data.connectors
     })
   }
 
@@ -162,13 +189,14 @@ class FaqService {
     return defaultTemplate;
   }
 
-  createGreetingsAndOperationalsFaqs(faq_kb_id, created_by, projectid, template, options) {
+  createGreetingsAndOperationalsFaqs(faq_kb_id, created_by, projectid, template, options, faqs) {
     
     return new Promise( async (resolve, reject) =>  {
 
       winston.debug('(FaqService) create faqs from template: ' + template);
 
-      let faqsArray = templates[template](options);
+      // `faqs`: the template's blocks already prepared by the caller (a V3 agent); otherwise the template as it is.
+      let faqsArray = faqs || templates[template](options);
 
       faqsArray.forEach(faq => {
 

package/services/v3FlowService.js

@@ -0,0 +1,416 @@
+const uuidv4 = require('uuid/v4');
+const winston = require('../config/winston');
+
+/**
+ * The V3 shape of an agent's flow (Design Studio V3, since 15/10/2026).
+ *
+ * A V3 agent (`faq_kb.ds_version === 'v3'`) keeps its links in the bot-level list
+ * `faq_kb.connectors`, not in the destination fields of its actions (`intentName`,
+ * `trueIntent`, `goToIntent`, `cases[].intent`, `attributes.nextBlockAction.intentName`, ...).
+ * Those fields are empty in the stored blocks: the list is the only truth, and both the
+ * Design Studio V3 and the engine (tiledesk-chatbot, ConnectorsV3) read it from there.
+ *
+ * This module is the server's own knowledge of that shape, so an agent born here (from a
+ * template) or coming in (import, fork, restore) is already in V3 form:
+ * - `toV3Flow(intents)`: the blocks of a template, written the V2 way, become V3 blocks plus
+ *   their connectors list (technical ids filled in, list built from the fields, fields cleared);
+ * - `validateConnectors(collection)`: the checks the dedicated endpoint and the import apply;
+ * - `promoteLegacyJson(json)`: a JSON exported before the two fields existed carried them
+ *   inside `attributes`; they are moved to the fields.
+ *
+ * The output catalog is a copy of `connectors/connector-catalog.ts` of the Design Studio and of
+ * `utils/ConnectorsV3.js` of the engine: same types, same fields, same id suffixes. A record is
+ * `{ id, from: { intentId, actionId, slot }, to: { intentId }, kind, props? }` and its id is
+ * `${intentId}/${actionId}${suffix}/${toIntentId}`. If the catalog changes there, it changes here.
+ *
+ * A V2 agent never passes through here: every caller checks `ds_version` first.
+ */
+
+const DS_VERSION_V3 = 'v3';
+const COLLECTION_VERSION = 1;
+const RECORD_KINDS = ['block', 'action', 'button', 'case', 'branch'];
+const RETURN_STACK = 'returnstack';
+const BUTTON_URL = 'url';
+const BUTTON_ACTION = 'action';
+
+const field = (key, suffix, name) => ({ key, kind: 'action', path: 'field', suffix, field: name });
+const nested = (key, suffix, path) => ({ key, kind: 'action', path: 'nested', suffix, steps: path });
+const lastCommand = (key, suffix, name) => ({ key, kind: 'action', path: 'lastCommandSetting', suffix, field: name });
+const BUTTONS = { key: 'button', kind: 'button', path: 'buttons' };
+const array = (key, kind, suffixOf, arrayName, idField, name) => ({ key, kind, path: 'array', suffixOf, array: arrayName, idField, field: name });
+
+const TRUE_FALSE = [field('true', '/true', 'trueIntent'), field('false', '/false', 'falseIntent')];
+const VOICE_SETTINGS = [nested('noInput', '/noInput', ['settings', 'noInputIntent']), nested('noMatch', '/noMatch', ['settings', 'noMatchIntent'])];
+const REPLY_V1 = [BUTTONS, ...VOICE_SETTINGS];
+
+const OUTPUT_CATALOG = {
+  intent:              [field('default', '', 'intentName')],
+  connect_block:       [field('default', '', 'intentName')],
+  reply:               REPLY_V1,
+  randomreply:         REPLY_V1,
+  replyv2:             [BUTTONS, field('noInput', '/noInput', 'noInputIntent'), field('noMatch', '/noMatch', 'noMatchIntent')],
+  ifonlineagents:      TRUE_FALSE,
+  ifonlineagentsv2:    TRUE_FALSE,
+  ifopenhours:         TRUE_FALSE,
+  jsonconditionmulti:  [array('case', 'case', (c) => '/case/' + c._tdCaseId, 'cases', '_tdCaseId', 'intent'), field('else', '/else', 'elseIntent')],
+  jsoncondition:       TRUE_FALSE,
+  jsoncondition2:      TRUE_FALSE,
+  invoke_subagent:     TRUE_FALSE,
+  askgpt:              TRUE_FALSE,
+  askgptv2:            TRUE_FALSE,
+  gpt_task:            TRUE_FALSE,
+  gpt_assistant:       TRUE_FALSE,
+  ai_prompt:           TRUE_FALSE,
+  ai_condition:        [array('branch', 'branch', (b) => '/' + b.label + '/true', 'intents', 'label', 'conditionIntentId'), field('fallback', '/fallback', 'fallbackIntent'), field('error', '/error', 'errorIntent')],
+  webrequestv2:        TRUE_FALSE,
+  data_table:          TRUE_FALSE,
+  make:                TRUE_FALSE,
+  hubspot:             TRUE_FALSE,
+  customerio:          TRUE_FALSE,
+  brevo:               TRUE_FALSE,
+  n8n:                 TRUE_FALSE,
+  qapla:               TRUE_FALSE,
+  capture_user_reply:  [field('default', '', 'goToIntent')],
+  iteration:           [field('goto', '/goto', 'goToIntent'), field('fallback', '/fallback', 'fallbackIntent')],
+  dtmf_menu:           [BUTTONS, ...VOICE_SETTINGS, lastCommand('noInput', '/noInput', 'noInputIntent'), lastCommand('noMatch', '/noMatch', 'noMatchIntent')],
+  dtmf_form:           [BUTTONS, ...VOICE_SETTINGS, lastCommand('noInput', '/noInput', 'noInputIntent'), lastCommand('noMatch', '/noMatch', 'noMatchIntent')],
+  speech_form:         [lastCommand('noInput', '/noInput', 'noInputIntent'), lastCommand('noMatch', '/noMatch', 'noMatchIntent')],
+  blind_transfer:      [BUTTONS, ...VOICE_SETTINGS, lastCommand('true', '/true', 'trueIntent'), lastCommand('false', '/false', 'falseIntent')],
+  send_whatsapp:       TRUE_FALSE,
+};
+
+/** The block's own exit (the dot), stored in `attributes.nextBlockAction.intentName`. */
+const BLOCK_SLOT = { key: 'next', kind: 'block', path: 'block', suffix: '' };
+
+function isSet(value) {
+  return typeof value === 'string' && value !== '';
+}
+
+function hasValidUid(uid) {
+  return typeof uid === 'string' && uid !== '' && uid !== 'UUIDV4';
+}
+
+/** Every `buttons[]` inside the object, at any depth, in visiting order (as the Design Studio's `findButtons`). */
+function findButtons(obj) {
+  let buttons = [];
+  if (Array.isArray(obj)) {
+    for (const element of obj) { buttons = buttons.concat(findButtons(element)); }
+  } else if (obj && typeof obj === 'object') {
+    if (Array.isArray(obj.buttons)) { buttons = buttons.concat(obj.buttons); }
+    for (const key in obj) { if (key !== 'buttons') { buttons = buttons.concat(findButtons(obj[key])); } }
+  }
+  return buttons;
+}
+
+function isReturnStackIntent(intent) {
+  const actions = intent && intent.actions;
+  return Array.isArray(actions) && actions.length === 1 && actions[0] && actions[0]._tdActionType === RETURN_STACK;
+}
+
+/** A button's target is `#<id>` or `#<id>{...params}`; a field's target is `#<id>` (a bare id in old flows). */
+function parseTarget(raw, isButton) {
+  if (!isSet(raw)) { return { toId: null, attrs: null, hasHash: false }; }
+  if (isButton) {
+    const start = raw.indexOf('#') + 1;
+    const end = raw.indexOf('{');
+    const toId = end > -1 ? raw.substring(start, end) : raw.substring(start);
+    return { toId: toId !== '' ? toId : null, attrs: end > -1 ? raw.substring(end) : null, hasHash: raw.trim().startsWith('#') };
+  }
+  const toId = raw.replace('#', '');
+  return { toId: toId !== '' ? toId : null, attrs: null, hasHash: raw.trim().startsWith('#') };
+}
+
+function makeSlot(spec, intentId, actionId, holder, fieldName, item, keyOverride) {
+  const isButton = spec.path === 'buttons';
+  const raw = holder && isSet(holder[fieldName]) ? holder[fieldName] : '';
+  const suffix = spec.path === 'array' ? spec.suffixOf(item) : (isButton ? '/' + item.uid : spec.suffix);
+  return {
+    key: keyOverride || spec.key, kind: spec.kind,
+    intentId, actionId, fromId: intentId + '/' + actionId + suffix,
+    holder, field: fieldName, item, raw, ...parseTarget(raw, isButton)
+  };
+}
+
+/** The exits of one action, connected or empty, in catalog order. Never throws: a malformed action just has fewer exits. */
+function outputsOf(intentId, action) {
+  const out = [];
+  if (!action || typeof action !== 'object') { return out; }
+  const actionId = action._tdActionId;
+  for (const spec of OUTPUT_CATALOG[action._tdActionType] || []) {
+    switch (spec.path) {
+      case 'field':
+        out.push(makeSlot(spec, intentId, actionId, action, spec.field));
+        break;
+      case 'nested': {
+        let holder = action;
+        for (let i = 0; i < spec.steps.length - 1 && holder; i++) { holder = holder[spec.steps[i]]; }
+        if (holder && typeof holder === 'object') { out.push(makeSlot(spec, intentId, actionId, holder, spec.steps[spec.steps.length - 1])); }
+        break;
+      }
+      case 'lastCommandSetting': {
+        const commands = action.attributes && action.attributes.commands;
+        const settings = Array.isArray(commands) && commands.length > 0 && commands[commands.length - 1] ? commands[commands.length - 1].settings : null;
+        if (settings && typeof settings === 'object') { out.push(makeSlot(spec, intentId, actionId, settings, spec.field)); }
+        break;
+      }
+      case 'buttons':
+        // A text button has an empty exit; only an `action` button with a target yields a record. A url button has no exit.
+        for (const button of findButtons(action)) {
+          if (!button || typeof button !== 'object' || button.type === BUTTON_URL) { continue; }
+          const slot = makeSlot(spec, intentId, actionId, button, 'action', button, 'button:' + (button.uid == null ? '' : button.uid));
+          if (button.type !== BUTTON_ACTION) { slot.raw = ''; slot.toId = null; slot.attrs = null; slot.hasHash = false; }
+          out.push(slot);
+        }
+        break;
+      case 'array': {
+        const list = action[spec.array];
+        if (!Array.isArray(list)) { break; }
+        for (const item of list) {
+          if (!item || typeof item !== 'object') { continue; }
+          out.push(makeSlot(spec, intentId, actionId, item, spec.field, item, spec.key + ':' + item[spec.idField]));
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  return out;
+}
+
+function blockOutputOf(intent) {
+  const next = intent && intent.attributes && intent.attributes.nextBlockAction;
+  if (!next || typeof next !== 'object' || isReturnStackIntent(intent)) { return null; }
+  const slot = makeSlot(BLOCK_SLOT, intent.intent_id, next._tdActionId, next, 'intentName');
+  slot.fromId = intent.intent_id + '/' + next._tdActionId;
+  return slot;
+}
+
+/** Every exit of a block: the dot first, then the actions in their order. */
+function slotsOfIntent(intent) {
+  const out = [];
+  const block = blockOutputOf(intent);
+  if (block) { out.push(block); }
+  for (const action of (intent && intent.actions) || []) { out.push(...outputsOf(intent.intent_id, action)); }
+  return out;
+}
+
+/**
+ * Fills in the technical ids a template may leave out: `intent_id`, `_tdActionId` of actions and of
+ * the block's dot, `uid` of buttons, `_tdCaseId` of the cases of a multi condition. The Design Studio
+ * did the same on open; a V3 block must have them before its list is built. Mutates; returns how many.
+ */
+function ensureTechnicalIds(intents) {
+  let filled = 0;
+  for (const intent of intents || []) {
+    if (!intent || typeof intent !== 'object') { continue; }
+    if (!isSet(intent.intent_id)) { intent.intent_id = uuidv4(); filled++; }
+    const next = intent.attributes && intent.attributes.nextBlockAction;
+    if (next && typeof next === 'object' && !isSet(next._tdActionId)) { next._tdActionId = uuidv4(); filled++; }
+    for (const action of intent.actions || []) {
+      if (!action || typeof action !== 'object') { continue; }
+      if (!isSet(action._tdActionId)) { action._tdActionId = uuidv4(); filled++; }
+      for (const button of findButtons(action)) {
+        if (button && typeof button === 'object' && !hasValidUid(button.uid)) { button.uid = uuidv4(); filled++; }
+      }
+      if (Array.isArray(action.cases)) {
+        for (const c of action.cases) {
+          if (c && typeof c === 'object' && !isSet(c._tdCaseId)) { c._tdCaseId = uuidv4(); filled++; }
+        }
+      }
+    }
+  }
+  return filled;
+}
+
+function indexFlow(intents) {
+  const ids = new Set();
+  for (const intent of intents || []) { if (intent && isSet(intent.intent_id)) { ids.add(intent.intent_id); } }
+  return ids;
+}
+
+/** A target that the list can hold: `#<id>` of an existing block, or a bare id that is one (the Design Studio added the `#`). */
+function resolvedTarget(slot, ids) {
+  if (!slot.toId) { return null; }
+  if (slot.hasHash) { return ids.has(slot.toId) ? slot.toId : null; }
+  return ids.has(slot.toId) ? slot.toId : null;
+}
+
+/** A destination written the V2 way: the key exists and holds '' or a `#id` (a bare block name of old flows is left alone). */
+function isV2Trace(slot, ids) {
+  if (!slot.holder || !Object.prototype.hasOwnProperty.call(slot.holder, slot.field)) { return false; }
+  if (slot.raw === '' || slot.hasHash) { return true; }
+  return !!slot.toId && ids.has(slot.toId);
+}
+
+function propsOf(slot, intent) {
+  const props = {};
+  if (slot.kind === 'button' && isSet(slot.attrs)) { props.params = slot.attrs; }
+  const looks = intent && intent.attributes && intent.attributes.connectors && intent.attributes.connectors[slot.fromId];
+  if (looks && typeof looks === 'object') {
+    if (looks.display !== undefined) { props.display = looks.display; }
+    if (looks.label !== undefined) { props.label = looks.label; }
+    if (looks.color !== undefined) { props.color = looks.color; }
+  }
+  return Object.keys(props).length > 0 ? props : null;
+}
+
+/**
+ * The connectors list the blocks describe: one record per connected exit towards a block that
+ * exists. Same ids and same order as the Design Studio's `buildCollection`.
+ */
+function buildConnectors(intents, now) {
+  const ids = indexFlow(intents);
+  const items = [];
+  const seen = new Set();
+  for (const intent of intents || []) {
+    if (!intent) { continue; }
+    for (const slot of slotsOfIntent(intent)) {
+      const toId = resolvedTarget(slot, ids);
+      if (!toId) { continue; }
+      const id = slot.fromId + '/' + toId;
+      if (seen.has(id)) { continue; }
+      seen.add(id);
+      const record = { id, from: { intentId: slot.intentId, actionId: slot.actionId, slot: slot.key }, to: { intentId: toId }, kind: slot.kind };
+      const props = propsOf(slot, intent);
+      if (props) { record.props = props; }
+      items.push(record);
+    }
+  }
+  return { version: COLLECTION_VERSION, updatedAt: now ? now() : new Date().toISOString(), items };
+}
+
+/**
+ * Clears every V2 trace of the connectors from the blocks: destination keys of actions and of the
+ * dot, `button.action`, and the per-block visual attributes (`attributes.connectors`). Mirrors the
+ * Design Studio's `stripV2Connectors`. Mutates; returns how many it removed.
+ */
+function stripDestinations(intents) {
+  const ids = indexFlow(intents);
+  let stripped = 0;
+  for (const intent of intents || []) {
+    if (!intent) { continue; }
+    for (const slot of slotsOfIntent(intent)) {
+      if (!isV2Trace(slot, ids)) { continue; }
+      delete slot.holder[slot.field];
+      stripped++;
+    }
+    if (intent.attributes && Object.prototype.hasOwnProperty.call(intent.attributes, 'connectors')) {
+      delete intent.attributes.connectors;
+      stripped++;
+    }
+  }
+  return stripped;
+}
+
+/**
+ * Blocks written the V2 way (a template, an old JSON) become V3 blocks plus their list.
+ * Mutates the intents it receives and returns `{ intents, connectors }`.
+ */
+function toV3Flow(intents, now) {
+  const list = Array.isArray(intents) ? intents : [];
+  ensureTechnicalIds(list);
+  const connectors = buildConnectors(list, now);
+  stripDestinations(list);
+  return { intents: list, connectors };
+}
+
+/** The errors a connectors list has; empty when it is good. Shape only: targets are not checked against the blocks. */
+function validateConnectors(collection) {
+  const errors = [];
+  if (!collection || typeof collection !== 'object' || Array.isArray(collection)) { return ['connectors must be an object']; }
+  if (collection.version !== COLLECTION_VERSION) { errors.push('connectors.version must be ' + COLLECTION_VERSION); }
+  if (collection.updatedAt !== undefined && collection.updatedAt !== null && isNaN(new Date(collection.updatedAt).getTime())) { errors.push('connectors.updatedAt must be a date'); }
+  if (!Array.isArray(collection.items)) { errors.push('connectors.items must be an array'); return errors; }
+  const ids = new Set();
+  collection.items.forEach((record, i) => {
+    const at = 'connectors.items[' + i + ']';
+    if (!record || typeof record !== 'object') { errors.push(at + ' must be an object'); return; }
+    if (!isSet(record.id)) { errors.push(at + '.id is required'); }
+    const from = record.from && typeof record.from === 'object' ? record.from : null;
+    if (!from || !isSet(from.intentId) || !isSet(from.actionId) || !isSet(from.slot)) { errors.push(at + '.from needs intentId, actionId and slot'); }
+    const to = record.to && typeof record.to === 'object' ? record.to : null;
+    if (!to || !isSet(to.intentId)) { errors.push(at + '.to.intentId is required'); }
+    if (!RECORD_KINDS.includes(record.kind)) { errors.push(at + '.kind must be one of ' + RECORD_KINDS.join(', ')); }
+    if (record.props !== undefined && (record.props === null || typeof record.props !== 'object' || Array.isArray(record.props))) { errors.push(at + '.props must be an object'); }
+    if (isSet(record.id) && from && to && isSet(from.intentId) && isSet(to.intentId)) {
+      if (!record.id.startsWith(from.intentId + '/') || !record.id.endsWith('/' + to.intentId)) { errors.push(at + '.id does not match from.intentId and to.intentId'); }
+    }
+    if (isSet(record.id)) {
+      if (ids.has(record.id)) { errors.push(at + '.id is duplicated: ' + record.id); }
+      ids.add(record.id);
+    }
+  });
+  return errors;
+}
+
+/** 'v3' for any spelling of the V3 label, otherwise undefined. */
+function normalizeDsVersion(value) {
+  if (typeof value !== 'string') { return undefined; }
+  const label = value.trim().toLowerCase();
+  return label === DS_VERSION_V3 ? DS_VERSION_V3 : undefined;
+}
+
+function isV3(bot) {
+  return !!bot && bot.ds_version === DS_VERSION_V3;
+}
+
+/** The legacy keys a PATCH of the attributes must not carry any more. */
+function legacyAttributeKeys(attributes) {
+  if (!attributes || typeof attributes !== 'object') { return []; }
+  return ['dsVersion', 'connectors'].filter((key) => Object.prototype.hasOwnProperty.call(attributes, key));
+}
+
+/**
+ * A JSON exported before 15/10/2026 carries `attributes.dsVersion` and `attributes.connectors`:
+ * they move to `ds_version` and `connectors` (the fields win if both are present). Applies to the
+ * sub agents too. Mutates; returns true if it moved anything.
+ */
+function promoteLegacyJson(json) {
+  if (!json || typeof json !== 'object') { return false; }
+  let moved = false;
+  const attributes = json.attributes;
+  if (attributes && typeof attributes === 'object') {
+    if (Object.prototype.hasOwnProperty.call(attributes, 'dsVersion')) {
+      if (json.ds_version === undefined) {
+        const label = normalizeDsVersion(attributes.dsVersion);
+        if (label) { json.ds_version = label; }
+      }
+      delete attributes.dsVersion;
+      moved = true;
+    }
+    if (Object.prototype.hasOwnProperty.call(attributes, 'connectors')) {
+      if (json.connectors === undefined && attributes.connectors && typeof attributes.connectors === 'object') {
+        json.connectors = attributes.connectors;
+      }
+      delete attributes.connectors;
+      moved = true;
+    }
+  }
+  if (json.ds_version !== undefined) {
+    const label = normalizeDsVersion(json.ds_version);
+    if (label) { json.ds_version = label; } else { delete json.ds_version; }
+  }
+  for (const subagent of Array.isArray(json.subagents) ? json.subagents : []) {
+    if (promoteLegacyJson(subagent)) { moved = true; }
+  }
+  if (moved) { winston.verbose('(V3FlowService) legacy dsVersion/connectors moved out of attributes'); }
+  return moved;
+}
+
+module.exports = {
+  DS_VERSION_V3,
+  COLLECTION_VERSION,
+  RECORD_KINDS,
+  OUTPUT_CATALOG,
+  slotsOfIntent,
+  ensureTechnicalIds,
+  buildConnectors,
+  stripDestinations,
+  toV3Flow,
+  validateConnectors,
+  normalizeDsVersion,
+  isV3,
+  legacyAttributeKeys,
+  promoteLegacyJson
+};