agent-swarm-kit 1.0.185 → 1.0.187

package/build/index.cjs

@@ -470,6 +470,13 @@ const PERSIST_STATE_UTILS_METHOD_NAME_USE_PERSIST_STATE_ADAPTER = "PersistStateU
 const PERSIST_STATE_UTILS_METHOD_NAME_SET_STATE = "PersistStateUtils.setState";
 /** @private Constant for logging the getState method in PersistStateUtils */
 const PERSIST_STATE_UTILS_METHOD_NAME_GET_STATE = "PersistStateUtils.getState";
+// Logging method names for PersistEmbeddingUtils
+/** @private Constant for logging the usePersistEmbeddingAdapter method in PersistEmbeddingUtils */
+const PERSIST_EMBEDDING_UTILS_METHOD_NAME_USE_PERSIST_EMBEDDING_ADAPTER = "PersistEmbeddingUtils.usePersistEmbeddingAdapter";
+/** @private Constant for logging the readEmbeddingCache method in PersistEmbeddingUtils */
+const PERSIST_EMBEDDING_UTILS_METHOD_NAME_READ_EMBEDDING_CACHE = "PersistEmbeddingUtils.readEmbeddingCache";
+/** @private Constant for logging the writeEmbeddingCache method in PersistEmbeddingUtils */
+const PERSIST_EMBEDDING_UTILS_METHOD_NAME_WRITE_EMBEDDING_CACHE = "PersistEmbeddingUtils.writeEmbeddingCache";
 // Logging method names for PersistMemoryUtils
 /** @private Constant for logging the usePersistMemoryAdapter method in PersistMemoryUtils */
 const PERSIST_MEMORY_UTILS_METHOD_NAME_USE_PERSIST_MEMORY_ADAPTER = "PersistMemoryUtils.usePersistMemoryAdapter";
@@ -1645,6 +1652,86 @@ const PersistPolicyAdapter = new PersistPolicyUtils();
  * @type {IPersistPolicyControl}
  */
 const PersistPolicy = PersistPolicyAdapter;
+/**
+ * Utility class for managing embedding data persistence in the swarm system.
+ * Provides methods to read and write embedding vectors with a customizable adapter.
+ * @implements {IPersistEmbeddingControl}
+ */
+class PersistEmbeddingUtils {
+    constructor() {
+        /** @private Default constructor for embedding data persistence, defaults to `PersistBase` */
+        this.PersistEmbeddingFactory = PersistBase;
+        /**
+         * Memoized function to create or retrieve storage for specific embedding data.
+         * Ensures a single persistence instance per embedding name, optimizing resource use.
+         * @private
+         * @param embeddingName - The identifier of the embedding type.
+         * @returns A persistence instance for the embedding data, rooted at `./logs/data/embedding/`.
+         */
+        this.getEmbeddingStorage = functoolsKit.memoize(([embeddingName]) => `${embeddingName}`, (embeddingName) => Reflect.construct(this.PersistEmbeddingFactory, [
+            embeddingName,
+            `./logs/data/embedding/`,
+        ]));
+        /**
+         * Retrieves the embedding vector for a specific string hash, returning null if not found.
+         * Used to check if a precomputed embedding exists in the cache.
+         * @param embeddingName - The identifier of the embedding type.
+         * @param stringHash - The hash of the string for which the embedding was generated.
+         * @returns A promise resolving to the embedding vector or null if not cached.
+         * @throws {Error} If reading from storage fails (e.g., file corruption).
+         */
+        this.readEmbeddingCache = async (embeddingName, stringHash) => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+                swarm$1.loggerService.log(PERSIST_EMBEDDING_UTILS_METHOD_NAME_READ_EMBEDDING_CACHE);
+            const isInitial = this.getEmbeddingStorage.has(embeddingName);
+            const stateStorage = this.getEmbeddingStorage(embeddingName);
+            await stateStorage.waitForInit(isInitial);
+            if (await stateStorage.hasValue(stringHash)) {
+                const { embeddings } = await stateStorage.readValue(stringHash);
+                return embeddings;
+            }
+            return null;
+        };
+        /**
+         * Stores an embedding vector for a specific string hash, persisting it for future retrieval.
+         * Used to cache computed embeddings to avoid redundant processing.
+         * @param embeddings - Array of numerical values representing the embedding vector.
+         * @param embeddingName - The identifier of the embedding type.
+         * @param stringHash - The hash of the string for which the embedding was generated.
+         * @returns A promise that resolves when the embedding vector is persisted.
+         * @throws {Error} If writing to storage fails (e.g., permissions or disk space).
+         */
+        this.writeEmbeddingCache = async (embeddings, embeddingName, stringHash) => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+                swarm$1.loggerService.log(PERSIST_EMBEDDING_UTILS_METHOD_NAME_WRITE_EMBEDDING_CACHE);
+            const isInitial = this.getEmbeddingStorage.has(embeddingName);
+            const stateStorage = this.getEmbeddingStorage(embeddingName);
+            await stateStorage.waitForInit(isInitial);
+            await stateStorage.writeValue(stringHash, { embeddings });
+        };
+    }
+    /**
+     * Configures a custom constructor for embedding data persistence, overriding the default `PersistBase`.
+     * Enables advanced tracking (e.g., in-memory or database-backed persistence).
+     * @param Ctor - The constructor to use for embedding data storage, implementing `IPersistBase`.
+     */
+    usePersistEmbeddingAdapter(Ctor) {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+            swarm$1.loggerService.log(PERSIST_EMBEDDING_UTILS_METHOD_NAME_USE_PERSIST_EMBEDDING_ADAPTER);
+        this.PersistEmbeddingFactory = Ctor;
+    }
+}
+/**
+ * Singleton instance of `PersistEmbeddingUtils` for managing embedding data persistence globally.
+ * @type {PersistEmbeddingUtils}
+ */
+const PersistEmbeddingAdapter = new PersistEmbeddingUtils();
+/**
+ * Exported singleton for embedding persistence operations, cast as the control interface.
+ * Provides a global point of access for managing embedding cache in the system.
+ * @type {IPersistEmbeddingControl}
+ */
+const PersistEmbedding = PersistEmbeddingAdapter;
 
 var _a$1, _b$1, _c, _d;
 /** @private Symbol for memoizing the waitForInit method in HistoryMemoryInstance */
@@ -2735,6 +2822,25 @@ const CC_PERSIST_ENABLED_BY_DEFAULT = true;
 const CC_PERSIST_MEMORY_STORAGE = true;
 const CC_AUTOBAN_ENABLED_BY_DEFAULT = false;
 const CC_SKIP_POSIX_RENAME = false;
+/**
+ * Retrieves the embedding vector for a specific string hash, returning null if not found.
+ * Used to check if a precomputed embedding exists in the cache.
+ * @param embeddingName - The identifier of the embedding type.
+ * @param stringHash - The hash of the string for which the embedding was generated.
+ * @returns A promise resolving to the embedding vector or null if not cached.
+ * @throws {Error} If reading from storage fails (e.g., file corruption).
+ */
+const CC_DEFAULT_READ_EMBEDDING_CACHE = (embeddingName, stringHash) => Promise.resolve(null);
+/**
+ * Stores an embedding vector for a specific string hash, persisting it for future retrieval.
+ * Used to cache computed embeddings to avoid redundant processing.
+ * @param embeddings - Array of numerical values representing the embedding vector.
+ * @param embeddingName - The identifier of the embedding type.
+ * @param stringHash - The hash of the string for which the embedding was generated.
+ * @returns A promise that resolves when the embedding vector is persisted.
+ * @throws {Error} If writing to storage fails (e.g., permissions or disk space).
+ */
+const CC_DEFAULT_WRITE_EMBEDDING_CACHE = (embeddings, embeddingName, stringHash) => Promise.resolve();
 const GLOBAL_CONFIG = {
     CC_TOOL_CALL_EXCEPTION_FLUSH_PROMPT,
     CC_TOOL_CALL_EXCEPTION_RECOMPLETE_PROMPT,
@@ -2778,6 +2884,8 @@ const GLOBAL_CONFIG = {
     CC_DEFAULT_STORAGE_SET,
     CC_SKIP_POSIX_RENAME,
     CC_PERSIST_MEMORY_STORAGE,
+    CC_DEFAULT_READ_EMBEDDING_CACHE,
+    CC_DEFAULT_WRITE_EMBEDDING_CACHE,
 };
 GLOBAL_CONFIG.CC_RESQUE_STRATEGY = "flush";
 const setConfig = (config) => {
@@ -8324,6 +8432,19 @@ class StorageSchemaService {
     }
 }
 
+/**
+ * Creates a SHA-256 hash of the provided string.
+ *
+ * @param {string} string - The input string to be hashed.
+ * @returns {string} A hexadecimal representation of the SHA-256 hash.
+ *
+ * @example
+ * // Returns "315f5bdb76d078c43b8ac0064e4a0164612b1fce77c869345bfc94c75894edd3"
+ * createSHA256Hash("Hello, world!");
+ */
+function createSHA256Hash(string) {
+    return crypto.createHash("sha256").update(string).digest("hex");
+}
 /**
  * Creates embeddings and an index for a given item, memoized by item ID in _createEmbedding.
  * Invokes the onCreate callback if provided, supporting EmbeddingSchemaService’s embedding generation.
@@ -8339,7 +8460,12 @@ const CREATE_EMBEDDING_FN = async (item, self) => {
             id: item.id,
         });
     const index = await self.params.createIndex(item);
-    const embeddings = await self.params.createEmbedding(index);
+    const hash = createSHA256Hash(index);
+    let embeddings = await self.params.readEmbeddingCache(self.params.embedding, hash);
+    if (!embeddings) {
+        embeddings = await self.params.createEmbedding(index, self.params.embedding);
+        await self.params.writeEmbeddingCache(embeddings, self.params.embedding, hash);
+    }
     if (self.params.onCreate) {
         self.params.onCreate(index, embeddings, self.params.clientId, self.params.embedding);
     }
@@ -8561,7 +8687,10 @@ class ClientStorage {
                 total,
             });
         const indexed = new functoolsKit.SortedArray();
-        const searchEmbeddings = await this.params.createEmbedding(search);
+        let searchEmbeddings = await this.params.readEmbeddingCache(this.params.embedding, createSHA256Hash(search));
+        if (!searchEmbeddings) {
+            searchEmbeddings = await this.params.createEmbedding(search, this.params.embedding);
+        }
         if (this.params.onCreate) {
             this.params.onCreate(search, searchEmbeddings, this.params.clientId, this.params.embedding);
         }
@@ -8803,11 +8932,17 @@ class StorageConnectionService {
                 this._sharedStorageSet.add(storageName);
                 return this.sharedStorageConnectionService.getStorage(storageName);
             }
-            const { calculateSimilarity, createEmbedding, callbacks: embedding, } = this.embeddingSchemaService.get(embeddingName);
+            const { persist: p = GLOBAL_CONFIG.CC_PERSIST_ENABLED_BY_DEFAULT, writeEmbeddingCache = p
+                ? PersistEmbeddingAdapter.writeEmbeddingCache
+                : GLOBAL_CONFIG.CC_DEFAULT_WRITE_EMBEDDING_CACHE, readEmbeddingCache = p
+                ? PersistEmbeddingAdapter.readEmbeddingCache
+                : GLOBAL_CONFIG.CC_DEFAULT_READ_EMBEDDING_CACHE, calculateSimilarity, createEmbedding, callbacks: embedding, } = this.embeddingSchemaService.get(embeddingName);
             return new ClientStorage({
                 clientId,
                 storageName,
                 embedding: embeddingName,
+                writeEmbeddingCache,
+                readEmbeddingCache,
                 calculateSimilarity,
                 createEmbedding,
                 createIndex,
@@ -10997,11 +11132,17 @@ class SharedStorageConnectionService {
             if (!shared) {
                 throw new Error(`agent-swarm storage not shared storageName=${storageName}`);
             }
-            const { calculateSimilarity, createEmbedding, callbacks: embedding, } = this.embeddingSchemaService.get(embeddingName);
+            const { persist: p = GLOBAL_CONFIG.CC_PERSIST_ENABLED_BY_DEFAULT, writeEmbeddingCache = p
+                ? PersistEmbeddingAdapter.writeEmbeddingCache
+                : GLOBAL_CONFIG.CC_DEFAULT_WRITE_EMBEDDING_CACHE, readEmbeddingCache = p
+                ? PersistEmbeddingAdapter.readEmbeddingCache
+                : GLOBAL_CONFIG.CC_DEFAULT_READ_EMBEDDING_CACHE, calculateSimilarity, createEmbedding, callbacks: embedding, } = this.embeddingSchemaService.get(embeddingName);
             return new ClientStorage({
                 clientId: "shared",
                 storageName,
                 embedding: embeddingName,
+                writeEmbeddingCache,
+                readEmbeddingCache,
                 calculateSimilarity,
                 createEmbedding,
                 createIndex,
@@ -14577,6 +14718,7 @@ const makeConnection = (connector, clientId, swarmName) => {
     const online = functoolsKit.singlerun(async () => {
         await markOnline(clientId, swarmName);
     });
+    online();
     return beginContext(async (content, payload = null) => {
         await online();
         if (payload) {
@@ -14611,6 +14753,7 @@ makeConnection.scheduled = (connector, clientId, swarmName, { delay = SCHEDULED_
     const online = functoolsKit.singlerun(async () => {
         await markOnline(clientId, swarmName);
     });
+    online();
     const wrappedSend = functoolsKit.schedule(beginContext(async (content, payload) => {
         if (!swarm$1.sessionValidationService.hasSession(clientId)) {
             return;
@@ -14668,6 +14811,7 @@ makeConnection.rate = (connector, clientId, swarmName, { delay = RATE_DELAY } =
     const online = functoolsKit.singlerun(async () => {
         await markOnline(clientId, swarmName);
     });
+    online();
     const wrappedSend = functoolsKit.rate(beginContext(async (content, payload) => {
         if (!swarm$1.sessionValidationService.hasSession(clientId)) {
             return;
@@ -14894,6 +15038,7 @@ const session = (clientId, swarmName, { onDispose } = {}) => {
     const online = functoolsKit.singlerun(async () => {
         await markOnline(clientId, swarmName);
     });
+    online();
     return {
         complete: beginContext(async (content, payload = null) => {
             if (!isMounted) {
@@ -14941,6 +15086,7 @@ session.scheduled = (clientId, swarmName, { delay = SCHEDULED_DELAY, onDispose }
     const online = functoolsKit.singlerun(async () => {
         await markOnline(clientId, swarmName);
     });
+    online();
     const wrappedComplete = functoolsKit.schedule(beginContext(async (content, payload) => {
         if (!isMounted) {
             return;
@@ -15008,6 +15154,7 @@ session.rate = (clientId, swarmName, { delay = SCHEDULED_DELAY, onDispose } = {}
     const online = functoolsKit.singlerun(async () => {
         await markOnline(clientId, swarmName);
     });
+    online();
     const wrappedComplete = functoolsKit.rate(beginContext(async (content, payload) => {
         if (!isMounted) {
             return;
@@ -17354,6 +17501,7 @@ const Utils = {
     PersistMemoryUtils,
     PersistAliveUtils,
     PersistPolicyUtils,
+    PersistEmbeddingUtils,
 };
 
 exports.Adapter = Adapter;
@@ -17367,6 +17515,7 @@ exports.MethodContextService = MethodContextService;
 exports.PayloadContextService = PayloadContextService;
 exports.PersistAlive = PersistAlive;
 exports.PersistBase = PersistBase;
+exports.PersistEmbedding = PersistEmbedding;
 exports.PersistList = PersistList;
 exports.PersistMemory = PersistMemory;
 exports.PersistPolicy = PersistPolicy;

package/build/index.mjs

@@ -4,7 +4,7 @@ import { trycatch, makeExtendable, singleshot, getErrorMessage, not, queued, mem
 import xml2js from 'xml2js';
 import fs, { access, mkdir } from 'fs/promises';
 import path, { join } from 'path';
-import crypto from 'crypto';
+import crypto, { createHash } from 'crypto';
 import os from 'os';
 import { AsyncResource } from 'async_hooks';
 import { omit } from 'lodash-es';
@@ -468,6 +468,13 @@ const PERSIST_STATE_UTILS_METHOD_NAME_USE_PERSIST_STATE_ADAPTER = "PersistStateU
 const PERSIST_STATE_UTILS_METHOD_NAME_SET_STATE = "PersistStateUtils.setState";
 /** @private Constant for logging the getState method in PersistStateUtils */
 const PERSIST_STATE_UTILS_METHOD_NAME_GET_STATE = "PersistStateUtils.getState";
+// Logging method names for PersistEmbeddingUtils
+/** @private Constant for logging the usePersistEmbeddingAdapter method in PersistEmbeddingUtils */
+const PERSIST_EMBEDDING_UTILS_METHOD_NAME_USE_PERSIST_EMBEDDING_ADAPTER = "PersistEmbeddingUtils.usePersistEmbeddingAdapter";
+/** @private Constant for logging the readEmbeddingCache method in PersistEmbeddingUtils */
+const PERSIST_EMBEDDING_UTILS_METHOD_NAME_READ_EMBEDDING_CACHE = "PersistEmbeddingUtils.readEmbeddingCache";
+/** @private Constant for logging the writeEmbeddingCache method in PersistEmbeddingUtils */
+const PERSIST_EMBEDDING_UTILS_METHOD_NAME_WRITE_EMBEDDING_CACHE = "PersistEmbeddingUtils.writeEmbeddingCache";
 // Logging method names for PersistMemoryUtils
 /** @private Constant for logging the usePersistMemoryAdapter method in PersistMemoryUtils */
 const PERSIST_MEMORY_UTILS_METHOD_NAME_USE_PERSIST_MEMORY_ADAPTER = "PersistMemoryUtils.usePersistMemoryAdapter";
@@ -1643,6 +1650,86 @@ const PersistPolicyAdapter = new PersistPolicyUtils();
  * @type {IPersistPolicyControl}
  */
 const PersistPolicy = PersistPolicyAdapter;
+/**
+ * Utility class for managing embedding data persistence in the swarm system.
+ * Provides methods to read and write embedding vectors with a customizable adapter.
+ * @implements {IPersistEmbeddingControl}
+ */
+class PersistEmbeddingUtils {
+    constructor() {
+        /** @private Default constructor for embedding data persistence, defaults to `PersistBase` */
+        this.PersistEmbeddingFactory = PersistBase;
+        /**
+         * Memoized function to create or retrieve storage for specific embedding data.
+         * Ensures a single persistence instance per embedding name, optimizing resource use.
+         * @private
+         * @param embeddingName - The identifier of the embedding type.
+         * @returns A persistence instance for the embedding data, rooted at `./logs/data/embedding/`.
+         */
+        this.getEmbeddingStorage = memoize(([embeddingName]) => `${embeddingName}`, (embeddingName) => Reflect.construct(this.PersistEmbeddingFactory, [
+            embeddingName,
+            `./logs/data/embedding/`,
+        ]));
+        /**
+         * Retrieves the embedding vector for a specific string hash, returning null if not found.
+         * Used to check if a precomputed embedding exists in the cache.
+         * @param embeddingName - The identifier of the embedding type.
+         * @param stringHash - The hash of the string for which the embedding was generated.
+         * @returns A promise resolving to the embedding vector or null if not cached.
+         * @throws {Error} If reading from storage fails (e.g., file corruption).
+         */
+        this.readEmbeddingCache = async (embeddingName, stringHash) => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+                swarm$1.loggerService.log(PERSIST_EMBEDDING_UTILS_METHOD_NAME_READ_EMBEDDING_CACHE);
+            const isInitial = this.getEmbeddingStorage.has(embeddingName);
+            const stateStorage = this.getEmbeddingStorage(embeddingName);
+            await stateStorage.waitForInit(isInitial);
+            if (await stateStorage.hasValue(stringHash)) {
+                const { embeddings } = await stateStorage.readValue(stringHash);
+                return embeddings;
+            }
+            return null;
+        };
+        /**
+         * Stores an embedding vector for a specific string hash, persisting it for future retrieval.
+         * Used to cache computed embeddings to avoid redundant processing.
+         * @param embeddings - Array of numerical values representing the embedding vector.
+         * @param embeddingName - The identifier of the embedding type.
+         * @param stringHash - The hash of the string for which the embedding was generated.
+         * @returns A promise that resolves when the embedding vector is persisted.
+         * @throws {Error} If writing to storage fails (e.g., permissions or disk space).
+         */
+        this.writeEmbeddingCache = async (embeddings, embeddingName, stringHash) => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+                swarm$1.loggerService.log(PERSIST_EMBEDDING_UTILS_METHOD_NAME_WRITE_EMBEDDING_CACHE);
+            const isInitial = this.getEmbeddingStorage.has(embeddingName);
+            const stateStorage = this.getEmbeddingStorage(embeddingName);
+            await stateStorage.waitForInit(isInitial);
+            await stateStorage.writeValue(stringHash, { embeddings });
+        };
+    }
+    /**
+     * Configures a custom constructor for embedding data persistence, overriding the default `PersistBase`.
+     * Enables advanced tracking (e.g., in-memory or database-backed persistence).
+     * @param Ctor - The constructor to use for embedding data storage, implementing `IPersistBase`.
+     */
+    usePersistEmbeddingAdapter(Ctor) {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+            swarm$1.loggerService.log(PERSIST_EMBEDDING_UTILS_METHOD_NAME_USE_PERSIST_EMBEDDING_ADAPTER);
+        this.PersistEmbeddingFactory = Ctor;
+    }
+}
+/**
+ * Singleton instance of `PersistEmbeddingUtils` for managing embedding data persistence globally.
+ * @type {PersistEmbeddingUtils}
+ */
+const PersistEmbeddingAdapter = new PersistEmbeddingUtils();
+/**
+ * Exported singleton for embedding persistence operations, cast as the control interface.
+ * Provides a global point of access for managing embedding cache in the system.
+ * @type {IPersistEmbeddingControl}
+ */
+const PersistEmbedding = PersistEmbeddingAdapter;
 
 var _a$1, _b$1, _c, _d;
 /** @private Symbol for memoizing the waitForInit method in HistoryMemoryInstance */
@@ -2733,6 +2820,25 @@ const CC_PERSIST_ENABLED_BY_DEFAULT = true;
 const CC_PERSIST_MEMORY_STORAGE = true;
 const CC_AUTOBAN_ENABLED_BY_DEFAULT = false;
 const CC_SKIP_POSIX_RENAME = false;
+/**
+ * Retrieves the embedding vector for a specific string hash, returning null if not found.
+ * Used to check if a precomputed embedding exists in the cache.
+ * @param embeddingName - The identifier of the embedding type.
+ * @param stringHash - The hash of the string for which the embedding was generated.
+ * @returns A promise resolving to the embedding vector or null if not cached.
+ * @throws {Error} If reading from storage fails (e.g., file corruption).
+ */
+const CC_DEFAULT_READ_EMBEDDING_CACHE = (embeddingName, stringHash) => Promise.resolve(null);
+/**
+ * Stores an embedding vector for a specific string hash, persisting it for future retrieval.
+ * Used to cache computed embeddings to avoid redundant processing.
+ * @param embeddings - Array of numerical values representing the embedding vector.
+ * @param embeddingName - The identifier of the embedding type.
+ * @param stringHash - The hash of the string for which the embedding was generated.
+ * @returns A promise that resolves when the embedding vector is persisted.
+ * @throws {Error} If writing to storage fails (e.g., permissions or disk space).
+ */
+const CC_DEFAULT_WRITE_EMBEDDING_CACHE = (embeddings, embeddingName, stringHash) => Promise.resolve();
 const GLOBAL_CONFIG = {
     CC_TOOL_CALL_EXCEPTION_FLUSH_PROMPT,
     CC_TOOL_CALL_EXCEPTION_RECOMPLETE_PROMPT,
@@ -2776,6 +2882,8 @@ const GLOBAL_CONFIG = {
     CC_DEFAULT_STORAGE_SET,
     CC_SKIP_POSIX_RENAME,
     CC_PERSIST_MEMORY_STORAGE,
+    CC_DEFAULT_READ_EMBEDDING_CACHE,
+    CC_DEFAULT_WRITE_EMBEDDING_CACHE,
 };
 GLOBAL_CONFIG.CC_RESQUE_STRATEGY = "flush";
 const setConfig = (config) => {
@@ -8322,6 +8430,19 @@ class StorageSchemaService {
     }
 }
 
+/**
+ * Creates a SHA-256 hash of the provided string.
+ *
+ * @param {string} string - The input string to be hashed.
+ * @returns {string} A hexadecimal representation of the SHA-256 hash.
+ *
+ * @example
+ * // Returns "315f5bdb76d078c43b8ac0064e4a0164612b1fce77c869345bfc94c75894edd3"
+ * createSHA256Hash("Hello, world!");
+ */
+function createSHA256Hash(string) {
+    return createHash("sha256").update(string).digest("hex");
+}
 /**
  * Creates embeddings and an index for a given item, memoized by item ID in _createEmbedding.
  * Invokes the onCreate callback if provided, supporting EmbeddingSchemaService’s embedding generation.
@@ -8337,7 +8458,12 @@ const CREATE_EMBEDDING_FN = async (item, self) => {
             id: item.id,
         });
     const index = await self.params.createIndex(item);
-    const embeddings = await self.params.createEmbedding(index);
+    const hash = createSHA256Hash(index);
+    let embeddings = await self.params.readEmbeddingCache(self.params.embedding, hash);
+    if (!embeddings) {
+        embeddings = await self.params.createEmbedding(index, self.params.embedding);
+        await self.params.writeEmbeddingCache(embeddings, self.params.embedding, hash);
+    }
     if (self.params.onCreate) {
         self.params.onCreate(index, embeddings, self.params.clientId, self.params.embedding);
     }
@@ -8559,7 +8685,10 @@ class ClientStorage {
                 total,
             });
         const indexed = new SortedArray();
-        const searchEmbeddings = await this.params.createEmbedding(search);
+        let searchEmbeddings = await this.params.readEmbeddingCache(this.params.embedding, createSHA256Hash(search));
+        if (!searchEmbeddings) {
+            searchEmbeddings = await this.params.createEmbedding(search, this.params.embedding);
+        }
         if (this.params.onCreate) {
             this.params.onCreate(search, searchEmbeddings, this.params.clientId, this.params.embedding);
         }
@@ -8801,11 +8930,17 @@ class StorageConnectionService {
                 this._sharedStorageSet.add(storageName);
                 return this.sharedStorageConnectionService.getStorage(storageName);
             }
-            const { calculateSimilarity, createEmbedding, callbacks: embedding, } = this.embeddingSchemaService.get(embeddingName);
+            const { persist: p = GLOBAL_CONFIG.CC_PERSIST_ENABLED_BY_DEFAULT, writeEmbeddingCache = p
+                ? PersistEmbeddingAdapter.writeEmbeddingCache
+                : GLOBAL_CONFIG.CC_DEFAULT_WRITE_EMBEDDING_CACHE, readEmbeddingCache = p
+                ? PersistEmbeddingAdapter.readEmbeddingCache
+                : GLOBAL_CONFIG.CC_DEFAULT_READ_EMBEDDING_CACHE, calculateSimilarity, createEmbedding, callbacks: embedding, } = this.embeddingSchemaService.get(embeddingName);
             return new ClientStorage({
                 clientId,
                 storageName,
                 embedding: embeddingName,
+                writeEmbeddingCache,
+                readEmbeddingCache,
                 calculateSimilarity,
                 createEmbedding,
                 createIndex,
@@ -10995,11 +11130,17 @@ class SharedStorageConnectionService {
             if (!shared) {
                 throw new Error(`agent-swarm storage not shared storageName=${storageName}`);
             }
-            const { calculateSimilarity, createEmbedding, callbacks: embedding, } = this.embeddingSchemaService.get(embeddingName);
+            const { persist: p = GLOBAL_CONFIG.CC_PERSIST_ENABLED_BY_DEFAULT, writeEmbeddingCache = p
+                ? PersistEmbeddingAdapter.writeEmbeddingCache
+                : GLOBAL_CONFIG.CC_DEFAULT_WRITE_EMBEDDING_CACHE, readEmbeddingCache = p
+                ? PersistEmbeddingAdapter.readEmbeddingCache
+                : GLOBAL_CONFIG.CC_DEFAULT_READ_EMBEDDING_CACHE, calculateSimilarity, createEmbedding, callbacks: embedding, } = this.embeddingSchemaService.get(embeddingName);
             return new ClientStorage({
                 clientId: "shared",
                 storageName,
                 embedding: embeddingName,
+                writeEmbeddingCache,
+                readEmbeddingCache,
                 calculateSimilarity,
                 createEmbedding,
                 createIndex,
@@ -14575,6 +14716,7 @@ const makeConnection = (connector, clientId, swarmName) => {
     const online = singlerun(async () => {
         await markOnline(clientId, swarmName);
     });
+    online();
     return beginContext(async (content, payload = null) => {
         await online();
         if (payload) {
@@ -14609,6 +14751,7 @@ makeConnection.scheduled = (connector, clientId, swarmName, { delay = SCHEDULED_
     const online = singlerun(async () => {
         await markOnline(clientId, swarmName);
     });
+    online();
     const wrappedSend = schedule(beginContext(async (content, payload) => {
         if (!swarm$1.sessionValidationService.hasSession(clientId)) {
             return;
@@ -14666,6 +14809,7 @@ makeConnection.rate = (connector, clientId, swarmName, { delay = RATE_DELAY } =
     const online = singlerun(async () => {
         await markOnline(clientId, swarmName);
     });
+    online();
     const wrappedSend = rate(beginContext(async (content, payload) => {
         if (!swarm$1.sessionValidationService.hasSession(clientId)) {
             return;
@@ -14892,6 +15036,7 @@ const session = (clientId, swarmName, { onDispose } = {}) => {
     const online = singlerun(async () => {
         await markOnline(clientId, swarmName);
     });
+    online();
     return {
         complete: beginContext(async (content, payload = null) => {
             if (!isMounted) {
@@ -14939,6 +15084,7 @@ session.scheduled = (clientId, swarmName, { delay = SCHEDULED_DELAY, onDispose }
     const online = singlerun(async () => {
         await markOnline(clientId, swarmName);
     });
+    online();
     const wrappedComplete = schedule(beginContext(async (content, payload) => {
         if (!isMounted) {
             return;
@@ -15006,6 +15152,7 @@ session.rate = (clientId, swarmName, { delay = SCHEDULED_DELAY, onDispose } = {}
     const online = singlerun(async () => {
         await markOnline(clientId, swarmName);
     });
+    online();
     const wrappedComplete = rate(beginContext(async (content, payload) => {
         if (!isMounted) {
             return;
@@ -17352,6 +17499,7 @@ const Utils = {
     PersistMemoryUtils,
     PersistAliveUtils,
     PersistPolicyUtils,
+    PersistEmbeddingUtils,
 };
 
-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 };
+export { Adapter, ExecutionContextService, History, HistoryMemoryInstance, HistoryPersistInstance, Logger, LoggerInstance, MethodContextService, PayloadContextService, PersistAlive, PersistBase, PersistEmbedding, 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.185",
+  "version": "1.0.187",
   "description": "A TypeScript library for building orchestrated framework-agnostic multi-agent AI systems",
   "author": {
     "name": "Petr Tripolsky",

package/types.d.ts

@@ -183,6 +183,8 @@ interface IEmbeddingCallbacks {
  * Defines how embeddings are created and compared within the swarm.
  */
 interface IEmbeddingSchema {
+    /** Optional flag to enable serialization of navigation stack and active agent state to persistent storage (e.g., hard drive). */
+    persist?: boolean;
     /** The unique name of the embedding mechanism within the swarm. */
     embeddingName: EmbeddingName;
     /**
@@ -192,7 +194,7 @@ interface IEmbeddingSchema {
      * @returns {Promise<Embeddings>} A promise resolving to the generated embedding as an array of numbers.
      * @throws {Error} If embedding creation fails (e.g., due to invalid text or model errors).
      */
-    createEmbedding(text: string): Promise<Embeddings>;
+    createEmbedding(text: string, embeddingName: EmbeddingName): Promise<Embeddings>;
     /**
      * Calculates the similarity between two embeddings.
      * Commonly used for search or ranking operations (e.g., cosine similarity).
@@ -202,6 +204,25 @@ interface IEmbeddingSchema {
      * @throws {Error} If similarity calculation fails (e.g., due to invalid embeddings or computation errors).
      */
     calculateSimilarity(a: Embeddings, b: Embeddings): Promise<number>;
+    /**
+     * Stores an embedding vector for a specific string hash, persisting it for future retrieval.
+     * Used to cache computed embeddings to avoid redundant processing.
+     * @param embeddings - Array of numerical values representing the embedding vector.
+     * @param embeddingName - The identifier of the embedding type.
+     * @param stringHash - The hash of the string for which the embedding was generated.
+     * @returns A promise that resolves when the embedding vector is persisted.
+     * @throws {Error} If writing to storage fails (e.g., permissions or disk space).
+     */
+    writeEmbeddingCache?: (embeddings: number[], embeddingName: EmbeddingName, stringHash: string) => Promise<void> | void;
+    /**
+     * Retrieves the embedding vector for a specific string hash, returning null if not found.
+     * Used to check if a precomputed embedding exists in the cache.
+     * @param embeddingName - The identifier of the embedding type.
+     * @param stringHash - The hash of the string for which the embedding was generated.
+     * @returns A promise resolving to the embedding vector or null if not cached.
+     * @throws {Error} If reading from storage fails (e.g., file corruption).
+     */
+    readEmbeddingCache?: (embeddingName: EmbeddingName, stringHash: string) => Promise<number[] | null> | number[] | null;
     /** Optional partial set of callbacks for embedding events, allowing customization of creation and comparison. */
     callbacks?: Partial<IEmbeddingCallbacks>;
 }
@@ -325,6 +346,25 @@ interface IStorageParams<T extends IStorageData = IStorageData> extends IStorage
      * Used for search operations.
      */
     calculateSimilarity: IEmbeddingSchema["calculateSimilarity"];
+    /**
+     * Stores an embedding vector for a specific string hash, persisting it for future retrieval.
+     * Used to cache computed embeddings to avoid redundant processing.
+     * @param embeddings - Array of numerical values representing the embedding vector.
+     * @param embeddingName - The identifier of the embedding type.
+     * @param stringHash - The hash of the string for which the embedding was generated.
+     * @returns A promise that resolves when the embedding vector is persisted.
+     * @throws {Error} If writing to storage fails (e.g., permissions or disk space).
+     */
+    writeEmbeddingCache: IEmbeddingSchema["writeEmbeddingCache"];
+    /**
+     * Retrieves the embedding vector for a specific string hash, returning null if not found.
+     * Used to check if a precomputed embedding exists in the cache.
+     * @param embeddingName - The identifier of the embedding type.
+     * @param stringHash - The hash of the string for which the embedding was generated.
+     * @returns A promise resolving to the embedding vector or null if not cached.
+     * @throws {Error} If reading from storage fails (e.g., file corruption).
+     */
+    readEmbeddingCache: IEmbeddingSchema["readEmbeddingCache"];
     /**
      * Function to create an embedding for storage items, inherited from the embedding schema.
      * Used for indexing.
@@ -2363,6 +2403,76 @@ declare class PersistPolicyUtils implements IPersistPolicyControl {
  * @type {IPersistPolicyControl}
  */
 declare const PersistPolicy: IPersistPolicyControl;
+/**
+ * Defines the structure for embedding data persistence in the swarm system.
+ * Stores numerical embeddings for a `stringHash` within an `EmbeddingName`.
+ * @interface IPersistEmbeddingData
+ */
+interface IPersistEmbeddingData {
+    /** Array of numerical values representing the embedding vector */
+    embeddings: number[];
+}
+/**
+ * Defines control methods for customizing embedding persistence operations.
+ * Allows injection of a custom persistence adapter for embedding data tied to `EmbeddingName`.
+ * @interface IPersistEmbeddingControl
+ */
+interface IPersistEmbeddingControl {
+    /**
+     * Sets a custom persistence adapter for embedding data storage.
+     * Overrides the default `PersistBase` implementation for specialized behavior (e.g., in-memory tracking for `SwarmName`).
+     * @param {TPersistBaseCtor<SwarmName, IPersistEmbeddingData>} Ctor - The constructor for the embedding data persistence adapter.
+     */
+    usePersistEmbeddingAdapter(Ctor: TPersistBaseCtor<SwarmName, IPersistEmbeddingData>): void;
+}
+/**
+ * Utility class for managing embedding data persistence in the swarm system.
+ * Provides methods to read and write embedding vectors with a customizable adapter.
+ * @implements {IPersistEmbeddingControl}
+ */
+declare class PersistEmbeddingUtils implements IPersistEmbeddingControl {
+    /** @private Default constructor for embedding data persistence, defaults to `PersistBase` */
+    private PersistEmbeddingFactory;
+    /**
+     * Memoized function to create or retrieve storage for specific embedding data.
+     * Ensures a single persistence instance per embedding name, optimizing resource use.
+     * @private
+     * @param embeddingName - The identifier of the embedding type.
+     * @returns A persistence instance for the embedding data, rooted at `./logs/data/embedding/`.
+     */
+    private getEmbeddingStorage;
+    /**
+     * Configures a custom constructor for embedding data persistence, overriding the default `PersistBase`.
+     * Enables advanced tracking (e.g., in-memory or database-backed persistence).
+     * @param Ctor - The constructor to use for embedding data storage, implementing `IPersistBase`.
+     */
+    usePersistEmbeddingAdapter(Ctor: TPersistBaseCtor<SwarmName, IPersistEmbeddingData>): void;
+    /**
+     * Retrieves the embedding vector for a specific string hash, returning null if not found.
+     * Used to check if a precomputed embedding exists in the cache.
+     * @param embeddingName - The identifier of the embedding type.
+     * @param stringHash - The hash of the string for which the embedding was generated.
+     * @returns A promise resolving to the embedding vector or null if not cached.
+     * @throws {Error} If reading from storage fails (e.g., file corruption).
+     */
+    readEmbeddingCache: (embeddingName: EmbeddingName, stringHash: string) => Promise<number[] | null>;
+    /**
+     * Stores an embedding vector for a specific string hash, persisting it for future retrieval.
+     * Used to cache computed embeddings to avoid redundant processing.
+     * @param embeddings - Array of numerical values representing the embedding vector.
+     * @param embeddingName - The identifier of the embedding type.
+     * @param stringHash - The hash of the string for which the embedding was generated.
+     * @returns A promise that resolves when the embedding vector is persisted.
+     * @throws {Error} If writing to storage fails (e.g., permissions or disk space).
+     */
+    writeEmbeddingCache: (embeddings: number[], embeddingName: EmbeddingName, stringHash: string) => Promise<void>;
+}
+/**
+ * Exported singleton for embedding persistence operations, cast as the control interface.
+ * Provides a global point of access for managing embedding cache in the system.
+ * @type {IPersistEmbeddingControl}
+ */
+declare const PersistEmbedding: IPersistEmbeddingControl;
 
 /**
  * Callbacks for managing history instance lifecycle and message handling.
@@ -10100,6 +10210,25 @@ interface IGlobalConfig {
      * @type {boolean}
      */
     CC_PERSIST_MEMORY_STORAGE: boolean;
+    /**
+     * Retrieves the embedding vector for a specific string hash, returning null if not found.
+     * Used to check if a precomputed embedding exists in the cache.
+     * @param embeddingName - The identifier of the embedding type.
+     * @param stringHash - The hash of the string for which the embedding was generated.
+     * @returns A promise resolving to the embedding vector or null if not cached.
+     * @throws {Error} If reading from storage fails (e.g., file corruption).
+     */
+    CC_DEFAULT_READ_EMBEDDING_CACHE: (embeddingName: EmbeddingName, stringHash: string) => Promise<number[] | null> | number[] | null;
+    /**
+     * Stores an embedding vector for a specific string hash, persisting it for future retrieval.
+     * Used to cache computed embeddings to avoid redundant processing.
+     * @param embeddings - Array of numerical values representing the embedding vector.
+     * @param embeddingName - The identifier of the embedding type.
+     * @param stringHash - The hash of the string for which the embedding was generated.
+     * @returns A promise that resolves when the embedding vector is persisted.
+     * @throws {Error} If writing to storage fails (e.g., permissions or disk space).
+     */
+    CC_DEFAULT_WRITE_EMBEDDING_CACHE: (embeddings: number[], embeddingName: EmbeddingName, stringHash: string) => Promise<void> | void;
 }
 
 declare const GLOBAL_CONFIG: IGlobalConfig;
@@ -10642,6 +10771,7 @@ declare const Utils: {
     PersistMemoryUtils: typeof PersistMemoryUtils;
     PersistAliveUtils: typeof PersistAliveUtils;
     PersistPolicyUtils: typeof PersistPolicyUtils;
+    PersistEmbeddingUtils: typeof PersistEmbeddingUtils;
 };
 
-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 IPersistActiveAgentData, type IPersistAliveData, type IPersistBase, type IPersistMemoryData, type IPersistNavigationStackData, type IPersistPolicyData, type IPersistStateData, type IPersistStorageData, type IPolicySchema, type ISessionConfig, type IStateSchema, type IStorageData, 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 };
+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 IPersistActiveAgentData, type IPersistAliveData, type IPersistBase, type IPersistEmbeddingData, type IPersistMemoryData, type IPersistNavigationStackData, type IPersistPolicyData, type IPersistStateData, type IPersistStorageData, type IPolicySchema, type ISessionConfig, type IStateSchema, type IStorageData, type IStorageSchema, type ISwarmSchema, type ITool, type IToolCall, Logger, LoggerInstance, MethodContextService, PayloadContextService, PersistAlive, PersistBase, PersistEmbedding, 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 };