agent-swarm-kit 1.0.84 → 1.0.86

package/build/index.cjs

@@ -195,6 +195,10 @@ var schemaServices$1 = {
     storageSchemaService: Symbol('storageSchemaService'),
     stateSchemaService: Symbol('stateSchemaService'),
 };
+var metaServices$1 = {
+    agentMetaService: Symbol('agentMetaService'),
+    swarmMetaService: Symbol('swarmMetaService'),
+};
 var publicServices$1 = {
     agentPublicService: Symbol('agentPublicService'),
     historyPublicService: Symbol('historyPublicService'),
@@ -212,7 +216,7 @@ var validationServices$1 = {
     embeddingValidationService: Symbol('embeddingValidationService'),
     storageValidationService: Symbol('storageValidationService'),
 };
-var TYPES = __assign(__assign(__assign(__assign(__assign(__assign({}, baseServices$1), contextServices$1), schemaServices$1), connectionServices$1), publicServices$1), validationServices$1);
+var TYPES = __assign(__assign(__assign(__assign(__assign(__assign(__assign({}, baseServices$1), contextServices$1), schemaServices$1), connectionServices$1), publicServices$1), validationServices$1), metaServices$1);
 
 /**
  * Service providing execution context information.
@@ -4933,6 +4937,7 @@ var AgentValidationService = /** @class */ (function () {
         this.completionValidationService = inject(TYPES.completionValidationService);
         this.storageValidationService = inject(TYPES.storageValidationService);
         this._agentMap = new Map();
+        this._agentDepsMap = new Map();
         /**
          * Retrieves the storages used by the agent
          * @param {agentName} agentName - The name of the swarm.
@@ -4973,6 +4978,9 @@ var AgentValidationService = /** @class */ (function () {
                 throw new Error("agent-swarm agent ".concat(agentName, " already exist"));
             }
             _this._agentMap.set(agentName, agentSchema);
+            if (agentSchema.dependsOn) {
+                _this._agentDepsMap.set(agentName, agentSchema.dependsOn);
+            }
         };
         /**
          * Check if agent got registered storage
@@ -4992,6 +5000,23 @@ var AgentValidationService = /** @class */ (function () {
             var _a = _this._agentMap.get(agentName).storages, storages = _a === void 0 ? [] : _a;
             return storages.includes(storageName);
         });
+        /**
+         * Check if agent got registered dependency
+         */
+        this.hasDependency = functoolsKit.memoize(function (_a) {
+            var _b = __read(_a, 2), targetAgentName = _b[0], depAgentName = _b[1];
+            return "".concat(targetAgentName, "-").concat(depAgentName);
+        }, function (targetAgentName, depAgentName) {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                _this.loggerService.info("agentValidationService hasDependency", {
+                    targetAgentName: targetAgentName,
+                    depAgentName: depAgentName,
+                });
+            if (_this._agentDepsMap.has(targetAgentName)) {
+                return _this._agentDepsMap.get(targetAgentName).includes(depAgentName);
+            }
+            return true;
+        });
         /**
          * Check if agent got registered state
          */
@@ -7189,6 +7214,164 @@ var BusService = /** @class */ (function () {
     return BusService;
 }());
 
+var MAX_NESTING = 10;
+var UML_STEP = "\t";
+var UML_BULLET = "•";
+/**
+ * Creates a function to serialize meta nodes to UML format.
+ * @returns {Function} A function that takes an array of IMetaNode and returns a string in UML format.
+ */
+var createSerialize = function () { return function (nodes) {
+    var lines = [];
+    var process = function (nodes, level, seen) {
+        var e_1, _a;
+        var _b;
+        if (level === void 0) { level = 0; }
+        if (seen === void 0) { seen = new Set(); }
+        try {
+            for (var nodes_1 = __values(nodes), nodes_1_1 = nodes_1.next(); !nodes_1_1.done; nodes_1_1 = nodes_1.next()) {
+                var node = nodes_1_1.value;
+                var space = __spreadArray([], __read(new Array(level)), false).fill(UML_STEP).join("");
+                if (seen.has(node.name)) {
+                    lines.push("".concat(space).concat(String(node.name), ": \"\""));
+                }
+                else if (((_b = node.child) === null || _b === void 0 ? void 0 : _b.length) && level < MAX_NESTING) {
+                    lines.push("".concat(space).concat(String(node.name), ":"));
+                    lines.push("".concat(space).concat(UML_STEP).concat(UML_BULLET, " ").concat(String(node.name), ": \"\""));
+                    process(node.child, level + 1, seen.add(node.name));
+                }
+                else {
+                    lines.push("".concat(space).concat(String(node.name), ": \"\""));
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (nodes_1_1 && !nodes_1_1.done && (_a = nodes_1.return)) _a.call(nodes_1);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+    };
+    process(nodes);
+    var result = __spreadArray(__spreadArray(["@startyaml"], __read(lines), false), ["@endyaml"], false).join("\n");
+    return result;
+}; };
+/**
+ * Service class for managing agent meta nodes and converting them to UML format.
+ */
+var AgentMetaService = /** @class */ (function () {
+    function AgentMetaService() {
+        var _this = this;
+        this.loggerService = inject(TYPES.loggerService);
+        this.agentSchemaService = inject(TYPES.agentSchemaService);
+        this.serialize = createSerialize();
+        /**
+         * Creates a meta node for the given agent.
+         * @param {AgentName} agentName - The name of the agent.
+         * @param {Set<AgentName>} seen - A set of seen agent names to avoid circular dependencies.
+         * @returns {IMetaNode} The created meta node.
+         */
+        this.makeAgentNode = function (agentName, seen) {
+            if (seen === void 0) { seen = new Set(); }
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                _this.loggerService.info("agentMetaService makeAgentNode", {
+                    agentName: agentName,
+                });
+            var _a = _this.agentSchemaService.get(agentName), dependsOn = _a.dependsOn, states = _a.states, storages = _a.storages, tools = _a.tools;
+            var childSeen = seen.add(agentName);
+            var agentTree = [];
+            if (dependsOn && !seen.has(agentName)) {
+                agentTree.push({
+                    name: "Agents (".concat(agentName, ")"),
+                    child: dependsOn
+                        .filter(function (name) { return !!name; })
+                        .map(function (dep) { return _this.makeAgentNode(dep, childSeen); }),
+                });
+            }
+            if (states) {
+                agentTree.push({
+                    name: "States (".concat(agentName, ")"),
+                    child: states.filter(function (name) { return !!name; }).map(function (name) { return ({ name: name }); }),
+                });
+            }
+            if (storages) {
+                agentTree.push({
+                    name: "Storages (".concat(agentName, ")"),
+                    child: storages.filter(function (name) { return !!name; }).map(function (name) { return ({ name: name }); }),
+                });
+            }
+            if (tools) {
+                agentTree.push({
+                    name: "Tools (".concat(agentName, ")"),
+                    child: tools.filter(function (name) { return !!name; }).map(function (name) { return ({ name: name }); }),
+                });
+            }
+            return {
+                name: agentName,
+                child: agentTree,
+            };
+        };
+        /**
+         * Converts the meta nodes of the given agent to UML format.
+         * @param {AgentName} agentName - The name of the agent.
+         * @returns {string} The UML representation of the agent's meta nodes.
+         */
+        this.toUML = function (agentName) {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                _this.loggerService.info("agentMetaService toUML", {
+                    agentName: agentName,
+                });
+            var rootNode = _this.makeAgentNode(agentName);
+            return _this.serialize([rootNode]);
+        };
+    }
+    return AgentMetaService;
+}());
+
+/**
+ * Service for handling swarm metadata.
+ */
+var SwarmMetaService = /** @class */ (function () {
+    function SwarmMetaService() {
+        var _this = this;
+        this.loggerService = inject(TYPES.loggerService);
+        this.swarmSchemaService = inject(TYPES.swarmSchemaService);
+        this.agentMetaService = inject(TYPES.agentMetaService);
+        this.serialize = createSerialize();
+        /**
+         * Creates a swarm node with the given swarm name.
+         * @param {SwarmName} swarmName - The name of the swarm.
+         * @returns {IMetaNode} The metadata node of the swarm.
+         */
+        this.makeSwarmNode = function (swarmName) {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                _this.loggerService.info("swarmMetaService makeSwarmNode", {
+                    swarmName: swarmName,
+                });
+            var agentList = _this.swarmSchemaService.get(swarmName).agentList;
+            return {
+                name: swarmName,
+                child: agentList.map(function (dep) { return _this.agentMetaService.makeAgentNode(dep); }),
+            };
+        };
+        /**
+         * Converts the swarm metadata to UML format.
+         * @param {SwarmName} swarmName - The name of the swarm.
+         * @returns {string} The UML representation of the swarm.
+         */
+        this.toUML = function (swarmName) {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                _this.loggerService.info("swarmMetaService toUML", {
+                    swarmName: swarmName,
+                });
+            var rootNode = _this.makeSwarmNode(swarmName);
+            return _this.serialize([rootNode]);
+        };
+    }
+    return SwarmMetaService;
+}());
+
 {
     provide(TYPES.busService, function () { return new BusService(); });
     provide(TYPES.loggerService, function () { return new LoggerService(); });
@@ -7222,6 +7405,10 @@ var BusService = /** @class */ (function () {
     provide(TYPES.storagePublicService, function () { return new StoragePublicService(); });
     provide(TYPES.statePublicService, function () { return new StatePublicService(); });
 }
+{
+    provide(TYPES.swarmMetaService, function () { return new SwarmMetaService(); });
+    provide(TYPES.agentMetaService, function () { return new AgentMetaService(); });
+}
 {
     provide(TYPES.agentPublicService, function () { return new AgentPublicService(); });
     provide(TYPES.historyPublicService, function () { return new HistoryPublicService(); });
@@ -7271,6 +7458,10 @@ var publicServices = {
     storagePublicService: inject(TYPES.storagePublicService),
     statePublicService: inject(TYPES.statePublicService),
 };
+var metaServices = {
+    agentMetaService: inject(TYPES.agentMetaService),
+    swarmMetaService: inject(TYPES.swarmMetaService),
+};
 var validationServices = {
     agentValidationService: inject(TYPES.agentValidationService),
     toolValidationService: inject(TYPES.toolValidationService),
@@ -7280,10 +7471,42 @@ var validationServices = {
     storageValidationService: inject(TYPES.storageValidationService),
     embeddingValidationService: inject(TYPES.embeddingValidationService),
 };
-var swarm = __assign(__assign(__assign(__assign(__assign(__assign({}, baseServices), contextServices), connectionServices), schemaServices), publicServices), validationServices);
+var swarm = __assign(__assign(__assign(__assign(__assign(__assign(__assign({}, baseServices), contextServices), connectionServices), schemaServices), publicServices), metaServices), validationServices);
 init();
 var swarm$1 = swarm;
 
+var METHOD_NAME$E = "function.dumpAgent";
+/**
+ * Dumps the agent information into PlantUML format.
+ *
+ * @param {SwarmName} swarmName - The name of the swarm to be dumped.
+ * @returns {string} The UML representation of the swarm.
+ */
+var dumpAgent = function (agentName) {
+    GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+        swarm$1.loggerService.log(METHOD_NAME$E, {
+            agentName: agentName,
+        });
+    swarm$1.agentValidationService.validate(agentName, METHOD_NAME$E);
+    return swarm$1.agentMetaService.toUML(agentName);
+};
+
+var METHOD_NAME$D = "function.dumpSwarm";
+/**
+ * Dumps the swarm information into PlantUML format.
+ *
+ * @param {SwarmName} swarmName - The name of the swarm to be dumped.
+ * @returns {string} The UML representation of the swarm.
+ */
+var dumpSwarm = function (swarmName) {
+    GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+        swarm$1.loggerService.log(METHOD_NAME$D, {
+            swarmName: swarmName,
+        });
+    swarm$1.swarmValidationService.validate(swarmName, METHOD_NAME$D);
+    return swarm$1.swarmMetaService.toUML(swarmName);
+};
+
 var METHOD_NAME$C = "function.addAgent";
 /**
  * Adds a new agent to the agent registry. The swarm takes only those agents which was registered
@@ -7618,26 +7841,22 @@ var CHANGE_AGENT_GC = 60 * 1000;
  * @returns {TChangeAgentRun} - The change agent function.
  */
 var createChangeAgent = functoolsKit.ttl(function (clientId) {
-    return functoolsKit.queued(function (methodName, agentName) { return __awaiter(void 0, void 0, void 0, function () {
-        var swarmName, _a, _b, _c;
+    return functoolsKit.queued(function (methodName, agentName, swarmName) { return __awaiter(void 0, void 0, void 0, function () {
+        var _a, _b, _c;
         return __generator(this, function (_d) {
             switch (_d.label) {
-                case 0:
-                    swarm$1.sessionValidationService.validate(clientId, METHOD_NAME$s);
-                    swarm$1.agentValidationService.validate(agentName, METHOD_NAME$s);
-                    swarmName = swarm$1.sessionValidationService.getSwarm(clientId);
-                    return [4 /*yield*/, Promise.all(swarm$1.swarmValidationService
-                            .getAgentList(swarmName)
-                            .map(function (agentName) { return __awaiter(void 0, void 0, void 0, function () {
-                            return __generator(this, function (_a) {
-                                switch (_a.label) {
-                                    case 0: return [4 /*yield*/, swarm$1.agentPublicService.commitAgentChange(methodName, clientId, agentName)];
-                                    case 1:
-                                        _a.sent();
-                                        return [2 /*return*/];
-                                }
-                            });
-                        }); }))];
+                case 0: return [4 /*yield*/, Promise.all(swarm$1.swarmValidationService
+                        .getAgentList(swarmName)
+                        .map(function (agentName) { return __awaiter(void 0, void 0, void 0, function () {
+                        return __generator(this, function (_a) {
+                            switch (_a.label) {
+                                case 0: return [4 /*yield*/, swarm$1.agentPublicService.commitAgentChange(methodName, clientId, agentName)];
+                                case 1:
+                                    _a.sent();
+                                    return [2 /*return*/];
+                            }
+                        });
+                    }); }))];
                 case 1:
                     _d.sent();
                     return [4 /*yield*/, swarm$1.agentPublicService.dispose(methodName, clientId, agentName)];
@@ -7689,7 +7908,7 @@ var createGc$1 = functoolsKit.singleshot(function () { return __awaiter(void 0,
  * @returns {Promise<void>} - A promise that resolves when the agent is changed.
  */
 var changeAgent = function (agentName, clientId) { return __awaiter(void 0, void 0, void 0, function () {
-    var run;
+    var swarmName, activeAgent, run;
     return __generator(this, function (_a) {
         switch (_a.label) {
             case 0:
@@ -7698,12 +7917,21 @@ var changeAgent = function (agentName, clientId) { return __awaiter(void 0, void
                         agentName: agentName,
                         clientId: clientId,
                     });
-                return [4 /*yield*/, createChangeAgent(clientId)];
+                swarmName = swarm$1.sessionValidationService.getSwarm(clientId);
+                swarm$1.sessionValidationService.validate(clientId, METHOD_NAME$s);
+                swarm$1.agentValidationService.validate(agentName, METHOD_NAME$s);
+                return [4 /*yield*/, swarm$1.swarmPublicService.getAgentName(METHOD_NAME$s, clientId, swarmName)];
             case 1:
+                activeAgent = _a.sent();
+                if (!swarm$1.agentValidationService.hasDependency(activeAgent, agentName)) {
+                    console.error("agent-swarm missing dependency detected for activeAgent=".concat(activeAgent, " dependencyAgent=").concat(agentName));
+                }
+                return [4 /*yield*/, createChangeAgent(clientId)];
+            case 2:
                 run = _a.sent();
                 createGc$1();
-                return [4 /*yield*/, run(METHOD_NAME$s, agentName)];
-            case 2: return [2 /*return*/, _a.sent()];
+                return [4 /*yield*/, run(METHOD_NAME$s, agentName, swarmName)];
+            case 3: return [2 /*return*/, _a.sent()];
         }
     });
 }); };
@@ -9567,6 +9795,8 @@ exports.commitUserMessage = commitUserMessage;
 exports.commitUserMessageForce = commitUserMessageForce;
 exports.complete = complete;
 exports.disposeConnection = disposeConnection;
+exports.dumpAgent = dumpAgent;
+exports.dumpSwarm = dumpSwarm;
 exports.emit = emit;
 exports.emitForce = emitForce;
 exports.event = event;

package/build/index.mjs

@@ -193,6 +193,10 @@ var schemaServices$1 = {
     storageSchemaService: Symbol('storageSchemaService'),
     stateSchemaService: Symbol('stateSchemaService'),
 };
+var metaServices$1 = {
+    agentMetaService: Symbol('agentMetaService'),
+    swarmMetaService: Symbol('swarmMetaService'),
+};
 var publicServices$1 = {
     agentPublicService: Symbol('agentPublicService'),
     historyPublicService: Symbol('historyPublicService'),
@@ -210,7 +214,7 @@ var validationServices$1 = {
     embeddingValidationService: Symbol('embeddingValidationService'),
     storageValidationService: Symbol('storageValidationService'),
 };
-var TYPES = __assign(__assign(__assign(__assign(__assign(__assign({}, baseServices$1), contextServices$1), schemaServices$1), connectionServices$1), publicServices$1), validationServices$1);
+var TYPES = __assign(__assign(__assign(__assign(__assign(__assign(__assign({}, baseServices$1), contextServices$1), schemaServices$1), connectionServices$1), publicServices$1), validationServices$1), metaServices$1);
 
 /**
  * Service providing execution context information.
@@ -4931,6 +4935,7 @@ var AgentValidationService = /** @class */ (function () {
         this.completionValidationService = inject(TYPES.completionValidationService);
         this.storageValidationService = inject(TYPES.storageValidationService);
         this._agentMap = new Map();
+        this._agentDepsMap = new Map();
         /**
          * Retrieves the storages used by the agent
          * @param {agentName} agentName - The name of the swarm.
@@ -4971,6 +4976,9 @@ var AgentValidationService = /** @class */ (function () {
                 throw new Error("agent-swarm agent ".concat(agentName, " already exist"));
             }
             _this._agentMap.set(agentName, agentSchema);
+            if (agentSchema.dependsOn) {
+                _this._agentDepsMap.set(agentName, agentSchema.dependsOn);
+            }
         };
         /**
          * Check if agent got registered storage
@@ -4990,6 +4998,23 @@ var AgentValidationService = /** @class */ (function () {
             var _a = _this._agentMap.get(agentName).storages, storages = _a === void 0 ? [] : _a;
             return storages.includes(storageName);
         });
+        /**
+         * Check if agent got registered dependency
+         */
+        this.hasDependency = memoize(function (_a) {
+            var _b = __read(_a, 2), targetAgentName = _b[0], depAgentName = _b[1];
+            return "".concat(targetAgentName, "-").concat(depAgentName);
+        }, function (targetAgentName, depAgentName) {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                _this.loggerService.info("agentValidationService hasDependency", {
+                    targetAgentName: targetAgentName,
+                    depAgentName: depAgentName,
+                });
+            if (_this._agentDepsMap.has(targetAgentName)) {
+                return _this._agentDepsMap.get(targetAgentName).includes(depAgentName);
+            }
+            return true;
+        });
         /**
          * Check if agent got registered state
          */
@@ -7187,6 +7212,164 @@ var BusService = /** @class */ (function () {
     return BusService;
 }());
 
+var MAX_NESTING = 10;
+var UML_STEP = "\t";
+var UML_BULLET = "•";
+/**
+ * Creates a function to serialize meta nodes to UML format.
+ * @returns {Function} A function that takes an array of IMetaNode and returns a string in UML format.
+ */
+var createSerialize = function () { return function (nodes) {
+    var lines = [];
+    var process = function (nodes, level, seen) {
+        var e_1, _a;
+        var _b;
+        if (level === void 0) { level = 0; }
+        if (seen === void 0) { seen = new Set(); }
+        try {
+            for (var nodes_1 = __values(nodes), nodes_1_1 = nodes_1.next(); !nodes_1_1.done; nodes_1_1 = nodes_1.next()) {
+                var node = nodes_1_1.value;
+                var space = __spreadArray([], __read(new Array(level)), false).fill(UML_STEP).join("");
+                if (seen.has(node.name)) {
+                    lines.push("".concat(space).concat(String(node.name), ": \"\""));
+                }
+                else if (((_b = node.child) === null || _b === void 0 ? void 0 : _b.length) && level < MAX_NESTING) {
+                    lines.push("".concat(space).concat(String(node.name), ":"));
+                    lines.push("".concat(space).concat(UML_STEP).concat(UML_BULLET, " ").concat(String(node.name), ": \"\""));
+                    process(node.child, level + 1, seen.add(node.name));
+                }
+                else {
+                    lines.push("".concat(space).concat(String(node.name), ": \"\""));
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (nodes_1_1 && !nodes_1_1.done && (_a = nodes_1.return)) _a.call(nodes_1);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+    };
+    process(nodes);
+    var result = __spreadArray(__spreadArray(["@startyaml"], __read(lines), false), ["@endyaml"], false).join("\n");
+    return result;
+}; };
+/**
+ * Service class for managing agent meta nodes and converting them to UML format.
+ */
+var AgentMetaService = /** @class */ (function () {
+    function AgentMetaService() {
+        var _this = this;
+        this.loggerService = inject(TYPES.loggerService);
+        this.agentSchemaService = inject(TYPES.agentSchemaService);
+        this.serialize = createSerialize();
+        /**
+         * Creates a meta node for the given agent.
+         * @param {AgentName} agentName - The name of the agent.
+         * @param {Set<AgentName>} seen - A set of seen agent names to avoid circular dependencies.
+         * @returns {IMetaNode} The created meta node.
+         */
+        this.makeAgentNode = function (agentName, seen) {
+            if (seen === void 0) { seen = new Set(); }
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                _this.loggerService.info("agentMetaService makeAgentNode", {
+                    agentName: agentName,
+                });
+            var _a = _this.agentSchemaService.get(agentName), dependsOn = _a.dependsOn, states = _a.states, storages = _a.storages, tools = _a.tools;
+            var childSeen = seen.add(agentName);
+            var agentTree = [];
+            if (dependsOn && !seen.has(agentName)) {
+                agentTree.push({
+                    name: "Agents (".concat(agentName, ")"),
+                    child: dependsOn
+                        .filter(function (name) { return !!name; })
+                        .map(function (dep) { return _this.makeAgentNode(dep, childSeen); }),
+                });
+            }
+            if (states) {
+                agentTree.push({
+                    name: "States (".concat(agentName, ")"),
+                    child: states.filter(function (name) { return !!name; }).map(function (name) { return ({ name: name }); }),
+                });
+            }
+            if (storages) {
+                agentTree.push({
+                    name: "Storages (".concat(agentName, ")"),
+                    child: storages.filter(function (name) { return !!name; }).map(function (name) { return ({ name: name }); }),
+                });
+            }
+            if (tools) {
+                agentTree.push({
+                    name: "Tools (".concat(agentName, ")"),
+                    child: tools.filter(function (name) { return !!name; }).map(function (name) { return ({ name: name }); }),
+                });
+            }
+            return {
+                name: agentName,
+                child: agentTree,
+            };
+        };
+        /**
+         * Converts the meta nodes of the given agent to UML format.
+         * @param {AgentName} agentName - The name of the agent.
+         * @returns {string} The UML representation of the agent's meta nodes.
+         */
+        this.toUML = function (agentName) {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                _this.loggerService.info("agentMetaService toUML", {
+                    agentName: agentName,
+                });
+            var rootNode = _this.makeAgentNode(agentName);
+            return _this.serialize([rootNode]);
+        };
+    }
+    return AgentMetaService;
+}());
+
+/**
+ * Service for handling swarm metadata.
+ */
+var SwarmMetaService = /** @class */ (function () {
+    function SwarmMetaService() {
+        var _this = this;
+        this.loggerService = inject(TYPES.loggerService);
+        this.swarmSchemaService = inject(TYPES.swarmSchemaService);
+        this.agentMetaService = inject(TYPES.agentMetaService);
+        this.serialize = createSerialize();
+        /**
+         * Creates a swarm node with the given swarm name.
+         * @param {SwarmName} swarmName - The name of the swarm.
+         * @returns {IMetaNode} The metadata node of the swarm.
+         */
+        this.makeSwarmNode = function (swarmName) {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                _this.loggerService.info("swarmMetaService makeSwarmNode", {
+                    swarmName: swarmName,
+                });
+            var agentList = _this.swarmSchemaService.get(swarmName).agentList;
+            return {
+                name: swarmName,
+                child: agentList.map(function (dep) { return _this.agentMetaService.makeAgentNode(dep); }),
+            };
+        };
+        /**
+         * Converts the swarm metadata to UML format.
+         * @param {SwarmName} swarmName - The name of the swarm.
+         * @returns {string} The UML representation of the swarm.
+         */
+        this.toUML = function (swarmName) {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                _this.loggerService.info("swarmMetaService toUML", {
+                    swarmName: swarmName,
+                });
+            var rootNode = _this.makeSwarmNode(swarmName);
+            return _this.serialize([rootNode]);
+        };
+    }
+    return SwarmMetaService;
+}());
+
 {
     provide(TYPES.busService, function () { return new BusService(); });
     provide(TYPES.loggerService, function () { return new LoggerService(); });
@@ -7220,6 +7403,10 @@ var BusService = /** @class */ (function () {
     provide(TYPES.storagePublicService, function () { return new StoragePublicService(); });
     provide(TYPES.statePublicService, function () { return new StatePublicService(); });
 }
+{
+    provide(TYPES.swarmMetaService, function () { return new SwarmMetaService(); });
+    provide(TYPES.agentMetaService, function () { return new AgentMetaService(); });
+}
 {
     provide(TYPES.agentPublicService, function () { return new AgentPublicService(); });
     provide(TYPES.historyPublicService, function () { return new HistoryPublicService(); });
@@ -7269,6 +7456,10 @@ var publicServices = {
     storagePublicService: inject(TYPES.storagePublicService),
     statePublicService: inject(TYPES.statePublicService),
 };
+var metaServices = {
+    agentMetaService: inject(TYPES.agentMetaService),
+    swarmMetaService: inject(TYPES.swarmMetaService),
+};
 var validationServices = {
     agentValidationService: inject(TYPES.agentValidationService),
     toolValidationService: inject(TYPES.toolValidationService),
@@ -7278,10 +7469,42 @@ var validationServices = {
     storageValidationService: inject(TYPES.storageValidationService),
     embeddingValidationService: inject(TYPES.embeddingValidationService),
 };
-var swarm = __assign(__assign(__assign(__assign(__assign(__assign({}, baseServices), contextServices), connectionServices), schemaServices), publicServices), validationServices);
+var swarm = __assign(__assign(__assign(__assign(__assign(__assign(__assign({}, baseServices), contextServices), connectionServices), schemaServices), publicServices), metaServices), validationServices);
 init();
 var swarm$1 = swarm;
 
+var METHOD_NAME$E = "function.dumpAgent";
+/**
+ * Dumps the agent information into PlantUML format.
+ *
+ * @param {SwarmName} swarmName - The name of the swarm to be dumped.
+ * @returns {string} The UML representation of the swarm.
+ */
+var dumpAgent = function (agentName) {
+    GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+        swarm$1.loggerService.log(METHOD_NAME$E, {
+            agentName: agentName,
+        });
+    swarm$1.agentValidationService.validate(agentName, METHOD_NAME$E);
+    return swarm$1.agentMetaService.toUML(agentName);
+};
+
+var METHOD_NAME$D = "function.dumpSwarm";
+/**
+ * Dumps the swarm information into PlantUML format.
+ *
+ * @param {SwarmName} swarmName - The name of the swarm to be dumped.
+ * @returns {string} The UML representation of the swarm.
+ */
+var dumpSwarm = function (swarmName) {
+    GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+        swarm$1.loggerService.log(METHOD_NAME$D, {
+            swarmName: swarmName,
+        });
+    swarm$1.swarmValidationService.validate(swarmName, METHOD_NAME$D);
+    return swarm$1.swarmMetaService.toUML(swarmName);
+};
+
 var METHOD_NAME$C = "function.addAgent";
 /**
  * Adds a new agent to the agent registry. The swarm takes only those agents which was registered
@@ -7616,26 +7839,22 @@ var CHANGE_AGENT_GC = 60 * 1000;
  * @returns {TChangeAgentRun} - The change agent function.
  */
 var createChangeAgent = ttl(function (clientId) {
-    return queued(function (methodName, agentName) { return __awaiter(void 0, void 0, void 0, function () {
-        var swarmName, _a, _b, _c;
+    return queued(function (methodName, agentName, swarmName) { return __awaiter(void 0, void 0, void 0, function () {
+        var _a, _b, _c;
         return __generator(this, function (_d) {
             switch (_d.label) {
-                case 0:
-                    swarm$1.sessionValidationService.validate(clientId, METHOD_NAME$s);
-                    swarm$1.agentValidationService.validate(agentName, METHOD_NAME$s);
-                    swarmName = swarm$1.sessionValidationService.getSwarm(clientId);
-                    return [4 /*yield*/, Promise.all(swarm$1.swarmValidationService
-                            .getAgentList(swarmName)
-                            .map(function (agentName) { return __awaiter(void 0, void 0, void 0, function () {
-                            return __generator(this, function (_a) {
-                                switch (_a.label) {
-                                    case 0: return [4 /*yield*/, swarm$1.agentPublicService.commitAgentChange(methodName, clientId, agentName)];
-                                    case 1:
-                                        _a.sent();
-                                        return [2 /*return*/];
-                                }
-                            });
-                        }); }))];
+                case 0: return [4 /*yield*/, Promise.all(swarm$1.swarmValidationService
+                        .getAgentList(swarmName)
+                        .map(function (agentName) { return __awaiter(void 0, void 0, void 0, function () {
+                        return __generator(this, function (_a) {
+                            switch (_a.label) {
+                                case 0: return [4 /*yield*/, swarm$1.agentPublicService.commitAgentChange(methodName, clientId, agentName)];
+                                case 1:
+                                    _a.sent();
+                                    return [2 /*return*/];
+                            }
+                        });
+                    }); }))];
                 case 1:
                     _d.sent();
                     return [4 /*yield*/, swarm$1.agentPublicService.dispose(methodName, clientId, agentName)];
@@ -7687,7 +7906,7 @@ var createGc$1 = singleshot(function () { return __awaiter(void 0, void 0, void
  * @returns {Promise<void>} - A promise that resolves when the agent is changed.
  */
 var changeAgent = function (agentName, clientId) { return __awaiter(void 0, void 0, void 0, function () {
-    var run;
+    var swarmName, activeAgent, run;
     return __generator(this, function (_a) {
         switch (_a.label) {
             case 0:
@@ -7696,12 +7915,21 @@ var changeAgent = function (agentName, clientId) { return __awaiter(void 0, void
                         agentName: agentName,
                         clientId: clientId,
                     });
-                return [4 /*yield*/, createChangeAgent(clientId)];
+                swarmName = swarm$1.sessionValidationService.getSwarm(clientId);
+                swarm$1.sessionValidationService.validate(clientId, METHOD_NAME$s);
+                swarm$1.agentValidationService.validate(agentName, METHOD_NAME$s);
+                return [4 /*yield*/, swarm$1.swarmPublicService.getAgentName(METHOD_NAME$s, clientId, swarmName)];
             case 1:
+                activeAgent = _a.sent();
+                if (!swarm$1.agentValidationService.hasDependency(activeAgent, agentName)) {
+                    console.error("agent-swarm missing dependency detected for activeAgent=".concat(activeAgent, " dependencyAgent=").concat(agentName));
+                }
+                return [4 /*yield*/, createChangeAgent(clientId)];
+            case 2:
                 run = _a.sent();
                 createGc$1();
-                return [4 /*yield*/, run(METHOD_NAME$s, agentName)];
-            case 2: return [2 /*return*/, _a.sent()];
+                return [4 /*yield*/, run(METHOD_NAME$s, agentName, swarmName)];
+            case 3: return [2 /*return*/, _a.sent()];
         }
     });
 }); };
@@ -9534,4 +9762,4 @@ var SchemaUtils = /** @class */ (function () {
  */
 var Schema = new SchemaUtils();
 
-export { ExecutionContextService, History, HistoryAdapter, HistoryInstance, Logger, LoggerAdapter, LoggerInstance, MethodContextService, Schema, State, Storage, addAgent, addCompletion, addEmbedding, addState, addStorage, addSwarm, addTool, cancelOutput, cancelOutputForce, changeAgent, commitFlush, commitFlushForce, commitSystemMessage, commitSystemMessageForce, commitToolOutput, commitToolOutputForce, commitUserMessage, commitUserMessageForce, complete, disposeConnection, emit, emitForce, event, execute, executeForce, getAgentHistory, getAgentName, getAssistantHistory, getLastAssistantMessage, getLastSystemMessage, getLastUserMessage, getRawHistory, getSessionMode, getUserHistory, listenAgentEvent, listenAgentEventOnce, listenEvent, listenEventOnce, listenHistoryEvent, listenHistoryEventOnce, listenSessionEvent, listenSessionEventOnce, listenStateEvent, listenStateEventOnce, listenStorageEvent, listenStorageEventOnce, listenSwarmEvent, listenSwarmEventOnce, makeAutoDispose, makeConnection, session, setConfig, swarm };
+export { ExecutionContextService, History, HistoryAdapter, HistoryInstance, Logger, LoggerAdapter, LoggerInstance, MethodContextService, Schema, State, Storage, addAgent, addCompletion, addEmbedding, addState, addStorage, addSwarm, addTool, cancelOutput, cancelOutputForce, changeAgent, commitFlush, commitFlushForce, commitSystemMessage, commitSystemMessageForce, commitToolOutput, commitToolOutputForce, commitUserMessage, commitUserMessageForce, complete, disposeConnection, dumpAgent, dumpSwarm, emit, emitForce, event, execute, executeForce, getAgentHistory, getAgentName, getAssistantHistory, getLastAssistantMessage, getLastSystemMessage, getLastUserMessage, getRawHistory, getSessionMode, getUserHistory, listenAgentEvent, listenAgentEventOnce, listenEvent, listenEventOnce, listenHistoryEvent, listenHistoryEventOnce, listenSessionEvent, listenSessionEventOnce, listenStateEvent, listenStateEventOnce, listenStorageEvent, listenStorageEventOnce, listenSwarmEvent, listenSwarmEventOnce, makeAutoDispose, makeConnection, session, setConfig, swarm };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-swarm-kit",
-  "version": "1.0.84",
+  "version": "1.0.86",
   "description": "A TypeScript library for building orchestrated framework-agnostic multi-agent AI systems",
   "author": {
     "name": "Petr Tripolsky",

package/types.d.ts

@@ -1394,6 +1394,8 @@ interface IAgentSchema {
     storages?: StorageName[];
     /** The names of the states used by the agent. */
     states?: StateName[];
+    /** The list of dependencies for changeAgent */
+    dependsOn?: AgentName[];
     /**
      * Validates the output.
      * @param output - The output to validate.
@@ -2343,6 +2345,7 @@ declare class AgentValidationService {
     private readonly completionValidationService;
     private readonly storageValidationService;
     private _agentMap;
+    private _agentDepsMap;
     /**
      * Retrieves the storages used by the agent
      * @param {agentName} agentName - The name of the swarm.
@@ -2368,6 +2371,10 @@ declare class AgentValidationService {
      * Check if agent got registered storage
      */
     hasStorage: ((agentName: AgentName, storageName: StorageName) => boolean) & functools_kit.IClearableMemoize<string> & functools_kit.IControlMemoize<string, boolean>;
+    /**
+     * Check if agent got registered dependency
+     */
+    hasDependency: ((targetAgentName: AgentName, depAgentName: StorageName) => boolean) & functools_kit.IClearableMemoize<string> & functools_kit.IControlMemoize<string, boolean>;
     /**
      * Check if agent got registered state
      */
@@ -3028,6 +3035,57 @@ declare class BusService implements IBus {
     dispose: (clientId: string) => void;
 }
 
+/**
+ * Interface representing a meta node.
+ */
+interface IMetaNode {
+    name: string;
+    child?: IMetaNode[];
+}
+/**
+ * Service class for managing agent meta nodes and converting them to UML format.
+ */
+declare class AgentMetaService {
+    private readonly loggerService;
+    private readonly agentSchemaService;
+    private serialize;
+    /**
+     * Creates a meta node for the given agent.
+     * @param {AgentName} agentName - The name of the agent.
+     * @param {Set<AgentName>} seen - A set of seen agent names to avoid circular dependencies.
+     * @returns {IMetaNode} The created meta node.
+     */
+    makeAgentNode: (agentName: AgentName, seen?: Set<string>) => IMetaNode;
+    /**
+     * Converts the meta nodes of the given agent to UML format.
+     * @param {AgentName} agentName - The name of the agent.
+     * @returns {string} The UML representation of the agent's meta nodes.
+     */
+    toUML: (agentName: AgentName) => string;
+}
+
+/**
+ * Service for handling swarm metadata.
+ */
+declare class SwarmMetaService {
+    private readonly loggerService;
+    private readonly swarmSchemaService;
+    private readonly agentMetaService;
+    private serialize;
+    /**
+     * Creates a swarm node with the given swarm name.
+     * @param {SwarmName} swarmName - The name of the swarm.
+     * @returns {IMetaNode} The metadata node of the swarm.
+     */
+    makeSwarmNode: (swarmName: SwarmName) => IMetaNode;
+    /**
+     * Converts the swarm metadata to UML format.
+     * @param {SwarmName} swarmName - The name of the swarm.
+     * @returns {string} The UML representation of the swarm.
+     */
+    toUML: (swarmName: SwarmName) => string;
+}
+
 declare const swarm: {
     agentValidationService: AgentValidationService;
     toolValidationService: ToolValidationService;
@@ -3036,6 +3094,8 @@ declare const swarm: {
     completionValidationService: CompletionValidationService;
     storageValidationService: StorageValidationService;
     embeddingValidationService: EmbeddingValidationService;
+    agentMetaService: AgentMetaService;
+    swarmMetaService: SwarmMetaService;
     agentPublicService: AgentPublicService;
     historyPublicService: HistoryPublicService;
     sessionPublicService: SessionPublicService;
@@ -3065,6 +3125,22 @@ declare const swarm: {
     loggerService: LoggerService;
 };
 
+/**
+ * Dumps the agent information into PlantUML format.
+ *
+ * @param {SwarmName} swarmName - The name of the swarm to be dumped.
+ * @returns {string} The UML representation of the swarm.
+ */
+declare const dumpAgent: (agentName: AgentName) => string;
+
+/**
+ * Dumps the swarm information into PlantUML format.
+ *
+ * @param {SwarmName} swarmName - The name of the swarm to be dumped.
+ * @returns {string} The UML representation of the swarm.
+ */
+declare const dumpSwarm: (swarmName: SwarmName) => string;
+
 /**
  * Adds a new agent to the agent registry. The swarm takes only those agents which was registered
  *
@@ -3988,4 +4064,4 @@ declare class SchemaUtils {
  */
 declare const Schema: SchemaUtils;
 
-export { type EventSource, ExecutionContextService, History, HistoryAdapter, HistoryInstance, type IAgentSchema, type IAgentTool, type IBaseEvent, type IBusEvent, type IBusEventContext, type ICompletionArgs, type ICompletionSchema, type ICustomEvent, type IEmbeddingSchema, type IHistoryAdapter, type IHistoryInstance, type IHistoryInstanceCallbacks, type IIncomingMessage, type ILoggerAdapter, type ILoggerInstance, type ILoggerInstanceCallbacks, type IMakeConnectionConfig, type IMakeDisposeParams, type IModelMessage, type IOutgoingMessage, type ISessionConfig, type IStateSchema, type IStorageSchema, type ISwarmSchema, type ITool, type IToolCall, Logger, LoggerAdapter, LoggerInstance, MethodContextService, type ReceiveMessageFn, Schema, type SendMessageFn$1 as SendMessageFn, State, Storage, addAgent, addCompletion, addEmbedding, addState, addStorage, addSwarm, addTool, cancelOutput, cancelOutputForce, changeAgent, commitFlush, commitFlushForce, commitSystemMessage, commitSystemMessageForce, commitToolOutput, commitToolOutputForce, commitUserMessage, commitUserMessageForce, complete, disposeConnection, emit, emitForce, event, execute, executeForce, getAgentHistory, getAgentName, getAssistantHistory, getLastAssistantMessage, getLastSystemMessage, getLastUserMessage, getRawHistory, getSessionMode, getUserHistory, listenAgentEvent, listenAgentEventOnce, listenEvent, listenEventOnce, listenHistoryEvent, listenHistoryEventOnce, listenSessionEvent, listenSessionEventOnce, listenStateEvent, listenStateEventOnce, listenStorageEvent, listenStorageEventOnce, listenSwarmEvent, listenSwarmEventOnce, makeAutoDispose, makeConnection, session, setConfig, swarm };
+export { type EventSource, ExecutionContextService, History, HistoryAdapter, HistoryInstance, type IAgentSchema, type IAgentTool, type IBaseEvent, type IBusEvent, type IBusEventContext, type ICompletionArgs, type ICompletionSchema, type ICustomEvent, type IEmbeddingSchema, type IHistoryAdapter, type IHistoryInstance, type IHistoryInstanceCallbacks, type IIncomingMessage, type ILoggerAdapter, type ILoggerInstance, type ILoggerInstanceCallbacks, type IMakeConnectionConfig, type IMakeDisposeParams, type IModelMessage, type IOutgoingMessage, type ISessionConfig, type IStateSchema, type IStorageSchema, type ISwarmSchema, type ITool, type IToolCall, Logger, LoggerAdapter, LoggerInstance, MethodContextService, type ReceiveMessageFn, Schema, type SendMessageFn$1 as SendMessageFn, State, Storage, addAgent, addCompletion, addEmbedding, addState, addStorage, addSwarm, addTool, cancelOutput, cancelOutputForce, changeAgent, commitFlush, commitFlushForce, commitSystemMessage, commitSystemMessageForce, commitToolOutput, commitToolOutputForce, commitUserMessage, commitUserMessageForce, complete, disposeConnection, dumpAgent, dumpSwarm, emit, emitForce, event, execute, executeForce, getAgentHistory, getAgentName, getAssistantHistory, getLastAssistantMessage, getLastSystemMessage, getLastUserMessage, getRawHistory, getSessionMode, getUserHistory, listenAgentEvent, listenAgentEventOnce, listenEvent, listenEventOnce, listenHistoryEvent, listenHistoryEventOnce, listenSessionEvent, listenSessionEventOnce, listenStateEvent, listenStateEventOnce, listenStorageEvent, listenStorageEventOnce, listenSwarmEvent, listenSwarmEventOnce, makeAutoDispose, makeConnection, session, setConfig, swarm };