agent-swarm-kit 1.0.173 → 1.0.175

package/build/index.cjs

@@ -495,6 +495,9 @@ const PERSIST_STORAGE_UTILS_METHOD_NAME_USE_PERSIST_STORAGE_ADAPTER = "PersistSt
 const PERSIST_STORAGE_UTILS_METHOD_NAME_GET_DATA = "PersistStorageUtils.getData";
 /** @private Constant for logging the setData method in PersistStorageUtils */
 const PERSIST_STORAGE_UTILS_METHOD_NAME_SET_DATA = "PersistStorageUtils.setData";
+const PERSIST_POLICY_UTILS_METHOD_NAME_USE_PERSIST_POLICY_ADAPTER = "PersistPolicyUtils.usePersistPolicyAdapter";
+const PERSIST_POLICY_UTILS_METHOD_NAME_GET_BANNED_CLIENTS = "PersistPolicyUtils.getBannedClients";
+const PERSIST_POLICY_UTILS_METHOD_NAME_SET_BANNED_CLIENTS = "PersistPolicyUtils.setBannedClients";
 // Logging method names for private functions
 /** @private Constant for logging the waitForInitFn function */
 const BASE_WAIT_FOR_INIT_FN_METHOD_NAME = "PersistBase.waitForInitFn";
@@ -1551,6 +1554,87 @@ const PersistAliveAdapter = new PersistAliveUtils();
  * @type {IPersistAliveControl}
  */
 const PersistAlive = PersistAliveAdapter;
+/**
+ * Utility class for managing policy data persistence in the swarm system.
+ * Provides methods to get and set banned clients within a `SwarmName`, with a customizable adapter.
+ * @implements {IPersistPolicyControl}
+ */
+class PersistPolicyUtils {
+    constructor() {
+        /** @private Default constructor for policy data persistence, defaults to `PersistBase` */
+        this.PersistPolicyFactory = PersistBase;
+        /**
+         * Memoized function to create or retrieve storage for a specific policy data.
+         * Ensures a single persistence instance per swarm, optimizing resource use.
+         * @private
+         * @param swarmName - The identifier of the swarm.
+         * @returns A persistence instance for the policy data, rooted at `./logs/data/policy/`.
+         */
+        this.getPolicyStorage = functoolsKit.memoize(([swarmName]) => `${swarmName}`, (swarmName) => Reflect.construct(this.PersistPolicyFactory, [
+            swarmName,
+            `./logs/data/policy/`,
+        ]));
+        /**
+         * Retrieves the list of banned clients for a specific policy, defaulting to an empty array if unset.
+         * Used to check client ban status in swarm workflows.
+         * @param policyName - The identifier of the policy to check.
+         * @param swarmName - The identifier of the swarm.
+         * @param defaultValue - Optional default value if no banned clients are found.
+         * @returns A promise resolving to an array of banned client session IDs.
+         * @throws {Error} If reading from storage fails (e.g., file corruption).
+         */
+        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 stateStorage = this.getPolicyStorage(swarmName);
+            await stateStorage.waitForInit(isInitial);
+            if (await stateStorage.hasValue(policyName)) {
+                const { bannedClients } = await stateStorage.readValue(policyName);
+                return bannedClients;
+            }
+            return defaultValue;
+        };
+        /**
+         * Sets the list of banned clients for a specific policy, persisting the status for future retrieval.
+         * Used to manage client bans in swarm operations.
+         * @param bannedClients - Array of session IDs to be banned under this policy.
+         * @param policyName - The identifier of the policy to update.
+         * @param swarmName - The identifier of the swarm.
+         * @returns A promise that resolves when the banned clients list is persisted.
+         * @throws {Error} If writing to storage fails (e.g., permissions or disk space).
+         */
+        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 stateStorage = this.getPolicyStorage(swarmName);
+            await stateStorage.waitForInit(isInitial);
+            await stateStorage.writeValue(policyName, { bannedClients });
+        };
+    }
+    /**
+     * Configures a custom constructor for policy data persistence, overriding the default `PersistBase`.
+     * Enables advanced tracking (e.g., in-memory or database-backed persistence).
+     * @param Ctor - The constructor to use for policy data storage, implementing `IPersistBase`.
+     */
+    usePersistPolicyAdapter(Ctor) {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+            swarm$1.loggerService.log(PERSIST_POLICY_UTILS_METHOD_NAME_USE_PERSIST_POLICY_ADAPTER);
+        this.PersistPolicyFactory = Ctor;
+    }
+}
+/**
+ * Singleton instance of `PersistPolicyUtils` for managing policy data persistence globally.
+ * @type {PersistPolicyUtils}
+ */
+const PersistPolicyAdapter = new PersistPolicyUtils();
+/**
+ * Exported singleton for policy persistence operations, cast as the control interface.
+ * Provides a global point of access for managing client bans in the swarm.
+ * @type {IPersistPolicyControl}
+ */
+const PersistPolicy = PersistPolicyAdapter;
 
 var _a$1, _b$1, _c, _d;
 /** @private Symbol for memoizing the waitForInit method in HistoryMemoryInstance */
@@ -2628,6 +2712,9 @@ const CC_LOGGER_ENABLE_CONSOLE = false;
 let CC_RESQUE_STRATEGY;
 const CC_DEFAULT_STATE_SET = () => Promise.resolve();
 const CC_DEFAULT_STATE_GET = ({}, {}, defaultState) => Promise.resolve(defaultState);
+const CC_DEFAULT_POLICY_GET_BAN_CLIENTS = () => [];
+const CC_DEFAULT_POLICY_GET = () => [];
+const CC_DEFAULT_POLICY_SET = () => Promise.resolve();
 const CC_DEFAULT_STORAGE_GET = ({}, {}, defaultValue) => Promise.resolve(defaultValue);
 const CC_DEFAULT_STORAGE_SET = () => Promise.resolve();
 const CC_NAME_TO_TITLE = nameToTitle;
@@ -2644,6 +2731,9 @@ const GLOBAL_CONFIG = {
     CC_EMPTY_OUTPUT_PLACEHOLDERS,
     CC_KEEP_MESSAGES,
     CC_MAX_TOOL_CALLS,
+    CC_DEFAULT_POLICY_GET_BAN_CLIENTS,
+    CC_DEFAULT_POLICY_GET,
+    CC_DEFAULT_POLICY_SET,
     CC_AGENT_MAP_TOOLS,
     CC_GET_AGENT_HISTORY_ADAPTER,
     CC_GET_CLIENT_LOGGER_ADAPTER,
@@ -3547,15 +3637,15 @@ class ClientAgent {
      * @param {string} message - The user message to commit, trimmed before storage.
      * @returns {Promise<void>} Resolves when the message is committed to history and the event is emitted.
      */
-    async commitUserMessage(message) {
+    async commitUserMessage(message, mode) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
-            this.params.logger.debug(`ClientAgent agentName=${this.params.agentName} clientId=${this.params.clientId} commitUserMessage`, { message });
+            this.params.logger.debug(`ClientAgent agentName=${this.params.agentName} clientId=${this.params.clientId} commitUserMessage`, { message, mode });
         this.params.onUserMessage &&
             this.params.onUserMessage(this.params.clientId, this.params.agentName, message);
         await this.params.history.push({
             role: "user",
             agentName: this.params.agentName,
-            mode: "user",
+            mode,
             content: message.trim(),
         });
         await this.params.bus.emit(this.params.clientId, {
@@ -3954,12 +4044,13 @@ class AgentConnectionService {
          * @param {string} message - The user message to commit.
          * @returns {Promise<any>} A promise resolving to the commit result, type determined by ClientAgent’s implementation.
          */
-        this.commitUserMessage = async (message) => {
+        this.commitUserMessage = async (message, mode) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
                 this.loggerService.info(`agentConnectionService commitUserMessage`, {
                     message,
+                    mode,
                 });
-            return await this.getAgent(this.methodContextService.context.clientId, this.methodContextService.context.agentName).commitUserMessage(message);
+            return await this.getAgent(this.methodContextService.context.clientId, this.methodContextService.context.agentName).commitUserMessage(message, mode);
         };
         /**
          * Commits an agent change to prevent the next tool execution, altering the execution flow.
@@ -5229,13 +5320,14 @@ class ClientSession {
      * @param {string} message - The user message to commit, typically from client input.
      * @returns {Promise<void>} Resolves when the message is committed and the event is logged.
      */
-    async commitUserMessage(message) {
+    async commitUserMessage(message, mode) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             this.params.logger.debug(`ClientSession clientId=${this.params.clientId} commitUserMessage`, {
                 message,
+                mode,
             });
         const agent = await this.params.swarm.getAgent();
-        const result = await agent.commitUserMessage(message);
+        const result = await agent.commitUserMessage(message, mode);
         await this.params.bus.emit(this.params.clientId, {
             type: "commit-user-message",
             source: "session-bus",
@@ -5889,12 +5981,13 @@ class SessionConnectionService {
          * @param {string} message - The user message to commit.
          * @returns {Promise<void>} A promise resolving when the user message is committed.
          */
-        this.commitUserMessage = async (message) => {
+        this.commitUserMessage = async (message, mode) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
                 this.loggerService.info(`sessionConnectionService commitUserMessage`, {
                     message,
+                    mode,
                 });
-            return await this.getSession(this.methodContextService.context.clientId, this.methodContextService.context.swarmName).commitUserMessage(message);
+            return await this.getSession(this.methodContextService.context.clientId, this.methodContextService.context.swarmName).commitUserMessage(message, mode);
         };
         /**
          * Commits a flush of the session’s history, clearing stored data.
@@ -6179,16 +6272,17 @@ class AgentPublicService {
          * @param {AgentName} agentName - The agent name for identification.
          * @returns {Promise<unknown>} A promise resolving to the commit result.
          */
-        this.commitUserMessage = async (message, methodName, clientId, agentName) => {
+        this.commitUserMessage = async (message, mode, methodName, clientId, agentName) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
                 this.loggerService.info("agentPublicService commitUserMessage", {
                     methodName,
                     message,
                     clientId,
                     agentName,
+                    mode,
                 });
             return await MethodContextService.runInContext(async () => {
-                return await this.agentConnectionService.commitUserMessage(message);
+                return await this.agentConnectionService.commitUserMessage(message, mode);
             }, {
                 methodName,
                 clientId,
@@ -6758,16 +6852,17 @@ class SessionPublicService {
          * @param {SwarmName} swarmName - The swarm name for context.
          * @returns {Promise<void>} A promise resolving when the user message is committed.
          */
-        this.commitUserMessage = async (message, methodName, clientId, swarmName) => {
+        this.commitUserMessage = async (message, mode, methodName, clientId, swarmName) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
                 this.loggerService.info("sessionPublicService commitUserMessage", {
                     methodName,
                     message,
                     clientId,
                     swarmName,
+                    mode,
                 });
             return await MethodContextService.runInContext(async () => {
-                return await this.sessionConnectionService.commitUserMessage(message);
+                return await this.sessionConnectionService.commitUserMessage(message, mode);
             }, {
                 methodName,
                 clientId,
@@ -11898,8 +11993,9 @@ class PolicySchemaService {
             if (typeof policySchema.policyName !== "string") {
                 throw new Error(`agent-swarm policy schema validation failed: missing policyName`);
             }
-            if (typeof policySchema.getBannedClients !== "function") {
-                throw new Error(`agent-swarm policy schema validation failed: missing getBannedClients policyName=${policySchema.policyName}`);
+            if (typeof policySchema.validateInput !== "function" &&
+                typeof policySchema.validateOutput !== "function") {
+                throw new Error(`agent-swarm policy schema validation failed: the validateInput or validateOutput must be provided at least policyName=${policySchema.policyName}`);
             }
         };
         /**
@@ -12505,12 +12601,18 @@ class PolicyConnectionService {
          * @returns {ClientPolicy} The memoized ClientPolicy instance configured for the policy.
          */
         this.getPolicy = functoolsKit.memoize(([policyName]) => `${policyName}`, (policyName) => {
-            const { autoBan = GLOBAL_CONFIG.CC_AUTOBAN_ENABLED_BY_DEFAULT, ...schema } = this.policySchemaService.get(policyName);
+            const { autoBan = GLOBAL_CONFIG.CC_AUTOBAN_ENABLED_BY_DEFAULT, banMessage = GLOBAL_CONFIG.CC_BANHAMMER_PLACEHOLDER, persist = GLOBAL_CONFIG.CC_PERSIST_ENABLED_BY_DEFAULT, getBannedClients = persist
+                ? PersistPolicyAdapter.getBannedClients
+                : GLOBAL_CONFIG.CC_DEFAULT_POLICY_GET, setBannedClients = persist
+                ? PersistPolicyAdapter.setBannedClients
+                : GLOBAL_CONFIG.CC_DEFAULT_POLICY_SET, ...schema } = this.policySchemaService.get(policyName);
             return new ClientPolicy({
                 policyName,
                 bus: this.busService,
                 logger: this.loggerService,
-                autoBan,
+                autoBan, getBannedClients,
+                setBannedClients,
+                banMessage,
                 ...schema,
             });
         });
@@ -13452,13 +13554,14 @@ const METHOD_NAME$B = "function.commit.commitSystemMessage";
  * @example
  * await commitUserMessage("User input message", "client-123", "AgentX");
  */
-const commitUserMessage = beginContext(async (content, clientId, agentName) => {
+const commitUserMessage = beginContext(async (content, mode, clientId, agentName) => {
     // Log the operation details if logging is enabled in GLOBAL_CONFIG
     GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
         swarm$1.loggerService.log(METHOD_NAME$B, {
             content,
             clientId,
             agentName,
+            mode,
         });
     // Validate the agent, session, and swarm to ensure they exist and are accessible
     swarm$1.agentValidationService.validate(agentName, METHOD_NAME$B);
@@ -13478,7 +13581,7 @@ const commitUserMessage = beginContext(async (content, clientId, agentName) => {
         return;
     }
     // Commit the user message to the agent's history via the session public service
-    await swarm$1.sessionPublicService.commitUserMessage(content, METHOD_NAME$B, clientId, swarmName);
+    await swarm$1.sessionPublicService.commitUserMessage(content, mode, METHOD_NAME$B, clientId, swarmName);
 });
 
 const METHOD_NAME$A = "function.commit.commitToolOutputForce";
@@ -13593,19 +13696,20 @@ const METHOD_NAME$x = "function.commit.commitSystemMessage";
  * @example
  * await commitUserMessageForce("User input message", "client-123");
  */
-const commitUserMessageForce = beginContext(async (content, clientId) => {
+const commitUserMessageForce = beginContext(async (content, mode, clientId) => {
     // Log the operation details if logging is enabled in GLOBAL_CONFIG
     GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
         swarm$1.loggerService.log(METHOD_NAME$x, {
             content,
             clientId,
+            mode,
         });
     // Validate the session and swarm to ensure they exist and are accessible
     swarm$1.sessionValidationService.validate(clientId, METHOD_NAME$x);
     const swarmName = swarm$1.sessionValidationService.getSwarm(clientId);
     swarm$1.swarmValidationService.validate(swarmName, METHOD_NAME$x);
     // Commit the user message to the agent's history via the session public service without checking the active agent
-    await swarm$1.sessionPublicService.commitUserMessage(content, METHOD_NAME$x, clientId, swarmName);
+    await swarm$1.sessionPublicService.commitUserMessage(content, mode, METHOD_NAME$x, clientId, swarmName);
 });
 
 /** @private Constant defining the method name for logging and validation context */
@@ -14448,13 +14552,13 @@ makeConnection.scheduled = (connector, clientId, swarmName, { delay = SCHEDULED_
             await online();
             if (payload) {
                 return await PayloadContextService.runInContext(async () => {
-                    await swarm$1.sessionPublicService.commitUserMessage(content, METHOD_NAME$i, clientId, swarmName);
+                    await swarm$1.sessionPublicService.commitUserMessage(content, "user", METHOD_NAME$i, clientId, swarmName);
                 }, {
                     clientId,
                     payload,
                 });
             }
-            await swarm$1.sessionPublicService.commitUserMessage(content, METHOD_NAME$i, clientId, swarmName);
+            await swarm$1.sessionPublicService.commitUserMessage(content, "user", METHOD_NAME$i, clientId, swarmName);
         }),
         delay,
     });
@@ -14771,13 +14875,13 @@ session.scheduled = (clientId, swarmName, { delay = SCHEDULED_DELAY } = {}) => {
             await online();
             if (payload) {
                 return await PayloadContextService.runInContext(async () => {
-                    return await swarm$1.sessionPublicService.commitUserMessage(content, METHOD_NAME$g, clientId, swarmName);
+                    return await swarm$1.sessionPublicService.commitUserMessage(content, "user", METHOD_NAME$g, clientId, swarmName);
                 }, {
                     clientId,
                     payload,
                 });
             }
-            return await swarm$1.sessionPublicService.commitUserMessage(content, METHOD_NAME$g, clientId, swarmName);
+            return await swarm$1.sessionPublicService.commitUserMessage(content, "user", METHOD_NAME$g, clientId, swarmName);
         }),
         delay,
     });
@@ -17159,6 +17263,7 @@ const Utils = {
     PersistStorageUtils,
     PersistMemoryUtils,
     PersistAliveUtils,
+    PersistPolicyUtils,
 };
 
 exports.Adapter = Adapter;
@@ -17174,6 +17279,7 @@ exports.PersistAlive = PersistAlive;
 exports.PersistBase = PersistBase;
 exports.PersistList = PersistList;
 exports.PersistMemory = PersistMemory;
+exports.PersistPolicy = PersistPolicy;
 exports.PersistState = PersistState;
 exports.PersistStorage = PersistStorage;
 exports.PersistSwarm = PersistSwarm;

package/build/index.mjs

@@ -493,6 +493,9 @@ const PERSIST_STORAGE_UTILS_METHOD_NAME_USE_PERSIST_STORAGE_ADAPTER = "PersistSt
 const PERSIST_STORAGE_UTILS_METHOD_NAME_GET_DATA = "PersistStorageUtils.getData";
 /** @private Constant for logging the setData method in PersistStorageUtils */
 const PERSIST_STORAGE_UTILS_METHOD_NAME_SET_DATA = "PersistStorageUtils.setData";
+const PERSIST_POLICY_UTILS_METHOD_NAME_USE_PERSIST_POLICY_ADAPTER = "PersistPolicyUtils.usePersistPolicyAdapter";
+const PERSIST_POLICY_UTILS_METHOD_NAME_GET_BANNED_CLIENTS = "PersistPolicyUtils.getBannedClients";
+const PERSIST_POLICY_UTILS_METHOD_NAME_SET_BANNED_CLIENTS = "PersistPolicyUtils.setBannedClients";
 // Logging method names for private functions
 /** @private Constant for logging the waitForInitFn function */
 const BASE_WAIT_FOR_INIT_FN_METHOD_NAME = "PersistBase.waitForInitFn";
@@ -1549,6 +1552,87 @@ const PersistAliveAdapter = new PersistAliveUtils();
  * @type {IPersistAliveControl}
  */
 const PersistAlive = PersistAliveAdapter;
+/**
+ * Utility class for managing policy data persistence in the swarm system.
+ * Provides methods to get and set banned clients within a `SwarmName`, with a customizable adapter.
+ * @implements {IPersistPolicyControl}
+ */
+class PersistPolicyUtils {
+    constructor() {
+        /** @private Default constructor for policy data persistence, defaults to `PersistBase` */
+        this.PersistPolicyFactory = PersistBase;
+        /**
+         * Memoized function to create or retrieve storage for a specific policy data.
+         * Ensures a single persistence instance per swarm, optimizing resource use.
+         * @private
+         * @param swarmName - The identifier of the swarm.
+         * @returns A persistence instance for the policy data, rooted at `./logs/data/policy/`.
+         */
+        this.getPolicyStorage = memoize(([swarmName]) => `${swarmName}`, (swarmName) => Reflect.construct(this.PersistPolicyFactory, [
+            swarmName,
+            `./logs/data/policy/`,
+        ]));
+        /**
+         * Retrieves the list of banned clients for a specific policy, defaulting to an empty array if unset.
+         * Used to check client ban status in swarm workflows.
+         * @param policyName - The identifier of the policy to check.
+         * @param swarmName - The identifier of the swarm.
+         * @param defaultValue - Optional default value if no banned clients are found.
+         * @returns A promise resolving to an array of banned client session IDs.
+         * @throws {Error} If reading from storage fails (e.g., file corruption).
+         */
+        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 stateStorage = this.getPolicyStorage(swarmName);
+            await stateStorage.waitForInit(isInitial);
+            if (await stateStorage.hasValue(policyName)) {
+                const { bannedClients } = await stateStorage.readValue(policyName);
+                return bannedClients;
+            }
+            return defaultValue;
+        };
+        /**
+         * Sets the list of banned clients for a specific policy, persisting the status for future retrieval.
+         * Used to manage client bans in swarm operations.
+         * @param bannedClients - Array of session IDs to be banned under this policy.
+         * @param policyName - The identifier of the policy to update.
+         * @param swarmName - The identifier of the swarm.
+         * @returns A promise that resolves when the banned clients list is persisted.
+         * @throws {Error} If writing to storage fails (e.g., permissions or disk space).
+         */
+        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 stateStorage = this.getPolicyStorage(swarmName);
+            await stateStorage.waitForInit(isInitial);
+            await stateStorage.writeValue(policyName, { bannedClients });
+        };
+    }
+    /**
+     * Configures a custom constructor for policy data persistence, overriding the default `PersistBase`.
+     * Enables advanced tracking (e.g., in-memory or database-backed persistence).
+     * @param Ctor - The constructor to use for policy data storage, implementing `IPersistBase`.
+     */
+    usePersistPolicyAdapter(Ctor) {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+            swarm$1.loggerService.log(PERSIST_POLICY_UTILS_METHOD_NAME_USE_PERSIST_POLICY_ADAPTER);
+        this.PersistPolicyFactory = Ctor;
+    }
+}
+/**
+ * Singleton instance of `PersistPolicyUtils` for managing policy data persistence globally.
+ * @type {PersistPolicyUtils}
+ */
+const PersistPolicyAdapter = new PersistPolicyUtils();
+/**
+ * Exported singleton for policy persistence operations, cast as the control interface.
+ * Provides a global point of access for managing client bans in the swarm.
+ * @type {IPersistPolicyControl}
+ */
+const PersistPolicy = PersistPolicyAdapter;
 
 var _a$1, _b$1, _c, _d;
 /** @private Symbol for memoizing the waitForInit method in HistoryMemoryInstance */
@@ -2626,6 +2710,9 @@ const CC_LOGGER_ENABLE_CONSOLE = false;
 let CC_RESQUE_STRATEGY;
 const CC_DEFAULT_STATE_SET = () => Promise.resolve();
 const CC_DEFAULT_STATE_GET = ({}, {}, defaultState) => Promise.resolve(defaultState);
+const CC_DEFAULT_POLICY_GET_BAN_CLIENTS = () => [];
+const CC_DEFAULT_POLICY_GET = () => [];
+const CC_DEFAULT_POLICY_SET = () => Promise.resolve();
 const CC_DEFAULT_STORAGE_GET = ({}, {}, defaultValue) => Promise.resolve(defaultValue);
 const CC_DEFAULT_STORAGE_SET = () => Promise.resolve();
 const CC_NAME_TO_TITLE = nameToTitle;
@@ -2642,6 +2729,9 @@ const GLOBAL_CONFIG = {
     CC_EMPTY_OUTPUT_PLACEHOLDERS,
     CC_KEEP_MESSAGES,
     CC_MAX_TOOL_CALLS,
+    CC_DEFAULT_POLICY_GET_BAN_CLIENTS,
+    CC_DEFAULT_POLICY_GET,
+    CC_DEFAULT_POLICY_SET,
     CC_AGENT_MAP_TOOLS,
     CC_GET_AGENT_HISTORY_ADAPTER,
     CC_GET_CLIENT_LOGGER_ADAPTER,
@@ -3545,15 +3635,15 @@ class ClientAgent {
      * @param {string} message - The user message to commit, trimmed before storage.
      * @returns {Promise<void>} Resolves when the message is committed to history and the event is emitted.
      */
-    async commitUserMessage(message) {
+    async commitUserMessage(message, mode) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
-            this.params.logger.debug(`ClientAgent agentName=${this.params.agentName} clientId=${this.params.clientId} commitUserMessage`, { message });
+            this.params.logger.debug(`ClientAgent agentName=${this.params.agentName} clientId=${this.params.clientId} commitUserMessage`, { message, mode });
         this.params.onUserMessage &&
             this.params.onUserMessage(this.params.clientId, this.params.agentName, message);
         await this.params.history.push({
             role: "user",
             agentName: this.params.agentName,
-            mode: "user",
+            mode,
             content: message.trim(),
         });
         await this.params.bus.emit(this.params.clientId, {
@@ -3952,12 +4042,13 @@ class AgentConnectionService {
          * @param {string} message - The user message to commit.
          * @returns {Promise<any>} A promise resolving to the commit result, type determined by ClientAgent’s implementation.
          */
-        this.commitUserMessage = async (message) => {
+        this.commitUserMessage = async (message, mode) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
                 this.loggerService.info(`agentConnectionService commitUserMessage`, {
                     message,
+                    mode,
                 });
-            return await this.getAgent(this.methodContextService.context.clientId, this.methodContextService.context.agentName).commitUserMessage(message);
+            return await this.getAgent(this.methodContextService.context.clientId, this.methodContextService.context.agentName).commitUserMessage(message, mode);
         };
         /**
          * Commits an agent change to prevent the next tool execution, altering the execution flow.
@@ -5227,13 +5318,14 @@ class ClientSession {
      * @param {string} message - The user message to commit, typically from client input.
      * @returns {Promise<void>} Resolves when the message is committed and the event is logged.
      */
-    async commitUserMessage(message) {
+    async commitUserMessage(message, mode) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             this.params.logger.debug(`ClientSession clientId=${this.params.clientId} commitUserMessage`, {
                 message,
+                mode,
             });
         const agent = await this.params.swarm.getAgent();
-        const result = await agent.commitUserMessage(message);
+        const result = await agent.commitUserMessage(message, mode);
         await this.params.bus.emit(this.params.clientId, {
             type: "commit-user-message",
             source: "session-bus",
@@ -5887,12 +5979,13 @@ class SessionConnectionService {
          * @param {string} message - The user message to commit.
          * @returns {Promise<void>} A promise resolving when the user message is committed.
          */
-        this.commitUserMessage = async (message) => {
+        this.commitUserMessage = async (message, mode) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
                 this.loggerService.info(`sessionConnectionService commitUserMessage`, {
                     message,
+                    mode,
                 });
-            return await this.getSession(this.methodContextService.context.clientId, this.methodContextService.context.swarmName).commitUserMessage(message);
+            return await this.getSession(this.methodContextService.context.clientId, this.methodContextService.context.swarmName).commitUserMessage(message, mode);
         };
         /**
          * Commits a flush of the session’s history, clearing stored data.
@@ -6177,16 +6270,17 @@ class AgentPublicService {
          * @param {AgentName} agentName - The agent name for identification.
          * @returns {Promise<unknown>} A promise resolving to the commit result.
          */
-        this.commitUserMessage = async (message, methodName, clientId, agentName) => {
+        this.commitUserMessage = async (message, mode, methodName, clientId, agentName) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
                 this.loggerService.info("agentPublicService commitUserMessage", {
                     methodName,
                     message,
                     clientId,
                     agentName,
+                    mode,
                 });
             return await MethodContextService.runInContext(async () => {
-                return await this.agentConnectionService.commitUserMessage(message);
+                return await this.agentConnectionService.commitUserMessage(message, mode);
             }, {
                 methodName,
                 clientId,
@@ -6756,16 +6850,17 @@ class SessionPublicService {
          * @param {SwarmName} swarmName - The swarm name for context.
          * @returns {Promise<void>} A promise resolving when the user message is committed.
          */
-        this.commitUserMessage = async (message, methodName, clientId, swarmName) => {
+        this.commitUserMessage = async (message, mode, methodName, clientId, swarmName) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
                 this.loggerService.info("sessionPublicService commitUserMessage", {
                     methodName,
                     message,
                     clientId,
                     swarmName,
+                    mode,
                 });
             return await MethodContextService.runInContext(async () => {
-                return await this.sessionConnectionService.commitUserMessage(message);
+                return await this.sessionConnectionService.commitUserMessage(message, mode);
             }, {
                 methodName,
                 clientId,
@@ -11896,8 +11991,9 @@ class PolicySchemaService {
             if (typeof policySchema.policyName !== "string") {
                 throw new Error(`agent-swarm policy schema validation failed: missing policyName`);
             }
-            if (typeof policySchema.getBannedClients !== "function") {
-                throw new Error(`agent-swarm policy schema validation failed: missing getBannedClients policyName=${policySchema.policyName}`);
+            if (typeof policySchema.validateInput !== "function" &&
+                typeof policySchema.validateOutput !== "function") {
+                throw new Error(`agent-swarm policy schema validation failed: the validateInput or validateOutput must be provided at least policyName=${policySchema.policyName}`);
             }
         };
         /**
@@ -12503,12 +12599,18 @@ class PolicyConnectionService {
          * @returns {ClientPolicy} The memoized ClientPolicy instance configured for the policy.
          */
         this.getPolicy = memoize(([policyName]) => `${policyName}`, (policyName) => {
-            const { autoBan = GLOBAL_CONFIG.CC_AUTOBAN_ENABLED_BY_DEFAULT, ...schema } = this.policySchemaService.get(policyName);
+            const { autoBan = GLOBAL_CONFIG.CC_AUTOBAN_ENABLED_BY_DEFAULT, banMessage = GLOBAL_CONFIG.CC_BANHAMMER_PLACEHOLDER, persist = GLOBAL_CONFIG.CC_PERSIST_ENABLED_BY_DEFAULT, getBannedClients = persist
+                ? PersistPolicyAdapter.getBannedClients
+                : GLOBAL_CONFIG.CC_DEFAULT_POLICY_GET, setBannedClients = persist
+                ? PersistPolicyAdapter.setBannedClients
+                : GLOBAL_CONFIG.CC_DEFAULT_POLICY_SET, ...schema } = this.policySchemaService.get(policyName);
             return new ClientPolicy({
                 policyName,
                 bus: this.busService,
                 logger: this.loggerService,
-                autoBan,
+                autoBan, getBannedClients,
+                setBannedClients,
+                banMessage,
                 ...schema,
             });
         });
@@ -13450,13 +13552,14 @@ const METHOD_NAME$B = "function.commit.commitSystemMessage";
  * @example
  * await commitUserMessage("User input message", "client-123", "AgentX");
  */
-const commitUserMessage = beginContext(async (content, clientId, agentName) => {
+const commitUserMessage = beginContext(async (content, mode, clientId, agentName) => {
     // Log the operation details if logging is enabled in GLOBAL_CONFIG
     GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
         swarm$1.loggerService.log(METHOD_NAME$B, {
             content,
             clientId,
             agentName,
+            mode,
         });
     // Validate the agent, session, and swarm to ensure they exist and are accessible
     swarm$1.agentValidationService.validate(agentName, METHOD_NAME$B);
@@ -13476,7 +13579,7 @@ const commitUserMessage = beginContext(async (content, clientId, agentName) => {
         return;
     }
     // Commit the user message to the agent's history via the session public service
-    await swarm$1.sessionPublicService.commitUserMessage(content, METHOD_NAME$B, clientId, swarmName);
+    await swarm$1.sessionPublicService.commitUserMessage(content, mode, METHOD_NAME$B, clientId, swarmName);
 });
 
 const METHOD_NAME$A = "function.commit.commitToolOutputForce";
@@ -13591,19 +13694,20 @@ const METHOD_NAME$x = "function.commit.commitSystemMessage";
  * @example
  * await commitUserMessageForce("User input message", "client-123");
  */
-const commitUserMessageForce = beginContext(async (content, clientId) => {
+const commitUserMessageForce = beginContext(async (content, mode, clientId) => {
     // Log the operation details if logging is enabled in GLOBAL_CONFIG
     GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
         swarm$1.loggerService.log(METHOD_NAME$x, {
             content,
             clientId,
+            mode,
         });
     // Validate the session and swarm to ensure they exist and are accessible
     swarm$1.sessionValidationService.validate(clientId, METHOD_NAME$x);
     const swarmName = swarm$1.sessionValidationService.getSwarm(clientId);
     swarm$1.swarmValidationService.validate(swarmName, METHOD_NAME$x);
     // Commit the user message to the agent's history via the session public service without checking the active agent
-    await swarm$1.sessionPublicService.commitUserMessage(content, METHOD_NAME$x, clientId, swarmName);
+    await swarm$1.sessionPublicService.commitUserMessage(content, mode, METHOD_NAME$x, clientId, swarmName);
 });
 
 /** @private Constant defining the method name for logging and validation context */
@@ -14446,13 +14550,13 @@ makeConnection.scheduled = (connector, clientId, swarmName, { delay = SCHEDULED_
             await online();
             if (payload) {
                 return await PayloadContextService.runInContext(async () => {
-                    await swarm$1.sessionPublicService.commitUserMessage(content, METHOD_NAME$i, clientId, swarmName);
+                    await swarm$1.sessionPublicService.commitUserMessage(content, "user", METHOD_NAME$i, clientId, swarmName);
                 }, {
                     clientId,
                     payload,
                 });
             }
-            await swarm$1.sessionPublicService.commitUserMessage(content, METHOD_NAME$i, clientId, swarmName);
+            await swarm$1.sessionPublicService.commitUserMessage(content, "user", METHOD_NAME$i, clientId, swarmName);
         }),
         delay,
     });
@@ -14769,13 +14873,13 @@ session.scheduled = (clientId, swarmName, { delay = SCHEDULED_DELAY } = {}) => {
             await online();
             if (payload) {
                 return await PayloadContextService.runInContext(async () => {
-                    return await swarm$1.sessionPublicService.commitUserMessage(content, METHOD_NAME$g, clientId, swarmName);
+                    return await swarm$1.sessionPublicService.commitUserMessage(content, "user", METHOD_NAME$g, clientId, swarmName);
                 }, {
                     clientId,
                     payload,
                 });
             }
-            return await swarm$1.sessionPublicService.commitUserMessage(content, METHOD_NAME$g, clientId, swarmName);
+            return await swarm$1.sessionPublicService.commitUserMessage(content, "user", METHOD_NAME$g, clientId, swarmName);
         }),
         delay,
     });
@@ -17157,6 +17261,7 @@ const Utils = {
     PersistStorageUtils,
     PersistMemoryUtils,
     PersistAliveUtils,
+    PersistPolicyUtils,
 };
 
-export { Adapter, ExecutionContextService, History, HistoryMemoryInstance, HistoryPersistInstance, Logger, LoggerInstance, MethodContextService, PayloadContextService, PersistAlive, PersistBase, PersistList, PersistMemory, PersistState, PersistStorage, PersistSwarm, Policy, Schema, SharedState, SharedStorage, State, Storage, Utils, addAgent, addCompletion, addEmbedding, addPolicy, addState, addStorage, addSwarm, addTool, beginContext, cancelOutput, cancelOutputForce, changeToAgent, changeToDefaultAgent, changeToPrevAgent, commitAssistantMessage, commitAssistantMessageForce, commitFlush, commitFlushForce, commitStopTools, commitStopToolsForce, commitSystemMessage, commitSystemMessageForce, commitToolOutput, commitToolOutputForce, commitUserMessage, commitUserMessageForce, complete, disposeConnection, dumpAgent, dumpClientPerformance, dumpDocs, dumpPerfomance, dumpSwarm, emit, emitForce, event, execute, executeForce, getAgentHistory, getAgentName, getAssistantHistory, getLastAssistantMessage, getLastSystemMessage, getLastUserMessage, getPayload, getRawHistory, getSessionContext, getSessionMode, getUserHistory, listenAgentEvent, listenAgentEventOnce, listenEvent, listenEventOnce, listenExecutionEvent, listenExecutionEventOnce, listenHistoryEvent, listenHistoryEventOnce, listenPolicyEvent, listenPolicyEventOnce, listenSessionEvent, listenSessionEventOnce, listenStateEvent, listenStateEventOnce, listenStorageEvent, listenStorageEventOnce, listenSwarmEvent, listenSwarmEventOnce, makeAutoDispose, makeConnection, markOffline, markOnline, runStateless, runStatelessForce, session, setConfig, swarm };
+export { Adapter, ExecutionContextService, History, HistoryMemoryInstance, HistoryPersistInstance, Logger, LoggerInstance, MethodContextService, PayloadContextService, PersistAlive, PersistBase, PersistList, PersistMemory, PersistPolicy, PersistState, PersistStorage, PersistSwarm, Policy, Schema, SharedState, SharedStorage, State, Storage, Utils, addAgent, addCompletion, addEmbedding, addPolicy, addState, addStorage, addSwarm, addTool, beginContext, cancelOutput, cancelOutputForce, changeToAgent, changeToDefaultAgent, changeToPrevAgent, commitAssistantMessage, commitAssistantMessageForce, commitFlush, commitFlushForce, commitStopTools, commitStopToolsForce, commitSystemMessage, commitSystemMessageForce, commitToolOutput, commitToolOutputForce, commitUserMessage, commitUserMessageForce, complete, disposeConnection, dumpAgent, dumpClientPerformance, dumpDocs, dumpPerfomance, dumpSwarm, emit, emitForce, event, execute, executeForce, getAgentHistory, getAgentName, getAssistantHistory, getLastAssistantMessage, getLastSystemMessage, getLastUserMessage, getPayload, getRawHistory, getSessionContext, getSessionMode, getUserHistory, listenAgentEvent, listenAgentEventOnce, listenEvent, listenEventOnce, listenExecutionEvent, listenExecutionEventOnce, listenHistoryEvent, listenHistoryEventOnce, listenPolicyEvent, listenPolicyEventOnce, listenSessionEvent, listenSessionEventOnce, listenStateEvent, listenStateEventOnce, listenStorageEvent, listenStorageEventOnce, listenSwarmEvent, listenSwarmEventOnce, makeAutoDispose, makeConnection, markOffline, markOnline, runStateless, runStatelessForce, session, setConfig, swarm };

package/package.json

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

package/types.d.ts

@@ -664,6 +664,8 @@ interface IPolicy {
  * Defines how policies enforce rules and manage bans within the swarm.
  */
 interface IPolicySchema {
+    /** Optional flag to enable serialization of banned clients to persistent storage (e.g., hard drive). */
+    persist?: boolean;
     /** Optional description for documentation purposes, aiding in policy usage understanding. */
     docDescription?: string;
     /** The unique name of the policy within the swarm. */
@@ -687,7 +689,7 @@ interface IPolicySchema {
      * @param {SwarmName} swarmName - The unique name of the swarm.
      * @returns {SessionId[] | Promise<SessionId[]>} An array of banned session IDs, synchronously or asynchronously.
      */
-    getBannedClients: (policyName: PolicyName, swarmName: SwarmName) => SessionId[] | Promise<SessionId[]>;
+    getBannedClients?: (policyName: PolicyName, swarmName: SwarmName) => SessionId[] | Promise<SessionId[]>;
     /**
      * Optional function to set the list of banned clients.
      * Overrides default ban list management if provided.
@@ -1234,7 +1236,7 @@ interface ISession {
      * @returns {Promise<void>} A promise that resolves when the message is committed.
      * @throws {Error} If committing the message fails.
      */
-    commitUserMessage: (message: string) => Promise<void>;
+    commitUserMessage: (message: string, mode: ExecutionMode) => Promise<void>;
     /**
      * Commits a flush operation to clear the session's agent history.
      * Resets the history to an initial state.
@@ -2283,6 +2285,77 @@ declare class PersistAliveUtils implements IPersistAliveControl {
  * @type {IPersistAliveControl}
  */
 declare const PersistAlive: IPersistAliveControl;
+/**
+ * Defines the structure for policy data persistence in the swarm system.
+ * Tracks banned clients (`SessionId`) within a `SwarmName` under a specific policy.
+ * @interface IPersistPolicyData
+ */
+interface IPersistPolicyData {
+    /** Array of session IDs that are banned under this policy */
+    bannedClients: SessionId[];
+}
+/**
+ * Defines control methods for customizing policy persistence operations.
+ * Allows injection of a custom persistence adapter for policy data tied to `SwarmName`.
+ * @interface IPersistPolicyControl
+ */
+interface IPersistPolicyControl {
+    /**
+     * Sets a custom persistence adapter for policy data storage.
+     * Overrides the default `PersistBase` implementation for specialized behavior (e.g., in-memory tracking for `SwarmName`).
+     * @param {TPersistBaseCtor<SwarmName, IPersistPolicyData>} Ctor - The constructor for the policy data persistence adapter.
+     */
+    usePersistPolicyAdapter(Ctor: TPersistBaseCtor<SwarmName, IPersistPolicyData>): void;
+}
+/**
+ * Utility class for managing policy data persistence in the swarm system.
+ * Provides methods to get and set banned clients within a `SwarmName`, with a customizable adapter.
+ * @implements {IPersistPolicyControl}
+ */
+declare class PersistPolicyUtils implements IPersistPolicyControl {
+    /** @private Default constructor for policy data persistence, defaults to `PersistBase` */
+    private PersistPolicyFactory;
+    /**
+     * Memoized function to create or retrieve storage for a specific policy data.
+     * Ensures a single persistence instance per swarm, optimizing resource use.
+     * @private
+     * @param swarmName - The identifier of the swarm.
+     * @returns A persistence instance for the policy data, rooted at `./logs/data/policy/`.
+     */
+    private getPolicyStorage;
+    /**
+     * Configures a custom constructor for policy data persistence, overriding the default `PersistBase`.
+     * Enables advanced tracking (e.g., in-memory or database-backed persistence).
+     * @param Ctor - The constructor to use for policy data storage, implementing `IPersistBase`.
+     */
+    usePersistPolicyAdapter(Ctor: TPersistBaseCtor<SwarmName, IPersistPolicyData>): void;
+    /**
+     * Retrieves the list of banned clients for a specific policy, defaulting to an empty array if unset.
+     * Used to check client ban status in swarm workflows.
+     * @param policyName - The identifier of the policy to check.
+     * @param swarmName - The identifier of the swarm.
+     * @param defaultValue - Optional default value if no banned clients are found.
+     * @returns A promise resolving to an array of banned client session IDs.
+     * @throws {Error} If reading from storage fails (e.g., file corruption).
+     */
+    getBannedClients: (policyName: PolicyName, swarmName: SwarmName, defaultValue?: SessionId[]) => Promise<SessionId[]>;
+    /**
+     * Sets the list of banned clients for a specific policy, persisting the status for future retrieval.
+     * Used to manage client bans in swarm operations.
+     * @param bannedClients - Array of session IDs to be banned under this policy.
+     * @param policyName - The identifier of the policy to update.
+     * @param swarmName - The identifier of the swarm.
+     * @returns A promise that resolves when the banned clients list is persisted.
+     * @throws {Error} If writing to storage fails (e.g., permissions or disk space).
+     */
+    setBannedClients: (bannedClients: SessionId[], policyName: PolicyName, swarmName: SwarmName) => Promise<void>;
+}
+/**
+ * Exported singleton for policy persistence operations, cast as the control interface.
+ * Provides a global point of access for managing client bans in the swarm.
+ * @type {IPersistPolicyControl}
+ */
+declare const PersistPolicy: IPersistPolicyControl;
 
 /**
  * Callbacks for managing history instance lifecycle and message handling.
@@ -3036,7 +3109,7 @@ interface IAgent {
      * @returns {Promise<void>} A promise that resolves when the message is committed.
      * @throws {Error} If committing the message fails.
      */
-    commitUserMessage(message: string): Promise<void>;
+    commitUserMessage(message: string, mode: ExecutionMode): Promise<void>;
     /**
      * Commits an assistant message to the agent's history without triggering a response.
      * @param {string} message - The assistant message content to commit.
@@ -3294,7 +3367,7 @@ declare class ClientAgent implements IAgent {
      * @param {string} message - The user message to commit, trimmed before storage.
      * @returns {Promise<void>} Resolves when the message is committed to history and the event is emitted.
      */
-    commitUserMessage(message: string): Promise<void>;
+    commitUserMessage(message: string, mode: ExecutionMode): Promise<void>;
     /**
      * Commits a flush of the agent’s history, clearing it and notifying the system via BusService.
      * Useful for resetting agent state, coordinated with HistoryConnectionService.
@@ -3503,7 +3576,7 @@ declare class AgentConnectionService implements IAgent {
      * @param {string} message - The user message to commit.
      * @returns {Promise<any>} A promise resolving to the commit result, type determined by ClientAgent’s implementation.
      */
-    commitUserMessage: (message: string) => Promise<void>;
+    commitUserMessage: (message: string, mode: ExecutionMode) => Promise<void>;
     /**
      * Commits an agent change to prevent the next tool execution, altering the execution flow.
      * Delegates to ClientAgent.commitAgentChange, using context from MethodContextService, logging via LoggerService if GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO is true.
@@ -4175,7 +4248,7 @@ declare class ClientSession implements ISession {
      * @param {string} message - The user message to commit, typically from client input.
      * @returns {Promise<void>} Resolves when the message is committed and the event is logged.
      */
-    commitUserMessage(message: string): Promise<void>;
+    commitUserMessage(message: string, mode: ExecutionMode): Promise<void>;
     /**
      * Commits a flush of the agent’s history via the swarm’s agent (ClientAgent), clearing it and logging via BusService.
      * Useful for resetting session state, coordinated with ClientHistory via ClientAgent.
@@ -4346,7 +4419,7 @@ declare class SessionConnectionService implements ISession {
      * @param {string} message - The user message to commit.
      * @returns {Promise<void>} A promise resolving when the user message is committed.
      */
-    commitUserMessage: (message: string) => Promise<void>;
+    commitUserMessage: (message: string, mode: ExecutionMode) => Promise<void>;
     /**
      * Commits a flush of the session’s history, clearing stored data.
      * Delegates to ClientSession.commitFlush, using context from MethodContextService, logging via LoggerService if GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO is true.
@@ -4501,7 +4574,7 @@ declare class AgentPublicService implements TAgentConnectionService {
      * @param {AgentName} agentName - The agent name for identification.
      * @returns {Promise<unknown>} A promise resolving to the commit result.
      */
-    commitUserMessage: (message: string, methodName: string, clientId: string, agentName: AgentName) => Promise<void>;
+    commitUserMessage: (message: string, mode: ExecutionMode, methodName: string, clientId: string, agentName: AgentName) => Promise<void>;
     /**
      * Commits a flush of the agent’s history, clearing stored data.
      * Wraps AgentConnectionService.commitFlush with MethodContextService, logging via LoggerService if GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO is true.
@@ -4790,7 +4863,7 @@ declare class SessionPublicService implements TSessionConnectionService {
      * @param {SwarmName} swarmName - The swarm name for context.
      * @returns {Promise<void>} A promise resolving when the user message is committed.
      */
-    commitUserMessage: (message: string, methodName: string, clientId: string, swarmName: SwarmName) => Promise<void>;
+    commitUserMessage: (message: string, mode: ExecutionMode, methodName: string, clientId: string, swarmName: SwarmName) => Promise<void>;
     /**
      * Commits a flush of the session’s history, clearing stored data.
      * Wraps SessionConnectionService.commitFlush with MethodContextService, logging via LoggerService if GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO is true.
@@ -8255,7 +8328,7 @@ declare const commitFlush: (clientId: string, agentName: string) => Promise<void
  * @example
  * await commitUserMessage("User input message", "client-123", "AgentX");
  */
-declare const commitUserMessage: (content: string, clientId: string, agentName: string) => Promise<void>;
+declare const commitUserMessage: (content: string, mode: ExecutionMode, clientId: string, agentName: string) => Promise<void>;
 
 /**
  * Commits the output of a tool execution to the active agent in a swarm session without checking the active agent.
@@ -8321,7 +8394,7 @@ declare const commitFlushForce: (clientId: string) => Promise<void>;
  * @example
  * await commitUserMessageForce("User input message", "client-123");
  */
-declare const commitUserMessageForce: (content: string, clientId: string) => Promise<void>;
+declare const commitUserMessageForce: (content: string, mode: ExecutionMode, clientId: string) => Promise<void>;
 
 /**
  * Commits an assistant-generated message to the active agent in the swarm system.
@@ -9920,6 +9993,33 @@ interface IGlobalConfig {
      * });
      */
     CC_DEFAULT_STATE_GET: <T = any>(clientId: string, stateName: StateName, defaultState: T) => Promise<T>;
+    /**
+     * Default function to get banned clients for the policy
+     * @param {PolicyName} policyName - The policy identifier.
+     * @param {SwarmName} swarmName - The swarm identifier.
+     * @example
+     * setConfig({
+     *   CC_DEFAULT_POLICY_GET_BAN_CLIENTS: async () => []
+     * });
+     */
+    CC_DEFAULT_POLICY_GET_BAN_CLIENTS: (policyName: PolicyName, swarmName: SwarmName) => Promise<SessionId[]> | SessionId[];
+    /**
+     * Retrieves the list of currently banned clients under this policy.
+     * @param {PolicyName} policyName - The unique name of the policy.
+     * @param {SwarmName} swarmName - The unique name of the swarm.
+     * @returns {SessionId[] | Promise<SessionId[]>} An array of banned session IDs, synchronously or asynchronously.
+     */
+    CC_DEFAULT_POLICY_GET?: (policyName: PolicyName, swarmName: SwarmName) => SessionId[] | Promise<SessionId[]>;
+    /**
+     * Optional function to set the list of banned clients.
+     * Overrides default ban list management if provided.
+     * @param {SessionId[]} clientIds - An array of session IDs to ban.
+     * @param {PolicyName} policyName - The unique name of the policy.
+     * @param {SwarmName} swarmName - The unique name of the swarm.
+     * @returns {Promise<void> | void} A promise that resolves when the ban list is updated, or void if synchronous.
+     * @throws {Error} If updating the ban list fails (e.g., due to persistence issues).
+     */
+    CC_DEFAULT_POLICY_SET?: (clientIds: SessionId[], policyName: PolicyName, swarmName: SwarmName) => Promise<void> | void;
     /**
      * Default function to get storage data, used in `IStorage.take` for storage retrieval.
      * Returns `defaultValue` by default, allowing storage retrieval to be customized via `setConfig`, though not directly in `ClientAgent`.
@@ -10503,6 +10603,7 @@ declare const Utils: {
     PersistStorageUtils: typeof PersistStorageUtils;
     PersistMemoryUtils: typeof PersistMemoryUtils;
     PersistAliveUtils: typeof PersistAliveUtils;
+    PersistPolicyUtils: typeof PersistPolicyUtils;
 };
 
-export { Adapter, type EventSource, ExecutionContextService, History, HistoryMemoryInstance, HistoryPersistInstance, type IAgentSchema, type IAgentTool, type IBaseEvent, type IBusEvent, type IBusEventContext, type ICompletionArgs, type ICompletionSchema, type ICustomEvent, type IEmbeddingSchema, type IGlobalConfig, type IHistoryAdapter, type IHistoryControl, type IHistoryInstance, type IHistoryInstanceCallbacks, type IIncomingMessage, type ILoggerAdapter, type ILoggerInstance, type ILoggerInstanceCallbacks, type IMakeConnectionConfig, type IMakeDisposeParams, type IModelMessage, type IOutgoingMessage, type IPersistBase, type IPolicySchema, type ISessionConfig, type IStateSchema, type IStorageSchema, type ISwarmSchema, type ITool, type IToolCall, Logger, LoggerInstance, MethodContextService, PayloadContextService, PersistAlive, PersistBase, PersistList, PersistMemory, PersistState, PersistStorage, PersistSwarm, Policy, type ReceiveMessageFn, Schema, type SendMessageFn, SharedState, SharedStorage, State, Storage, type THistoryInstanceCtor, type THistoryMemoryInstance, type THistoryPersistInstance, type TLoggerInstance, type TPersistBase, type TPersistBaseCtor, type TPersistList, Utils, addAgent, addCompletion, addEmbedding, addPolicy, addState, addStorage, addSwarm, addTool, beginContext, cancelOutput, cancelOutputForce, changeToAgent, changeToDefaultAgent, changeToPrevAgent, commitAssistantMessage, commitAssistantMessageForce, commitFlush, commitFlushForce, commitStopTools, commitStopToolsForce, commitSystemMessage, commitSystemMessageForce, commitToolOutput, commitToolOutputForce, commitUserMessage, commitUserMessageForce, complete, disposeConnection, dumpAgent, dumpClientPerformance, dumpDocs, dumpPerfomance, dumpSwarm, emit, emitForce, event, execute, executeForce, getAgentHistory, getAgentName, getAssistantHistory, getLastAssistantMessage, getLastSystemMessage, getLastUserMessage, getPayload, getRawHistory, getSessionContext, getSessionMode, getUserHistory, listenAgentEvent, listenAgentEventOnce, listenEvent, listenEventOnce, listenExecutionEvent, listenExecutionEventOnce, listenHistoryEvent, listenHistoryEventOnce, listenPolicyEvent, listenPolicyEventOnce, listenSessionEvent, listenSessionEventOnce, listenStateEvent, listenStateEventOnce, listenStorageEvent, listenStorageEventOnce, listenSwarmEvent, listenSwarmEventOnce, makeAutoDispose, makeConnection, markOffline, markOnline, runStateless, runStatelessForce, session, setConfig, swarm };
+export { Adapter, type EventSource, ExecutionContextService, History, HistoryMemoryInstance, HistoryPersistInstance, type IAgentSchema, type IAgentTool, type IBaseEvent, type IBusEvent, type IBusEventContext, type ICompletionArgs, type ICompletionSchema, type ICustomEvent, type IEmbeddingSchema, type IGlobalConfig, type IHistoryAdapter, type IHistoryControl, type IHistoryInstance, type IHistoryInstanceCallbacks, type IIncomingMessage, type ILoggerAdapter, type ILoggerInstance, type ILoggerInstanceCallbacks, type IMakeConnectionConfig, type IMakeDisposeParams, type IModelMessage, type IOutgoingMessage, type IPersistBase, type IPolicySchema, type ISessionConfig, type IStateSchema, type IStorageSchema, type ISwarmSchema, type ITool, type IToolCall, Logger, LoggerInstance, MethodContextService, PayloadContextService, PersistAlive, PersistBase, PersistList, PersistMemory, PersistPolicy, PersistState, PersistStorage, PersistSwarm, Policy, type ReceiveMessageFn, Schema, type SendMessageFn, SharedState, SharedStorage, State, Storage, type THistoryInstanceCtor, type THistoryMemoryInstance, type THistoryPersistInstance, type TLoggerInstance, type TPersistBase, type TPersistBaseCtor, type TPersistList, Utils, addAgent, addCompletion, addEmbedding, addPolicy, addState, addStorage, addSwarm, addTool, beginContext, cancelOutput, cancelOutputForce, changeToAgent, changeToDefaultAgent, changeToPrevAgent, commitAssistantMessage, commitAssistantMessageForce, commitFlush, commitFlushForce, commitStopTools, commitStopToolsForce, commitSystemMessage, commitSystemMessageForce, commitToolOutput, commitToolOutputForce, commitUserMessage, commitUserMessageForce, complete, disposeConnection, dumpAgent, dumpClientPerformance, dumpDocs, dumpPerfomance, dumpSwarm, emit, emitForce, event, execute, executeForce, getAgentHistory, getAgentName, getAssistantHistory, getLastAssistantMessage, getLastSystemMessage, getLastUserMessage, getPayload, getRawHistory, getSessionContext, getSessionMode, getUserHistory, listenAgentEvent, listenAgentEventOnce, listenEvent, listenEventOnce, listenExecutionEvent, listenExecutionEventOnce, listenHistoryEvent, listenHistoryEventOnce, listenPolicyEvent, listenPolicyEventOnce, listenSessionEvent, listenSessionEventOnce, listenStateEvent, listenStateEventOnce, listenStorageEvent, listenStorageEventOnce, listenSwarmEvent, listenSwarmEventOnce, makeAutoDispose, makeConnection, markOffline, markOnline, runStateless, runStatelessForce, session, setConfig, swarm };