agent-swarm-kit 1.0.233 → 1.0.235

package/README.md

@@ -26,7 +26,7 @@ Unleash the power of collaborative AI with `agent-swarm-kit`! This library empow
 
 ### First Look
 
-Read the [briefing article by the link](https://agent-swarm.github.io/documents/app_getting-started.html)
+Read the [detailed instructions by the link](https://agent-swarm.github.io/documents/app_getting-started.html)
 
 ### Installation
 

package/build/index.cjs

@@ -1085,7 +1085,7 @@ class PersistSwarmUtils {
                     clientId,
                     swarmName,
                 });
-            const isInitial = this.getActiveAgentStorage.has(swarmName);
+            const isInitial = !this.getActiveAgentStorage.has(swarmName);
             const activeAgentStorage = this.getActiveAgentStorage(swarmName);
             await activeAgentStorage.waitForInit(isInitial);
             if (await activeAgentStorage.hasValue(clientId)) {
@@ -1110,7 +1110,7 @@ class PersistSwarmUtils {
                     agentName,
                     swarmName,
                 });
-            const isInitial = this.getActiveAgentStorage.has(swarmName);
+            const isInitial = !this.getActiveAgentStorage.has(swarmName);
             const activeAgentStorage = this.getActiveAgentStorage(swarmName);
             await activeAgentStorage.waitForInit(isInitial);
             await activeAgentStorage.writeValue(clientId, { agentName });
@@ -1129,7 +1129,7 @@ class PersistSwarmUtils {
                     clientId,
                     swarmName,
                 });
-            const isInitial = this.getNavigationStackStorage.has(swarmName);
+            const isInitial = !this.getNavigationStackStorage.has(swarmName);
             const navigationStackStorage = this.getNavigationStackStorage(swarmName);
             await navigationStackStorage.waitForInit(isInitial);
             if (await navigationStackStorage.hasValue(clientId)) {
@@ -1153,7 +1153,7 @@ class PersistSwarmUtils {
                     clientId,
                     swarmName,
                 });
-            const isInitial = this.getNavigationStackStorage.has(swarmName);
+            const isInitial = !this.getNavigationStackStorage.has(swarmName);
             const navigationStackStorage = this.getNavigationStackStorage(swarmName);
             await navigationStackStorage.waitForInit(isInitial);
             await navigationStackStorage.writeValue(clientId, { agentStack });
@@ -1227,7 +1227,7 @@ class PersistStateUtils {
                     clientId,
                     stateName,
                 });
-            const isInitial = this.getStateStorage.has(stateName);
+            const isInitial = !this.getStateStorage.has(stateName);
             const stateStorage = this.getStateStorage(stateName);
             await stateStorage.waitForInit(isInitial);
             await stateStorage.writeValue(clientId, { state });
@@ -1248,7 +1248,7 @@ class PersistStateUtils {
                     clientId,
                     stateName,
                 });
-            const isInitial = this.getStateStorage.has(stateName);
+            const isInitial = !this.getStateStorage.has(stateName);
             const stateStorage = this.getStateStorage(stateName);
             await stateStorage.waitForInit(isInitial);
             if (await stateStorage.hasValue(clientId)) {
@@ -1316,7 +1316,7 @@ class PersistStorageUtils {
                     clientId,
                     storageName,
                 });
-            const isInitial = this.getPersistStorage.has(storageName);
+            const isInitial = !this.getPersistStorage.has(storageName);
             const persistStorage = this.getPersistStorage(storageName);
             await persistStorage.waitForInit(isInitial);
             if (await persistStorage.hasValue(clientId)) {
@@ -1341,7 +1341,7 @@ class PersistStorageUtils {
                     clientId,
                     storageName,
                 });
-            const isInitial = this.getPersistStorage.has(storageName);
+            const isInitial = !this.getPersistStorage.has(storageName);
             const persistStorage = this.getPersistStorage(storageName);
             await persistStorage.waitForInit(isInitial);
             await persistStorage.writeValue(clientId, { data });
@@ -1403,7 +1403,7 @@ class PersistMemoryUtils {
                 swarm$1.loggerService.log(PERSIST_MEMORY_UTILS_METHOD_NAME_SET_MEMORY, {
                     clientId,
                 });
-            const isInitial = this.getMemoryStorage.has(clientId);
+            const isInitial = !this.getMemoryStorage.has(clientId);
             const stateStorage = this.getMemoryStorage(clientId);
             await stateStorage.waitForInit(isInitial);
             await stateStorage.writeValue(clientId, { data });
@@ -1422,7 +1422,7 @@ class PersistMemoryUtils {
                 swarm$1.loggerService.log(PERSIST_MEMORY_UTILS_METHOD_NAME_GET_MEMORY, {
                     clientId,
                 });
-            const isInitial = this.getMemoryStorage.has(clientId);
+            const isInitial = !this.getMemoryStorage.has(clientId);
             const stateStorage = this.getMemoryStorage(clientId);
             await stateStorage.waitForInit(isInitial);
             if (await stateStorage.hasValue(clientId)) {
@@ -1508,7 +1508,7 @@ class PersistAliveUtils {
                 swarm$1.loggerService.log(PERSIST_ALIVE_UTILS_METHOD_NAME_MARK_ONLINE, {
                     clientId,
                 });
-            const isInitial = this.getAliveStorage.has(swarmName);
+            const isInitial = !this.getAliveStorage.has(swarmName);
             const stateStorage = this.getAliveStorage(swarmName);
             await stateStorage.waitForInit(isInitial);
             await stateStorage.writeValue(clientId, { online: true });
@@ -1525,7 +1525,7 @@ class PersistAliveUtils {
                 swarm$1.loggerService.log(PERSIST_ALIVE_UTILS_METHOD_NAME_MARK_OFFLINE, {
                     clientId,
                 });
-            const isInitial = this.getAliveStorage.has(swarmName);
+            const isInitial = !this.getAliveStorage.has(swarmName);
             const stateStorage = this.getAliveStorage(swarmName);
             await stateStorage.waitForInit(isInitial);
             await stateStorage.writeValue(clientId, { online: false });
@@ -1542,7 +1542,7 @@ class PersistAliveUtils {
                 swarm$1.loggerService.log(PERSIST_ALIVE_UTILS_METHOD_NAME_GET_ONLINE, {
                     clientId,
                 });
-            const isInitial = this.getAliveStorage.has(swarmName);
+            const isInitial = !this.getAliveStorage.has(swarmName);
             const stateStorage = this.getAliveStorage(swarmName);
             await stateStorage.waitForInit(isInitial);
             if (await stateStorage.hasValue(clientId)) {
@@ -1606,7 +1606,7 @@ class PersistPolicyUtils {
         this.getBannedClients = async (policyName, swarmName, defaultValue = []) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
                 swarm$1.loggerService.log(PERSIST_POLICY_UTILS_METHOD_NAME_GET_BANNED_CLIENTS);
-            const isInitial = this.getPolicyStorage.has(swarmName);
+            const isInitial = !this.getPolicyStorage.has(swarmName);
             const stateStorage = this.getPolicyStorage(swarmName);
             await stateStorage.waitForInit(isInitial);
             if (await stateStorage.hasValue(policyName)) {
@@ -1627,7 +1627,7 @@ class PersistPolicyUtils {
         this.setBannedClients = async (bannedClients, policyName, swarmName) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
                 swarm$1.loggerService.log(PERSIST_POLICY_UTILS_METHOD_NAME_SET_BANNED_CLIENTS);
-            const isInitial = this.getPolicyStorage.has(swarmName);
+            const isInitial = !this.getPolicyStorage.has(swarmName);
             const stateStorage = this.getPolicyStorage(swarmName);
             await stateStorage.waitForInit(isInitial);
             await stateStorage.writeValue(policyName, { bannedClients });
@@ -1686,7 +1686,7 @@ class PersistEmbeddingUtils {
         this.readEmbeddingCache = async (embeddingName, stringHash) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
                 swarm$1.loggerService.log(PERSIST_EMBEDDING_UTILS_METHOD_NAME_READ_EMBEDDING_CACHE);
-            const isInitial = this.getEmbeddingStorage.has(embeddingName);
+            const isInitial = !this.getEmbeddingStorage.has(embeddingName);
             const stateStorage = this.getEmbeddingStorage(embeddingName);
             await stateStorage.waitForInit(isInitial);
             if (await stateStorage.hasValue(stringHash)) {
@@ -1707,7 +1707,7 @@ class PersistEmbeddingUtils {
         this.writeEmbeddingCache = async (embeddings, embeddingName, stringHash) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
                 swarm$1.loggerService.log(PERSIST_EMBEDDING_UTILS_METHOD_NAME_WRITE_EMBEDDING_CACHE);
-            const isInitial = this.getEmbeddingStorage.has(embeddingName);
+            const isInitial = !this.getEmbeddingStorage.has(embeddingName);
             const stateStorage = this.getEmbeddingStorage(embeddingName);
             await stateStorage.waitForInit(isInitial);
             await stateStorage.writeValue(stringHash, { embeddings });
@@ -2271,7 +2271,7 @@ class HistoryUtils {
                     agentName,
                     value,
                 });
-            const isInitial = this.getHistory.has(clientId);
+            const isInitial = !this.getHistory.has(clientId);
             const history = await this.getHistory(clientId);
             await history.waitForInit(agentName, isInitial);
             return await history.push(value, agentName);
@@ -2288,7 +2288,7 @@ class HistoryUtils {
                     clientId,
                     agentName,
                 });
-            const isInitial = this.getHistory.has(clientId);
+            const isInitial = !this.getHistory.has(clientId);
             const history = await this.getHistory(clientId);
             await history.waitForInit(agentName, isInitial);
             return await history.pop(agentName);
@@ -2328,7 +2328,7 @@ class HistoryUtils {
                 clientId,
                 agentName,
             });
-        const isInitial = this.getHistory.has(clientId);
+        const isInitial = !this.getHistory.has(clientId);
         const history = await this.getHistory(clientId);
         await history.waitForInit(agentName, isInitial);
         for await (const item of history.iterate(agentName)) {
@@ -2759,6 +2759,208 @@ const LoggerAdapter = new LoggerUtils();
  */
 const Logger = LoggerAdapter;
 
+/** @private Constant for logging the constructor in OperatorInstance */
+const OPERATOR_INSTANCE_METHOD_NAME_CTOR = "OperatorInstance.CTOR";
+/** @private Constant for logging the connectAnswer method in OperatorInstance */
+const OPERATOR_INSTANCE_METHOD_NAME_CONNECT_ANSWER = "OperatorInstance.connectAnswer";
+/** @private Constant for logging the notify method in OperatorInstance */
+const OPERATOR_INSTANCE_METHOD_NAME_NOTIFY = "OperatorInstance.notify";
+/** @private Constant for logging the answer method in OperatorInstance */
+const OPERATOR_INSTANCE_METHOD_NAME_ANSWER = "OperatorInstance.answer";
+/** @private Constant for logging the recieveMessage method in OperatorInstance */
+const OPERATOR_INSTANCE_METHOD_NAME_RECEIVE_MESSAGE = "OperatorInstance.recieveMessage";
+/** @private Constant for logging the dispose method in OperatorInstance */
+const OPERATOR_INSTANCE_METHOD_NAME_DISPOSE = "OperatorInstance.dispose";
+/** @private Constant for logging the useOperatorAdapter method in OperatorUtils */
+const METHOD_NAME_USE_OPERATOR_ADAPTER = "OperatorUtils.useOperatorAdapter";
+/** @private Constant for logging the useOperatorCallbacks method in OperatorUtils */
+const METHOD_NAME_USE_OPERATOR_CALLBACKS = "OperatorUtils.useOperatorCallbacks";
+/** @private Constant for logging the connectOperator method in OperatorUtils */
+const METHOD_NAME_CONNECT_OPERATOR = "OperatorUtils.connectOperator";
+/**
+ * Operator instance implementation
+ * @class OperatorInstance
+ * @implements {IOperatorInstance}
+ */
+const OperatorInstance = functoolsKit.makeExtendable(class {
+    /**
+     * Disposed flag for child class
+     */
+    get isDisposed() {
+        return this._isDisposed;
+    }
+    /**
+     * Creates an OperatorInstance
+     * @param {string} clientId - The client identifier
+     * @param {AgentName} agentName - The agent name
+     * @param {Partial<IOperatorInstanceCallbacks>} callbacks - Event callbacks
+     */
+    constructor(clientId, agentName, callbacks) {
+        this.clientId = clientId;
+        this.agentName = agentName;
+        this.callbacks = callbacks;
+        this._answerSubject = new functoolsKit.Subject();
+        this._isDisposed = false;
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            swarm$1.loggerService.debug(OPERATOR_INSTANCE_METHOD_NAME_CTOR, {
+                clientId: this.clientId,
+                agentName,
+            });
+        if (this.callbacks.onInit) {
+            this.callbacks.onInit(clientId, agentName);
+        }
+    }
+    /**
+     * Connects an answer subscription
+     * @param {(answer: string) => void} next - Answer handler callback
+     */
+    connectAnswer(next) {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            swarm$1.loggerService.debug(OPERATOR_INSTANCE_METHOD_NAME_CONNECT_ANSWER, {
+                clientId: this.clientId,
+                agentName: this.agentName,
+            });
+        this._answerSubject.unsubscribeAll();
+        this._answerSubject.subscribe(next);
+    }
+    /**
+     * Sends a notification
+     * @param {string} content - Notification content
+     * @returns {Promise<void>}
+     */
+    async notify(content) {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            swarm$1.loggerService.debug(OPERATOR_INSTANCE_METHOD_NAME_NOTIFY, {
+                clientId: this.clientId,
+                agentName: this.agentName,
+                content,
+            });
+        if (this._isDisposed) {
+            return;
+        }
+        if (this.callbacks.onNotify) {
+            this.callbacks.onNotify(content, this.clientId, this.agentName);
+        }
+    }
+    /**
+     * Sends an answer
+     * @param {string} content - Answer content
+     * @returns {Promise<void>}
+     */
+    async answer(content) {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            swarm$1.loggerService.debug(OPERATOR_INSTANCE_METHOD_NAME_ANSWER, {
+                clientId: this.clientId,
+                agentName: this.agentName,
+                content,
+            });
+        if (this._isDisposed) {
+            return;
+        }
+        if (this._answerSubject.hasListeners) {
+            this.callbacks.onAnswer &&
+                this.callbacks.onAnswer(content, this.clientId, this.agentName);
+            await this._answerSubject.next(content);
+        }
+        else {
+            await this.notify(content);
+        }
+        this._answerSubject.unsubscribeAll();
+    }
+    /**
+     * Receives a message
+     * @param {string} message - Message content
+     * @returns {Promise<void>}
+     */
+    async recieveMessage(message) {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            swarm$1.loggerService.debug(OPERATOR_INSTANCE_METHOD_NAME_RECEIVE_MESSAGE, {
+                clientId: this.clientId,
+                agentName: this.agentName,
+                message,
+            });
+        if (this.callbacks.onMessage) {
+            this.callbacks.onMessage(message, this.clientId, this.agentName);
+        }
+    }
+    /**
+     * Disposes the operator instance
+     * @returns {Promise<void>}
+     */
+    async dispose() {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            swarm$1.loggerService.debug(OPERATOR_INSTANCE_METHOD_NAME_DISPOSE, {
+                clientId: this.clientId,
+                agentName: this.agentName,
+            });
+        if (this.callbacks.onDispose) {
+            this.callbacks.onDispose(this.clientId, this.agentName);
+        }
+        this._answerSubject.unsubscribeAll();
+        this._isDisposed = true;
+    }
+});
+/**
+ * Operator utilities class
+ * @class OperatorUtils
+ * @implements {IOperatorControl}
+ */
+class OperatorUtils {
+    constructor() {
+        this.OperatorFactory = OperatorInstance;
+        this.OperatorCallbacks = {};
+        this.getOperator = functoolsKit.memoize(([clientId, agentName]) => `${clientId}-${agentName}`, (clientId, agentName) => Reflect.construct(this.OperatorFactory, [
+            clientId,
+            agentName,
+            this.OperatorCallbacks,
+        ]));
+    }
+    /**
+     * Sets custom operator adapter constructor
+     * @param {TOperatorInstanceCtor} Ctor - Operator constructor
+     */
+    useOperatorAdapter(Ctor) {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+            swarm$1.loggerService.log(METHOD_NAME_USE_OPERATOR_ADAPTER);
+        this.OperatorFactory = Ctor;
+    }
+    /**
+     * Sets operator callbacks
+     * @param {Partial<IOperatorInstanceCallbacks>} Callbacks - Callback functions
+     */
+    useOperatorCallbacks(Callbacks) {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+            swarm$1.loggerService.log(METHOD_NAME_USE_OPERATOR_CALLBACKS);
+        Object.assign(this.OperatorCallbacks, Callbacks);
+    }
+    /**
+     * Connects an operator instance
+     * @param {string} clientId - Client identifier
+     * @param {AgentName} agentName - Agent name
+     * @returns {(message: string, next: (answer: string) => void) => DisposeFn} Connection function
+     */
+    connectOperator(clientId, agentName) {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+            swarm$1.loggerService.log(METHOD_NAME_CONNECT_OPERATOR, {
+                clientId,
+                agentName,
+            });
+        const operator = this.getOperator(clientId, agentName);
+        return (message, next) => {
+            operator.connectAnswer(next);
+            operator.recieveMessage(message);
+            return async () => {
+                this.getOperator.clear(`${clientId}-${agentName}`);
+                await operator.dispose();
+            };
+        };
+    }
+}
+/** @type {OperatorUtils} Operator adapter instance */
+const OperatorAdapter = new OperatorUtils();
+/** @type {IOperatorControl} Operator control instance */
+const Operator = OperatorAdapter;
+
 const CC_THROW_WHEN_NAVIGATION_RECURSION = true;
 const CC_TOOL_CALL_EXCEPTION_FLUSH_PROMPT = "Start the conversation";
 const CC_TOOL_CALL_EXCEPTION_RECOMPLETE_PROMPT = functoolsKit.str.newline("Please analyze the last tool call message and identify any errors in its syntax or parameters.", "Then, provide a corrected version of the tool call that properly follows the required format and includes all necessary parameters with appropriate values.", "Include a brief explanation of what was fixed as a text content of a new message with correct tool calls request");
@@ -2847,6 +3049,16 @@ const CC_DEFAULT_READ_EMBEDDING_CACHE = (embeddingName, stringHash) => Promise.r
  * @throws {Error} If writing to storage fails (e.g., permissions or disk space).
  */
 const CC_DEFAULT_WRITE_EMBEDDING_CACHE = (embeddings, embeddingName, stringHash) => Promise.resolve();
+/**
+ * Default function to connect an operator for handling messages and responses.
+ * Establishes a connection between a client and an agent, allowing messages to be sent
+ * and answers to be received via a callback mechanism.
+ *
+ * @param {string} clientId - The unique identifier of the client initiating the connection.
+ * @param {AgentName} agentName - The name of the agent to connect with.
+ * @returns {(message: string, next: (answer: string) => void) => DisposeFn}
+ */
+const CC_DEFAULT_CONNECT_OPERATOR = (clientId, agentName) => OperatorAdapter.connectOperator(clientId, agentName);
 const GLOBAL_CONFIG = {
     CC_TOOL_CALL_EXCEPTION_FLUSH_PROMPT,
     CC_TOOL_CALL_EXCEPTION_RECOMPLETE_PROMPT,
@@ -2895,6 +3107,7 @@ const GLOBAL_CONFIG = {
     CC_PERSIST_EMBEDDING_CACHE,
     CC_DEFAULT_AGENT_TOOL_VALIDATE,
     CC_THROW_WHEN_NAVIGATION_RECURSION,
+    CC_DEFAULT_CONNECT_OPERATOR,
 };
 GLOBAL_CONFIG.CC_RESQUE_STRATEGY = "flush";
 /**
@@ -3130,10 +3343,10 @@ class AgentSchemaService {
             if (typeof agentSchema.agentName !== "string") {
                 throw new Error(`agent-swarm agent schema validation failed: missing agentName`);
             }
-            if (typeof agentSchema.completion !== "string") {
+            if (!agentSchema.operator && typeof agentSchema.completion !== "string") {
                 throw new Error(`agent-swarm agent schema validation failed: missing completion for agentName=${agentSchema.agentName}`);
             }
-            if (typeof agentSchema.prompt !== "string") {
+            if (!agentSchema.operator && typeof agentSchema.prompt !== "string") {
                 throw new Error(`agent-swarm agent schema validation failed: missing prompt for agentName=${agentSchema.agentName}`);
             }
             if (agentSchema.system && !Array.isArray(agentSchema.system)) {
@@ -4108,6 +4321,201 @@ class ClientAgent {
     }
 }
 
+/** @private Timeout duration for operator signal in milliseconds */
+const OPERATOR_SIGNAL_TIMEOUT = 90000;
+/** @private Symbol representing operator timeout */
+const OPERATOR_SIGNAL_SYMBOL = Symbol("operator-timeout");
+/**
+ * Manages operator signal communication
+ * @class OperatorSignal
+ */
+class OperatorSignal {
+    /**
+     * Creates an OperatorSignal instance
+     * @param {IOperatorParams} params - Operator parameters
+     */
+    constructor(params) {
+        this.params = params;
+        this._disposeRef = null;
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            params.logger.debug(`OperatorSignal agentName=${params.agentName} clientId=${params.clientId} CTOR`);
+        this._signalFactory = params.connectOperator(params.clientId, params.agentName);
+    }
+    /**
+     * Sends a message through the operator signal
+     * @param {string} message - Message content
+     * @param {(answer: string) => void} next - Callback for response
+     */
+    sendMessage(message, next) {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            this.params.logger.debug(`OperatorSignal agentName=${this.params.agentName} clientId=${this.params.clientId} sendMessage`, { message });
+        this._disposeRef = this._signalFactory(message, next);
+    }
+    /**
+     * Disposes the operator signal
+     * @returns {Promise<void>}
+     */
+    async dispose() {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            this.params.logger.debug(`OperatorSignal agentName=${this.params.agentName} clientId=${this.params.clientId} dispose`);
+        if (this._disposeRef) {
+            this._disposeRef = null;
+            await this._disposeRef();
+        }
+    }
+}
+/**
+ * Client operator implementation
+ * @class ClientOperator
+ * @implements {IAgent}
+ */
+class ClientOperator {
+    /**
+     * Creates a ClientOperator instance
+     * @param {IOperatorParams} params - Operator parameters
+     */
+    constructor(params) {
+        this.params = params;
+        this._outgoingSubject = new functoolsKit.Subject();
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            this.params.logger.debug(`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} CTOR`, { params });
+        this._operatorSignal = new OperatorSignal(params);
+        this.params.onInit && this.params.onInit(params.clientId, params.agentName);
+    }
+    /**
+     * Runs the operator (not supported)
+     * @returns {Promise<string>}
+     */
+    async run() {
+        console.warn(`ClientOperator: run should not be called for clientId=${this.params.clientId} agentName=${this.params.agentName}`);
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            this.params.logger.debug(`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} run - not supported`);
+        return "";
+    }
+    /**
+     * Executes an input with specified mode
+     * @param {string} input - Input content
+     * @param {ExecutionMode} mode - Execution mode
+     * @returns {Promise<void>}
+     */
+    async execute(input, mode) {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            this.params.logger.debug(`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} execute begin`, { input, mode });
+        if (mode === "tool") {
+            console.warn(`ClientOperator: execute with tool mode should not be called for clientId=${this.params.clientId} agentName=${this.params.agentName}`);
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+                this.params.logger.debug(`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} execute - tool mode not supported`);
+            return;
+        }
+        this._operatorSignal.sendMessage(input, this._outgoingSubject.next);
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            this.params.logger.debug(`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} execute end`, { input, mode });
+    }
+    /**
+     * Waits for operator output with timeout
+     * @returns {Promise<string>} Output result or empty string on timeout
+     */
+    async waitForOutput() {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            this.params.logger.debug(`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} waitForOutput begin`);
+        const result = await Promise.race([
+            this._outgoingSubject.toPromise(),
+            functoolsKit.sleep(OPERATOR_SIGNAL_TIMEOUT).then(() => OPERATOR_SIGNAL_SYMBOL),
+        ]);
+        if (typeof result === "symbol") {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+                this.params.logger.debug(`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} waitForOutput timeout after ${OPERATOR_SIGNAL_TIMEOUT}ms`);
+            await this._operatorSignal.dispose();
+            return "";
+        }
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            this.params.logger.debug(`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} waitForOutput end`, { result });
+        return result;
+    }
+    /**
+     * Commits tool output (not supported)
+     * @returns {Promise<void>}
+     */
+    commitToolOutput() {
+        console.warn(`ClientOperator: commitToolOutput should not be called for clientId=${this.params.clientId} agentName=${this.params.agentName}`);
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            this.params.logger.debug(`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} commitToolOutput - not supported`);
+        return Promise.resolve();
+    }
+    /**
+     * Commits system message (not supported)
+     * @returns {Promise<void>}
+     */
+    commitSystemMessage() {
+        console.warn(`ClientOperator: commitSystemMessage should not be called for clientId=${this.params.clientId} agentName=${this.params.agentName}`);
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            this.params.logger.debug(`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} commitSystemMessage - not supported`);
+        return Promise.resolve();
+    }
+    /**
+     * Commits user message
+     * @param {string} content - Message content
+     * @returns {Promise<void>}
+     */
+    commitUserMessage(content) {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            this.params.logger.debug(`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} commitUserMessage`, { content });
+        this._operatorSignal.sendMessage(content, this._outgoingSubject.next);
+        return Promise.resolve();
+    }
+    /**
+     * Commits assistant message (not supported)
+     * @returns {Promise<void>}
+     */
+    commitAssistantMessage() {
+        console.warn(`ClientOperator: commitAssistantMessage should not be called for clientId=${this.params.clientId} agentName=${this.params.agentName}`);
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            this.params.logger.debug(`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} commitAssistantMessage - not supported`);
+        return Promise.resolve();
+    }
+    /**
+     * Commits flush (not supported)
+     * @returns {Promise<void>}
+     */
+    commitFlush() {
+        console.warn(`ClientOperator: commitFlush should not be called for clientId=${this.params.clientId} agentName=${this.params.agentName}`);
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            this.params.logger.debug(`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} commitFlush - not supported`);
+        return Promise.resolve();
+    }
+    /**
+     * Commits stop tools (not supported)
+     * @returns {Promise<void>}
+     */
+    commitStopTools() {
+        console.warn(`ClientOperator: commitStopTools should not be called for clientId=${this.params.clientId} agentName=${this.params.agentName}`);
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            this.params.logger.debug(`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} commitStopTools - not supported`);
+        return Promise.resolve();
+    }
+    /**
+     * Commits agent change
+     * @returns {Promise<void>}
+     */
+    async commitAgentChange() {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            this.params.logger.debug(`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} commitAgentChange`);
+        await this._operatorSignal.dispose();
+    }
+    /**
+     * Disposes the client operator
+     * @returns {Promise<void>}
+     */
+    async dispose() {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            this.params.logger.debug(`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} dispose`);
+        await this._operatorSignal.dispose();
+        this._outgoingSubject.unsubscribeAll();
+        this.params.onDispose &&
+            this.params.onDispose(this.params.clientId, this.params.agentName);
+    }
+}
+
 /**
  * Service class for managing agent connections and operations in the swarm system.
  * Implements IAgent to provide an interface for agent instantiation, execution, message handling, and lifecycle management.
@@ -4198,8 +4606,9 @@ class AgentConnectionService {
          * @returns {ClientAgent} The memoized ClientAgent instance configured for the client and agent.
          */
         this.getAgent = functoolsKit.memoize(([clientId, agentName]) => `${clientId}-${agentName}`, (clientId, agentName) => {
-            const { prompt, system, systemStatic = system, systemDynamic, tools, transform = GLOBAL_CONFIG.CC_AGENT_OUTPUT_TRANSFORM, map = GLOBAL_CONFIG.CC_AGENT_OUTPUT_MAP, maxToolCalls = GLOBAL_CONFIG.CC_MAX_TOOL_CALLS, mapToolCalls = GLOBAL_CONFIG.CC_AGENT_MAP_TOOLS, callbacks, storages, states, completion: completionName, validate = validateDefault, } = this.agentSchemaService.get(agentName);
+            const { prompt, system, operator, systemStatic = system, systemDynamic, tools, transform = GLOBAL_CONFIG.CC_AGENT_OUTPUT_TRANSFORM, map = GLOBAL_CONFIG.CC_AGENT_OUTPUT_MAP, maxToolCalls = GLOBAL_CONFIG.CC_MAX_TOOL_CALLS, mapToolCalls = GLOBAL_CONFIG.CC_AGENT_MAP_TOOLS, callbacks, storages, states, connectOperator = GLOBAL_CONFIG.CC_DEFAULT_CONNECT_OPERATOR, completion: completionName, validate = validateDefault, } = this.agentSchemaService.get(agentName);
             const completion = this.completionSchemaService.get(completionName);
+            const history = this.historyConnectionService.getHistory(clientId, agentName);
             this.sessionValidationService.addAgentUsage(clientId, agentName);
             storages?.forEach((storageName) => this.storageConnectionService
                 .getStorage(clientId, storageName)
@@ -4207,6 +4616,17 @@ class AgentConnectionService {
             states?.forEach((stateName) => this.stateConnectionService
                 .getStateRef(clientId, stateName)
                 .waitForInit());
+            if (operator) {
+                return new ClientOperator({
+                    clientId,
+                    agentName,
+                    bus: this.busService,
+                    history,
+                    logger: this.loggerService,
+                    connectOperator,
+                    ...callbacks,
+                });
+            }
             return new ClientAgent({
                 clientId,
                 agentName,
@@ -4215,7 +4635,7 @@ class AgentConnectionService {
                 mapToolCalls,
                 logger: this.loggerService,
                 bus: this.busService,
-                history: this.historyConnectionService.getHistory(clientId, agentName),
+                history,
                 prompt,
                 systemStatic,
                 systemDynamic,
@@ -18865,6 +19285,8 @@ exports.HistoryPersistInstance = HistoryPersistInstance;
 exports.Logger = Logger;
 exports.LoggerInstance = LoggerInstance;
 exports.MethodContextService = MethodContextService;
+exports.Operator = Operator;
+exports.OperatorInstance = OperatorInstance;
 exports.PayloadContextService = PayloadContextService;
 exports.PersistAlive = PersistAlive;
 exports.PersistBase = PersistBase;