agent-swarm-kit 1.0.173 → 1.0.174

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,
@@ -11898,8 +11988,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 +12596,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,
             });
         });
@@ -17159,6 +17256,7 @@ const Utils = {
     PersistStorageUtils,
     PersistMemoryUtils,
     PersistAliveUtils,
+    PersistPolicyUtils,
 };
 
 exports.Adapter = Adapter;
@@ -17174,6 +17272,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,
@@ -11896,8 +11986,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 +12594,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,
             });
         });
@@ -17157,6 +17254,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.174",
   "description": "A TypeScript library for building orchestrated framework-agnostic multi-agent AI systems",
   "author": {
     "name": "Petr Tripolsky",

package/types.d.ts

@@ -1,6 +1,7 @@
 import * as di_scoped from 'di-scoped';
 import * as functools_kit from 'functools-kit';
 import { SortedArray, Subject } from 'functools-kit';
+import { PolicyName as PolicyName$1 } from 'src/interfaces/Policy.interface';
 
 /**
  * Interface defining the structure of execution context in the swarm system.
@@ -664,6 +665,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 +690,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.
@@ -2283,6 +2286,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$1, 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$1, 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.
@@ -9920,6 +9994,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 +10604,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 };