agent-swarm-kit 1.0.69 → 1.0.71

package/types.d.ts

@@ -53,989 +53,1058 @@ interface ILogger {
     debug(...args: any[]): void;
 }
 
-interface ISwarmSessionCallbacks {
+/**
+ * Type representing an array of numbers as embeddings.
+ */
+type Embeddings = number[];
+/**
+ * Interface for embedding callbacks.
+ */
+interface IEmbeddingCallbacks {
     /**
-     * Callback triggered when a client connects.
-     * @param clientId - The ID of the client.
-     * @param swarmName - The name of the swarm.
+     * Callback for when an embedding is created.
+     * @param text - The text used to create the embedding.
+     * @param embeddings - The generated embeddings.
+     * @param clientId - The client ID associated with the embedding.
+     * @param embeddingName - The name of the embedding.
      */
-    onConnect?: (clientId: string, swarmName: SwarmName) => void;
+    onCreate(text: string, embeddings: Embeddings, clientId: string, embeddingName: EmbeddingName): void;
     /**
-     * Callback triggered when a command is executed.
-     * @param clientId - The ID of the client.
-     * @param swarmName - The name of the swarm.
-     * @param content - The content to execute.
-     * @param mode - The source of execution: tool or user.
+     * Callback for when embeddings are compared.
+     * @param text1 - The first text used in the comparison.
+     * @param text2 - The second text used in the comparison.
+     * @param similarity - The similarity score between the embeddings.
+     * @param clientId - The client ID associated with the comparison.
+     * @param embeddingName - The name of the embedding.
      */
-    onExecute?: (clientId: string, swarmName: SwarmName, content: string, mode: ExecutionMode) => void;
+    onCompare(text1: string, text2: string, similarity: number, clientId: string, embeddingName: EmbeddingName): void;
+}
+/**
+ * Interface representing the schema for embeddings.
+ */
+interface IEmbeddingSchema {
     /**
-     * Callback triggered when a message is emitted.
-     * @param clientId - The ID of the client.
-     * @param swarmName - The name of the swarm.
-     * @param message - The message to emit.
+     * The name of the embedding.
      */
-    onEmit?: (clientId: string, swarmName: SwarmName, message: string) => void;
+    embeddingName: EmbeddingName;
     /**
-     * Callback triggered when a session being connected
-     * @param clientId - The ID of the client.
-     * @param swarmName - The name of the swarm.
+     * Creates an embedding from the given text.
+     * @param text - The text to create the embedding from.
+     * @returns A promise that resolves to the generated embeddings.
      */
-    onInit?: (clientId: string, swarmName: SwarmName) => void;
+    createEmbedding(text: string): Promise<Embeddings>;
     /**
-     * Callback triggered when a session being disponnected
-     * @param clientId - The ID of the client.
-     * @param swarmName - The name of the swarm.
+     * Calculates the similarity between two embeddings.
+     * @param a - The first embedding.
+     * @param b - The second embedding.
+     * @returns A promise that resolves to the similarity score.
      */
-    onDispose?: (clientId: string, swarmName: SwarmName) => void;
-}
-/**
- * Lifecycle callbacks of initialized swarm
- */
-interface ISwarmCallbacks extends ISwarmSessionCallbacks {
-    /** Emit the callback on agent change */
-    onAgentChanged: (clientId: string, agentName: AgentName, swarmName: SwarmName) => Promise<void>;
+    calculateSimilarity(a: Embeddings, b: Embeddings): Promise<number>;
+    /**
+     * Optional callbacks for embedding events.
+     */
+    callbacks?: Partial<IEmbeddingCallbacks>;
 }
 /**
- * Parameters for initializing a swarm.
- * @interface
- * @extends {Omit<ISwarmSchema, 'agentList'>}
+ * Type representing the name of an embedding.
  */
-interface ISwarmParams extends Omit<ISwarmSchema, keyof {
-    agentList: never;
-    onAgentChanged: never;
-}>, ISwarmCallbacks {
-    /** Client identifier */
-    clientId: string;
-    /** Logger instance */
-    logger: ILogger;
-    /** Map of agent names to agent instances */
-    agentMap: Record<AgentName, IAgent>;
-}
+type EmbeddingName = string;
+
+type StorageId = string | number;
 /**
- * Schema for defining a swarm.
- * @interface
+ * Interface representing the data stored in the storage.
  */
-interface ISwarmSchema {
-    /** Default agent name */
-    defaultAgent: AgentName;
-    /** Name of the swarm */
-    swarmName: string;
-    /** List of agent names */
-    agentList: string[];
-    /** Lifecycle callbacks*/
-    callbacks?: Partial<ISwarmCallbacks>;
+interface IStorageData {
+    id: StorageId;
 }
 /**
- * Interface for a swarm.
- * @interface
+ * Interface representing the schema of the storage.
+ * @template T - Type of the storage data.
  */
-interface ISwarm {
+interface IStorageSchema<T extends IStorageData = IStorageData> {
     /**
-     * Waits for the output from the swarm.
-     * @returns {Promise<string>} The output from the swarm.
+     * All agents will share the same ClientStorage instance
      */
-    waitForOutput(): Promise<string>;
+    shared?: boolean;
     /**
-     * Gets the name of the agent.
-     * @returns {Promise<AgentName>} The name of the agent.
+     * Function to get data from the storage.
+     * @param clientId - The client ID.
+     * @param storageName - The name of the storage.
+     * @returns A promise that resolves to an array of storage data or an array of storage data.
      */
-    getAgentName(): Promise<AgentName>;
+    getData?: (clientId: string, storageName: StorageName) => Promise<T[]> | T[];
     /**
-     * Gets the agent instance.
-     * @returns {Promise<IAgent>} The agent instance.
+     * Function to create an index for an item.
+     * @param item - The item to index.
+     * @returns A promise that resolves to a string or a string.
      */
-    getAgent(): Promise<IAgent>;
+    createIndex(item: T): Promise<string> | string;
     /**
-     * Sets the reference to an agent.
-     * @param {AgentName} agentName - The name of the agent.
-     * @param {IAgent} agent - The agent instance.
-     * @returns {Promise<void>}
+     * The name of the embedding.
      */
-    setAgentRef(agentName: AgentName, agent: IAgent): Promise<void>;
+    embedding: EmbeddingName;
     /**
-     * Sets the name of the agent.
-     * @param {AgentName} agentName - The name of the agent.
-     * @returns {Promise<void>}
+     * The name of the storage.
      */
-    setAgentName(agentName: AgentName): Promise<void>;
-}
-/** Type alias for swarm name */
-type SwarmName = string;
-
-/**
- * Parameters required to create a session.
- * @interface
- */
-interface ISessionParams extends ISessionSchema, ISwarmSessionCallbacks {
-    clientId: string;
-    logger: ILogger;
-    swarm: ISwarm;
-    swarmName: SwarmName;
-}
-/**
- * Schema for session data.
- * @interface
- */
-interface ISessionSchema {
+    storageName: StorageName;
+    /**
+     * Optional callbacks for storage events.
+     */
+    callbacks?: Partial<IStorageCallbacks<T>>;
 }
 /**
- * Function type for sending messages.
- * @typedef {function} SendMessageFn
- * @param {IOutgoingMessage} outgoing - The outgoing message.
- * @returns {Promise<void> | void}
- */
-type SendMessageFn$1 = (outgoing: IOutgoingMessage) => Promise<void> | void;
-/**
- * Function type for receiving messages.
- * @typedef {function} ReceiveMessageFn
- * @param {IIncomingMessage} incoming - The incoming message.
- * @returns {Promise<void> | void}
- */
-type ReceiveMessageFn = (incoming: IIncomingMessage) => Promise<void> | void;
-/**
- * Interface for a session.
- * @interface
+ * Interface representing the callbacks for storage events.
+ * @template T - Type of the storage data.
  */
-interface ISession {
-    /**
-     * Emit a message.
-     * @param {string} message - The message to emit.
-     * @returns {Promise<void>}
-     */
-    emit(message: string): Promise<void>;
-    /**
-     * Execute a command.
-     * @param {string} content - The content to execute.
-     * @param {string} mode - The source of execution: tool or user
-     * @returns {Promise<string>}
-     */
-    execute(content: string, mode: ExecutionMode): Promise<string>;
-    /**
-     * Connect to a message sender.
-     * @param {SendMessageFn} connector - The function to send messages.
-     * @returns {ReceiveMessageFn}
-     */
-    connect(connector: SendMessageFn$1): ReceiveMessageFn;
+interface IStorageCallbacks<T extends IStorageData = IStorageData> {
     /**
-     * Commit tool output.
-     * @param {string} toolId - The `tool_call_id` for openai history
-     * @param {string} content - The content to commit.
-     * @returns {Promise<void>}
+     * Callback function for update events.
+     * @param items - The updated items.
+     * @param clientId - The client ID.
+     * @param storageName - The name of the storage.
      */
-    commitToolOutput(toolId: string, content: string): Promise<void>;
+    onUpdate: (items: T[], clientId: string, storageName: StorageName) => void;
     /**
-     * Commit user message without answer
-     * @param {string} message - The message to commit.
-     * @returns {Promise<void>}
+     * Callback function for search events.
+     * @param search - The search query.
+     * @param index - The sorted array of storage data.
+     * @param clientId - The client ID.
+     * @param storageName - The name of the storage.
      */
-    commitUserMessage: (message: string) => Promise<void>;
+    onSearch: (search: string, index: SortedArray<T>, clientId: string, storageName: StorageName) => void;
     /**
-     * Commit flush of agent history
-     * @returns {Promise<void>}
+     * Callback function for init
+     * @param clientId - The client ID.
+     * @param storageName - The name of the storage.
      */
-    commitFlush: () => Promise<void>;
+    onInit: (clientId: string, storageName: StorageName) => void;
     /**
-     * Commit a system message.
-     * @param {string} message - The message to commit.
-     * @returns {Promise<void>}
+     * Callback function for dispose
+     * @param clientId - The client ID.
+     * @param storageName - The name of the storage.
      */
-    commitSystemMessage(message: string): Promise<void>;
+    onDispose: (clientId: string, storageName: StorageName) => void;
 }
 /**
- * Type for session ID.
- * @typedef {string} SessionId
- */
-type SessionId = string;
-/**
- * Type for session mode.
- * @typedef {"session" | "makeConnection" | "complete"} SessionMode
- */
-type SessionMode = "session" | "makeConnection" | "complete";
-/**
- * Tools can emit user messages to trigger user friendly responses.
- * Should be ignored for `getUserHistory`
- * @typedef {"tool" | "user"} ExecutionMode
- */
-type ExecutionMode = "tool" | "user";
-
-/**
- * Represents a tool call with a function name and arguments.
+ * Interface representing the parameters for storage.
+ * @template T - Type of the storage data.
  */
-interface IToolCall {
+interface IStorageParams<T extends IStorageData = IStorageData> extends IStorageSchema<T>, Partial<IEmbeddingCallbacks> {
     /**
-     * The ID of the tool call.
+     * The client ID.
      */
-    id: string;
+    clientId: string;
     /**
-     * The type of the tool. Currently, only `function` is supported.
+     * Function to calculate similarity.
      */
-    type: 'function';
+    calculateSimilarity: IEmbeddingSchema["calculateSimilarity"];
     /**
-     * The function that the model called.
+     * Function to create an embedding.
      */
-    function: {
-        /**
-         * The name of the function to be called.
-         */
-        name: string;
-        /**
-         * The arguments to be passed to the function.
-         */
-        arguments: {
-            [key: string]: any;
-        };
-    };
-}
-/**
- * Represents a tool with a type and function details.
- */
-interface ITool {
+    createEmbedding: IEmbeddingSchema["createEmbedding"];
     /**
-     * The type of the tool.
+     * The name of the storage.
      */
-    type: string;
-    function: {
-        /**
-         * The name of the function.
-         */
-        name: string;
-        /**
-         * The description of the function.
-         */
-        description: string;
-        /**
-         * The parameters required by the function.
-         */
-        parameters: {
-            /**
-             * The type of the parameters.
-             */
-            type: string;
-            /**
-             * The list of required parameters.
-             */
-            required: string[];
-            /**
-             * The properties of the parameters.
-             */
-            properties: {
-                [key: string]: {
-                    /**
-                     * The type of the property.
-                     */
-                    type: string;
-                    /**
-                     * The description of the property.
-                     */
-                    description: string;
-                    /**
-                     * The possible values for the property.
-                     */
-                    enum?: string[];
-                };
-            };
-        };
-    };
+    storageName: StorageName;
+    /**
+     * Logger instance.
+     */
+    logger: ILogger;
+    /** The bus instance. */
+    bus: IBus;
 }
-
 /**
- * Interface representing a model message.
+ * Interface representing the storage.
+ * @template T - Type of the storage data.
  */
-interface IModelMessage {
+interface IStorage<T extends IStorageData = IStorageData> {
     /**
-     * The role of the message sender.
-     * @type {'assistant' | 'system' | 'tool' | 'user' | 'resque' | 'flush'}
+     * Function to take items from the storage.
+     * @param search - The search query.
+     * @param total - The total number of items to take.
+     * @param score - Optional score parameter.
+     * @returns A promise that resolves to an array of storage data.
      */
-    role: "assistant" | "system" | "tool" | "user" | "resque" | "flush";
+    take(search: string, total: number, score?: number): Promise<T[]>;
     /**
-     * The name of the agent sending the message.
-     * @type {string}
+     * Function to upsert an item in the storage.
+     * @param item - The item to upsert.
+     * @returns A promise that resolves when the operation is complete.
      */
-    agentName: string;
+    upsert(item: T): Promise<void>;
     /**
-     * The content of the message.
-     * @type {string}
+     * Function to remove an item from the storage.
+     * @param itemId - The ID of the item to remove.
+     * @returns A promise that resolves when the operation is complete.
      */
-    content: string;
+    remove(itemId: IStorageData["id"]): Promise<void>;
     /**
-     * The source of message: tool or user
-     * @type {ExecutionMode}
+     * Function to get an item from the storage.
+     * @param itemId - The ID of the item to get.
+     * @returns A promise that resolves to the item or null if not found.
      */
-    mode: ExecutionMode;
+    get(itemId: IStorageData["id"]): Promise<T | null>;
     /**
-     * Optional tool calls associated with the message.
-     * @type {Array<{ function: { name: string; arguments: { [key: string]: any; }; }; }>}
+     * Function to list items from the storage.
+     * @param filter - Optional filter function.
+     * @returns A promise that resolves to an array of storage data.
      */
-    tool_calls?: IToolCall[];
+    list(filter?: (item: T) => boolean): Promise<T[]>;
     /**
-     * Tool call that this message is responding to.
+     * Function to clear the storage.
+     * @returns A promise that resolves when the operation is complete.
      */
-    tool_call_id?: string;
+    clear(): Promise<void>;
 }
+/**
+ * Type representing the name of the storage.
+ */
+type StorageName = string;
 
+type IStateData = any;
 /**
- * Interface for History Adapter Callbacks
+ * Middleware function for state management.
+ * @template T - The type of the state data.
+ * @param {T} state - The current state.
+ * @param {string} clientId - The client ID.
+ * @param {StateName} stateName - The name of the state.
+ * @returns {Promise<T>} - The updated state.
  */
-interface IHistoryInstanceCallbacks {
+interface IStateMiddleware<T extends IStateData = IStateData> {
+    (state: T, clientId: string, stateName: StateName): Promise<T>;
+}
+/**
+ * Callbacks for state lifecycle events.
+ * @template T - The type of the state data.
+ */
+interface IStateCallbacks<T extends IStateData = IStateData> {
     /**
-     * Filter condition for history messages.
-     * @param message - The model message.
-     * @param clientId - The client ID.
-     * @param agentName - The agent name.
-     * @returns A promise that resolves to a boolean indicating whether the message passes the filter.
+     * Called when the state is initialized.
+     * @param {string} clientId - The client ID.
+     * @param {StateName} stateName - The name of the state.
      */
-    filterCondition?: (message: IModelMessage, clientId: string, agentName: AgentName) => Promise<boolean> | boolean;
+    onInit: (clientId: string, stateName: StateName) => void;
     /**
-     * Get data for the history.
-     * @param clientId - The client ID.
-     * @param agentName - The agent name.
-     * @returns A promise that resolves to an array of model messages.
+     * Called when the state is disposed.
+     * @param {string} clientId - The client ID.
+     * @param {StateName} stateName - The name of the state.
      */
-    getData: (clientId: string, agentName: AgentName) => Promise<IModelMessage[]> | IModelMessage[];
+    onDispose: (clientId: string, stateName: StateName) => void;
     /**
-     * Callback for when the history changes.
-     * @param data - The array of model messages.
-     * @param clientId - The client ID.
-     * @param agentName - The agent name.
+     * Called when the state is loaded.
+     * @param {T} state - The current state.
+     * @param {string} clientId - The client ID.
+     * @param {StateName} stateName - The name of the state.
      */
-    onChange: (data: IModelMessage[], clientId: string, agentName: AgentName) => void;
+    onLoad: (state: T, clientId: string, stateName: StateName) => void;
     /**
-     * Callback for when the history get the new message
-     * @param data - The array of model messages.
-     * @param clientId - The client ID.
-     * @param agentName - The agent name.
+     * Called when the state is read.
+     * @param {T} state - The current state.
+     * @param {string} clientId - The client ID.
+     * @param {StateName} stateName - The name of the state.
      */
-    onPush: (data: IModelMessage, clientId: string, agentName: AgentName) => void;
+    onRead: (state: T, clientId: string, stateName: StateName) => void;
     /**
-     * Callback for when the history is read. Will be called for each message
-     * @param message - The model message.
-     * @param clientId - The client ID.
-     * @param agentName - The agent name.
+     * Called when the state is written.
+     * @param {T} state - The current state.
+     * @param {string} clientId - The client ID.
+     * @param {StateName} stateName - The name of the state.
      */
-    onRead: (message: IModelMessage, clientId: string, agentName: AgentName) => void;
+    onWrite: (state: T, clientId: string, stateName: StateName) => void;
+}
+/**
+ * Schema for state management.
+ * @template T - The type of the state data.
+ */
+interface IStateSchema<T extends IStateData = IStateData> {
     /**
-     * Callback for when the read is begin
-     * @param clientId - The client ID.
-     * @param agentName - The agent name.
+     * The agents can share the state
+     */
+    shared?: boolean;
+    /**
+     * The name of the state.
      */
-    onReadBegin: (clientId: string, agentName: AgentName) => void;
+    stateName: StateName;
     /**
-     * Callback for when the read is end
-     * @param clientId - The client ID.
-     * @param agentName - The agent name.
+     * Gets the state.
+     * @param {string} clientId - The client ID.
+     * @param {StateName} stateName - The name of the state.
+     * @returns {T | Promise<T>} - The current state.
      */
-    onReadEnd: (clientId: string, agentName: AgentName) => void;
+    getState: (clientId: string, stateName: StateName) => T | Promise<T>;
     /**
-     * Callback for when the history is disposed.
-     * @param clientId - The client ID.
+     * Sets the state.
+     * @param {T} state - The new state.
+     * @param {string} clientId - The client ID.
+     * @param {StateName} stateName - The name of the state.
+     * @returns {Promise<void> | void} - A promise that resolves when the state is set.
      */
-    onDispose: (clientId: string) => void;
+    setState?: (state: T, clientId: string, stateName: StateName) => Promise<void> | void;
     /**
-     * Callback for when the history is initialized.
-     * @param clientId - The client ID.
+     * Middleware functions for state management.
      */
-    onInit: (clientId: string) => void;
+    middlewares?: IStateMiddleware<T>[];
     /**
-     * Callback to obtain history ref
-     * @param clientId - The client ID.
+     * Callbacks for state lifecycle events.
      */
-    onRef: (history: HistoryInstance) => void;
+    callbacks?: Partial<IStateCallbacks<T>>;
 }
 /**
- * Interface for History Adapter
+ * Parameters for state management.
+ * @template T - The type of the state data.
  */
-interface IHistoryAdapter {
-    /**
-     * Iterate over the history messages.
-     * @param clientId - The client ID.
-     * @param agentName - The agent name.
-     * @returns An async iterable iterator of model messages.
-     */
-    iterate(clientId: string, agentName: AgentName): AsyncIterableIterator<IModelMessage>;
+interface IStateParams<T extends IStateData = IStateData> extends IStateSchema<T> {
     /**
-     * Push a new message to the history.
-     * @param value - The model message to push.
-     * @param clientId - The client ID.
-     * @param agentName - The agent name.
-     * @returns A promise that resolves when the message is pushed.
+     * The client ID.
      */
-    push: (value: IModelMessage, clientId: string, agentName: AgentName) => Promise<void>;
+    clientId: string;
     /**
-     * Dispose of the history for a given client and agent.
-     * @param clientId - The client ID.
-     * @param agentName - The agent name or null.
-     * @returns A promise that resolves when the history is disposed.
+     * The logger instance.
      */
-    dispose: (clientId: string, agentName: AgentName | null) => Promise<void>;
+    logger: ILogger;
+    /** The bus instance. */
+    bus: IBus;
 }
 /**
- * Interface for History Control
+ * State management interface.
+ * @template T - The type of the state data.
  */
-interface IHistoryControl {
+interface IState<T extends IStateData = IStateData> {
     /**
-     * Use a custom history adapter.
-     * @param Ctor - The constructor for the history instance.
+     * Gets the state.
+     * @returns {Promise<T>} - The current state.
      */
-    useHistoryAdapter(Ctor: THistoryInstanceCtor): void;
+    getState: () => Promise<T>;
     /**
-     * Use history lifecycle callbacks.
-     * @param Callbacks - The callbacks dictionary.
+     * Sets the state.
+     * @param {(prevState: T) => Promise<T>} dispatchFn - The function to dispatch the new state.
+     * @returns {Promise<T>} - The updated state.
      */
-    useHistoryCallbacks: (Callbacks: Partial<IHistoryInstanceCallbacks>) => void;
+    setState: (dispatchFn: (prevState: T) => Promise<T>) => Promise<T>;
 }
 /**
- * Interface for History Instance
+ * The name of the state.
  */
-interface IHistoryInstance {
+type StateName = string;
+
+/**
+ * Interface representing the base context for an event.
+ */
+interface IBaseEventContext {
     /**
-     * Iterate over the history messages for a given agent.
-     * @param agentName - The agent name.
-     * @returns An async iterable iterator of model messages.
+     * The name of the agent.
      */
-    iterate(agentName: AgentName): AsyncIterableIterator<IModelMessage>;
+    agentName: AgentName;
     /**
-     * Wait for the history to initialize.
-     * @param agentName - The agent name.
-     * @param init - Whether the history is initializing.
-     * @returns A promise that resolves when the history is initialized.
+     * The name of the swarm.
      */
-    waitForInit(agentName: AgentName, init: boolean): Promise<void>;
+    swarmName: SwarmName;
     /**
-     * Push a new message to the history for a given agent.
-     * @param value - The model message to push.
-     * @param agentName - The agent name.
-     * @returns A promise that resolves when the message is pushed.
+     * The name of the storage.
      */
-    push(value: IModelMessage, agentName: AgentName): Promise<void>;
+    storageName: StorageName;
     /**
-     * Dispose of the history for a given agent.
-     * @param agentName - The agent name or null.
-     * @returns A promise that resolves when the history is disposed.
+     * The name of the state.
      */
-    dispose(agentName: AgentName | null): Promise<void>;
+    stateName: StateName;
 }
 /**
- * Type for History Instance Constructor
+ * Type representing the possible sources of an event.
  */
-type THistoryInstanceCtor = new (clientId: string, ...args: unknown[]) => IHistoryInstance;
+type EventSource = string;
 /**
- * Class representing a History Instance
+ * Interface representing the base structure of an event.
  */
-declare class HistoryInstance implements IHistoryInstance {
-    readonly clientId: string;
-    readonly callbacks: Partial<IHistoryInstanceCallbacks>;
-    private _array;
+interface IBaseEvent {
     /**
-     * Wait for the history to initialize.
-     * @param agentName - The agent name.
+     * The source of the event.
      */
-    waitForInit: ((agentName: AgentName) => Promise<void>) & functools_kit.ISingleshotClearable;
+    source: EventSource;
+}
+
+interface IBus {
+    emit<T extends IBaseEvent>(clientId: string, event: T): Promise<void>;
+}
+
+interface ISwarmSessionCallbacks {
     /**
-     * Create a HistoryInstance.
-     * @param clientId - The client ID.
-     * @param callbacks - The callbacks for the history instance.
+     * Callback triggered when a client connects.
+     * @param clientId - The ID of the client.
+     * @param swarmName - The name of the swarm.
      */
-    constructor(clientId: string, callbacks: Partial<IHistoryInstanceCallbacks>);
+    onConnect?: (clientId: string, swarmName: SwarmName) => void;
     /**
-     * Iterate over the history messages for a given agent.
-     * @param agentName - The agent name.
-     * @returns An async iterable iterator of model messages.
+     * Callback triggered when a command is executed.
+     * @param clientId - The ID of the client.
+     * @param swarmName - The name of the swarm.
+     * @param content - The content to execute.
+     * @param mode - The source of execution: tool or user.
      */
-    iterate(agentName: AgentName): AsyncIterableIterator<IModelMessage>;
+    onExecute?: (clientId: string, swarmName: SwarmName, content: string, mode: ExecutionMode) => void;
     /**
-     * Push a new message to the history for a given agent.
-     * @param value - The model message to push.
-     * @param agentName - The agent name.
-     * @returns A promise that resolves when the message is pushed.
+     * Callback triggered when a message is emitted.
+     * @param clientId - The ID of the client.
+     * @param swarmName - The name of the swarm.
+     * @param message - The message to emit.
      */
-    push: (value: IModelMessage, agentName: AgentName) => Promise<void>;
+    onEmit?: (clientId: string, swarmName: SwarmName, message: string) => void;
     /**
-     * Dispose of the history for a given agent.
-     * @param agentName - The agent name or null.
-     * @returns A promise that resolves when the history is disposed.
+     * Callback triggered when a session being connected
+     * @param clientId - The ID of the client.
+     * @param swarmName - The name of the swarm.
      */
-    dispose: (agentName: AgentName | null) => Promise<void>;
+    onInit?: (clientId: string, swarmName: SwarmName) => void;
+    /**
+     * Callback triggered when a session being disponnected
+     * @param clientId - The ID of the client.
+     * @param swarmName - The name of the swarm.
+     */
+    onDispose?: (clientId: string, swarmName: SwarmName) => void;
 }
 /**
- * Class representing History Utilities
+ * Lifecycle callbacks of initialized swarm
  */
-declare class HistoryUtils implements IHistoryAdapter, IHistoryControl {
-    private HistoryFactory;
-    private HistoryCallbacks;
-    private getHistory;
+interface ISwarmCallbacks extends ISwarmSessionCallbacks {
+    /** Emit the callback on agent change */
+    onAgentChanged: (clientId: string, agentName: AgentName, swarmName: SwarmName) => Promise<void>;
+}
+/**
+ * Parameters for initializing a swarm.
+ * @interface
+ * @extends {Omit<ISwarmSchema, 'agentList'>}
+ */
+interface ISwarmParams extends Omit<ISwarmSchema, keyof {
+    agentList: never;
+    onAgentChanged: never;
+}>, ISwarmCallbacks {
+    /** Client identifier */
+    clientId: string;
+    /** Logger instance */
+    logger: ILogger;
+    /** The bus instance. */
+    bus: IBus;
+    /** Map of agent names to agent instances */
+    agentMap: Record<AgentName, IAgent>;
+}
+/**
+ * Schema for defining a swarm.
+ * @interface
+ */
+interface ISwarmSchema {
+    /** Default agent name */
+    defaultAgent: AgentName;
+    /** Name of the swarm */
+    swarmName: string;
+    /** List of agent names */
+    agentList: string[];
+    /** Lifecycle callbacks*/
+    callbacks?: Partial<ISwarmCallbacks>;
+}
+/**
+ * Interface for a swarm.
+ * @interface
+ */
+interface ISwarm {
     /**
-     * Use a custom history adapter.
-     * @param Ctor - The constructor for the history instance.
+     * Will return empty string in waitForOutput
+     * @returns {Promise<void>}
      */
-    useHistoryAdapter: (Ctor: THistoryInstanceCtor) => void;
+    cancelOutput(): Promise<void>;
     /**
-     * Use history lifecycle callbacks.
-     * @param Callbacks - The callbacks dictionary.
+     * Waits for the output from the swarm.
+     * @returns {Promise<string>} The output from the swarm.
      */
-    useHistoryCallbacks: (Callbacks: Partial<IHistoryInstanceCallbacks>) => void;
+    waitForOutput(): Promise<string>;
     /**
-     * Iterate over the history messages.
-     * @param clientId - The client ID.
-     * @param agentName - The agent name.
-     * @returns An async iterable iterator of model messages.
+     * Gets the name of the agent.
+     * @returns {Promise<AgentName>} The name of the agent.
      */
-    iterate(clientId: string, agentName: AgentName): AsyncIterableIterator<IModelMessage>;
+    getAgentName(): Promise<AgentName>;
     /**
-     * Push a new message to the history.
-     * @param value - The model message to push.
-     * @param clientId - The client ID.
-     * @param agentName - The agent name.
-     * @returns A promise that resolves when the message is pushed.
+     * Gets the agent instance.
+     * @returns {Promise<IAgent>} The agent instance.
      */
-    push: (value: IModelMessage, clientId: string, agentName: AgentName) => Promise<void>;
+    getAgent(): Promise<IAgent>;
     /**
-     * Dispose of the history for a given client and agent.
-     * @param clientId - The client ID.
-     * @param agentName - The agent name or null.
-     * @returns A promise that resolves when the history is disposed.
+     * Sets the reference to an agent.
+     * @param {AgentName} agentName - The name of the agent.
+     * @param {IAgent} agent - The agent instance.
+     * @returns {Promise<void>}
      */
-    dispose: (clientId: string, agentName: AgentName | null) => Promise<void>;
+    setAgentRef(agentName: AgentName, agent: IAgent): Promise<void>;
+    /**
+     * Sets the name of the agent.
+     * @param {AgentName} agentName - The name of the agent.
+     * @returns {Promise<void>}
+     */
+    setAgentName(agentName: AgentName): Promise<void>;
+}
+/** Type alias for swarm name */
+type SwarmName = string;
+
+/**
+ * Parameters required to create a session.
+ * @interface
+ */
+interface ISessionParams extends ISessionSchema, ISwarmSessionCallbacks {
+    clientId: string;
+    logger: ILogger;
+    bus: IBus;
+    swarm: ISwarm;
+    swarmName: SwarmName;
 }
 /**
- * Exported History Adapter instance
+ * Schema for session data.
+ * @interface
  */
-declare const HistoryAdapter: HistoryUtils;
+interface ISessionSchema {
+}
 /**
- * Exported History Control instance
+ * Function type for sending messages.
+ * @typedef {function} SendMessageFn
+ * @param {IOutgoingMessage} outgoing - The outgoing message.
+ * @returns {Promise<void> | void}
  */
-declare const History: IHistoryControl;
-
+type SendMessageFn$1 = (outgoing: IOutgoingMessage) => Promise<void> | void;
 /**
- * Interface representing the history of model messages.
+ * Function type for receiving messages.
+ * @typedef {function} ReceiveMessageFn
+ * @param {IIncomingMessage} incoming - The incoming message.
+ * @returns {Promise<void> | void}
  */
-interface IHistory {
+type ReceiveMessageFn = (incoming: IIncomingMessage) => Promise<void> | void;
+/**
+ * Interface for a session.
+ * @interface
+ */
+interface ISession {
     /**
-     * Pushes a message to the history.
-     * @param {IModelMessage} message - The message to push.
+     * Emit a message.
+     * @param {string} message - The message to emit.
      * @returns {Promise<void>}
      */
-    push(message: IModelMessage): Promise<void>;
+    emit(message: string): Promise<void>;
     /**
-     * Converts the history to an array of messages for a specific agent.
-     * @param {string} prompt - The prompt to filter messages for the agent.
-     * @returns {Promise<IModelMessage[]>}
+     * Execute a command.
+     * @param {string} content - The content to execute.
+     * @param {string} mode - The source of execution: tool or user
+     * @returns {Promise<string>}
      */
-    toArrayForAgent(prompt: string, system?: string[]): Promise<IModelMessage[]>;
+    execute(content: string, mode: ExecutionMode): Promise<string>;
     /**
-     * Converts the history to an array of raw messages.
-     * @returns {Promise<IModelMessage[]>}
+     * Connect to a message sender.
+     * @param {SendMessageFn} connector - The function to send messages.
+     * @returns {ReceiveMessageFn}
      */
-    toArrayForRaw(): Promise<IModelMessage[]>;
-}
-/**
- * Interface representing the parameters required to create a history instance.
- */
-interface IHistoryParams extends IHistorySchema {
+    connect(connector: SendMessageFn$1): ReceiveMessageFn;
     /**
-     * The name of the agent.
-     * @type {AgentName}
+     * Commit tool output.
+     * @param {string} toolId - The `tool_call_id` for openai history
+     * @param {string} content - The content to commit.
+     * @returns {Promise<void>}
      */
-    agentName: AgentName;
+    commitToolOutput(toolId: string, content: string): Promise<void>;
     /**
-     * The client ID.
-     * @type {string}
+     * Commit user message without answer
+     * @param {string} message - The message to commit.
+     * @returns {Promise<void>}
      */
-    clientId: string;
+    commitUserMessage: (message: string) => Promise<void>;
     /**
-     * The logger instance.
-     * @type {ILogger}
+     * Commit flush of agent history
+     * @returns {Promise<void>}
      */
-    logger: ILogger;
-}
-/**
- * Interface representing the schema of the history.
- */
-interface IHistorySchema {
+    commitFlush: () => Promise<void>;
     /**
-     * The adapter for array of model messages.
-     * @type {IHistoryAdapter}
+     * Commit a system message.
+     * @param {string} message - The message to commit.
+     * @returns {Promise<void>}
      */
-    items: IHistoryAdapter;
+    commitSystemMessage(message: string): Promise<void>;
 }
-
 /**
- * Interface representing a completion.
+ * Type for session ID.
+ * @typedef {string} SessionId
  */
-interface ICompletion extends ICompletionSchema {
-}
+type SessionId = string;
 /**
- * Arguments required to get a completion.
+ * Type for session mode.
+ * @typedef {"session" | "makeConnection" | "complete"} SessionMode
  */
-interface ICompletionArgs {
-    /**
-     * Client ID.
-     */
-    clientId: string;
-    /**
-     * Name of the agent.
-     */
-    agentName: AgentName;
+type SessionMode = "session" | "makeConnection" | "complete";
+/**
+ * Tools can emit user messages to trigger user friendly responses.
+ * Should be ignored for `getUserHistory`
+ * @typedef {"tool" | "user"} ExecutionMode
+ */
+type ExecutionMode = "tool" | "user";
+
+/**
+ * Represents a tool call with a function name and arguments.
+ */
+interface IToolCall {
     /**
-     * The source of the last message: tool or user
+     * The ID of the tool call.
      */
-    mode: ExecutionMode;
+    id: string;
     /**
-     * Array of model messages.
+     * The type of the tool. Currently, only `function` is supported.
      */
-    messages: IModelMessage[];
+    type: 'function';
     /**
-     * Optional array of tools.
+     * The function that the model called.
      */
-    tools?: ITool[];
+    function: {
+        /**
+         * The name of the function to be called.
+         */
+        name: string;
+        /**
+         * The arguments to be passed to the function.
+         */
+        arguments: {
+            [key: string]: any;
+        };
+    };
 }
 /**
- * Completion lifecycle callbacks
+ * Represents a tool with a type and function details.
  */
-interface ICompletionCallbacks {
+interface ITool {
     /**
-     * Callback fired after complete.
-     * @param args - Arguments passed to complete
-     * @param output - Output of the model
+     * The type of the tool.
      */
-    onComplete?: (args: ICompletionArgs, output: IModelMessage) => void;
+    type: string;
+    function: {
+        /**
+         * The name of the function.
+         */
+        name: string;
+        /**
+         * The description of the function.
+         */
+        description: string;
+        /**
+         * The parameters required by the function.
+         */
+        parameters: {
+            /**
+             * The type of the parameters.
+             */
+            type: string;
+            /**
+             * The list of required parameters.
+             */
+            required: string[];
+            /**
+             * The properties of the parameters.
+             */
+            properties: {
+                [key: string]: {
+                    /**
+                     * The type of the property.
+                     */
+                    type: string;
+                    /**
+                     * The description of the property.
+                     */
+                    description: string;
+                    /**
+                     * The possible values for the property.
+                     */
+                    enum?: string[];
+                };
+            };
+        };
+    };
 }
+
 /**
- * Schema for a completion.
+ * Interface representing a model message.
  */
-interface ICompletionSchema {
+interface IModelMessage {
     /**
-     * Name of the completion.
+     * The role of the message sender.
+     * @type {'assistant' | 'system' | 'tool' | 'user' | 'resque' | 'flush'}
      */
-    completionName: CompletionName;
+    role: "assistant" | "system" | "tool" | "user" | "resque" | "flush";
     /**
-     * Method to get a completion.
-     * @param args - Arguments required to get a completion.
-     * @returns A promise that resolves to a model message.
+     * The name of the agent sending the message.
+     * @type {string}
      */
-    getCompletion(args: ICompletionArgs): Promise<IModelMessage>;
+    agentName: string;
     /**
-     * Completion lifecycle callbacks
+     * The content of the message.
+     * @type {string}
      */
-    callbacks?: Partial<ICompletionCallbacks>;
-}
-/**
- * Type representing the name of a completion.
- */
-type CompletionName = string;
-
-/**
- * Type representing an array of numbers as embeddings.
- */
-type Embeddings = number[];
-/**
- * Interface for embedding callbacks.
- */
-interface IEmbeddingCallbacks {
+    content: string;
     /**
-     * Callback for when an embedding is created.
-     * @param text - The text used to create the embedding.
-     * @param embeddings - The generated embeddings.
-     * @param clientId - The client ID associated with the embedding.
-     * @param embeddingName - The name of the embedding.
+     * The source of message: tool or user
+     * @type {ExecutionMode}
      */
-    onCreate(text: string, embeddings: Embeddings, clientId: string, embeddingName: EmbeddingName): void;
+    mode: ExecutionMode;
     /**
-     * Callback for when embeddings are compared.
-     * @param text1 - The first text used in the comparison.
-     * @param text2 - The second text used in the comparison.
-     * @param similarity - The similarity score between the embeddings.
-     * @param clientId - The client ID associated with the comparison.
-     * @param embeddingName - The name of the embedding.
+     * Optional tool calls associated with the message.
+     * @type {Array<{ function: { name: string; arguments: { [key: string]: any; }; }; }>}
+     */
+    tool_calls?: IToolCall[];
+    /**
+     * Tool call that this message is responding to.
      */
-    onCompare(text1: string, text2: string, similarity: number, clientId: string, embeddingName: EmbeddingName): void;
+    tool_call_id?: string;
 }
+
 /**
- * Interface representing the schema for embeddings.
+ * Interface for History Adapter Callbacks
  */
-interface IEmbeddingSchema {
+interface IHistoryInstanceCallbacks {
     /**
-     * The name of the embedding.
+     * Filter condition for history messages.
+     * @param message - The model message.
+     * @param clientId - The client ID.
+     * @param agentName - The agent name.
+     * @returns A promise that resolves to a boolean indicating whether the message passes the filter.
      */
-    embeddingName: EmbeddingName;
+    filterCondition?: (message: IModelMessage, clientId: string, agentName: AgentName) => Promise<boolean> | boolean;
     /**
-     * Creates an embedding from the given text.
-     * @param text - The text to create the embedding from.
-     * @returns A promise that resolves to the generated embeddings.
+     * Get data for the history.
+     * @param clientId - The client ID.
+     * @param agentName - The agent name.
+     * @returns A promise that resolves to an array of model messages.
      */
-    createEmbedding(text: string): Promise<Embeddings>;
+    getData: (clientId: string, agentName: AgentName) => Promise<IModelMessage[]> | IModelMessage[];
     /**
-     * Calculates the similarity between two embeddings.
-     * @param a - The first embedding.
-     * @param b - The second embedding.
-     * @returns A promise that resolves to the similarity score.
+     * Callback for when the history changes.
+     * @param data - The array of model messages.
+     * @param clientId - The client ID.
+     * @param agentName - The agent name.
      */
-    calculateSimilarity(a: Embeddings, b: Embeddings): Promise<number>;
+    onChange: (data: IModelMessage[], clientId: string, agentName: AgentName) => void;
     /**
-     * Optional callbacks for embedding events.
+     * Callback for when the history get the new message
+     * @param data - The array of model messages.
+     * @param clientId - The client ID.
+     * @param agentName - The agent name.
      */
-    callbacks?: Partial<IEmbeddingCallbacks>;
-}
-/**
- * Type representing the name of an embedding.
- */
-type EmbeddingName = string;
-
-type StorageId = string | number;
-/**
- * Interface representing the data stored in the storage.
- */
-interface IStorageData {
-    id: StorageId;
-}
-/**
- * Interface representing the schema of the storage.
- * @template T - Type of the storage data.
- */
-interface IStorageSchema<T extends IStorageData = IStorageData> {
+    onPush: (data: IModelMessage, clientId: string, agentName: AgentName) => void;
     /**
-     * All agents will share the same ClientStorage instance
+     * Callback for when the history is read. Will be called for each message
+     * @param message - The model message.
+     * @param clientId - The client ID.
+     * @param agentName - The agent name.
      */
-    shared?: boolean;
+    onRead: (message: IModelMessage, clientId: string, agentName: AgentName) => void;
     /**
-     * Function to get data from the storage.
+     * Callback for when the read is begin
      * @param clientId - The client ID.
-     * @param storageName - The name of the storage.
-     * @returns A promise that resolves to an array of storage data or an array of storage data.
+     * @param agentName - The agent name.
      */
-    getData?: (clientId: string, storageName: StorageName) => Promise<T[]> | T[];
+    onReadBegin: (clientId: string, agentName: AgentName) => void;
     /**
-     * Function to create an index for an item.
-     * @param item - The item to index.
-     * @returns A promise that resolves to a string or a string.
+     * Callback for when the read is end
+     * @param clientId - The client ID.
+     * @param agentName - The agent name.
      */
-    createIndex(item: T): Promise<string> | string;
+    onReadEnd: (clientId: string, agentName: AgentName) => void;
     /**
-     * The name of the embedding.
+     * Callback for when the history is disposed.
+     * @param clientId - The client ID.
      */
-    embedding: EmbeddingName;
+    onDispose: (clientId: string) => void;
     /**
-     * The name of the storage.
+     * Callback for when the history is initialized.
+     * @param clientId - The client ID.
      */
-    storageName: StorageName;
+    onInit: (clientId: string) => void;
     /**
-     * Optional callbacks for storage events.
+     * Callback to obtain history ref
+     * @param clientId - The client ID.
      */
-    callbacks?: Partial<IStorageCallbacks<T>>;
+    onRef: (history: HistoryInstance) => void;
 }
 /**
- * Interface representing the callbacks for storage events.
- * @template T - Type of the storage data.
+ * Interface for History Adapter
  */
-interface IStorageCallbacks<T extends IStorageData = IStorageData> {
+interface IHistoryAdapter {
     /**
-     * Callback function for update events.
-     * @param items - The updated items.
+     * Iterate over the history messages.
      * @param clientId - The client ID.
-     * @param storageName - The name of the storage.
+     * @param agentName - The agent name.
+     * @returns An async iterable iterator of model messages.
      */
-    onUpdate: (items: T[], clientId: string, storageName: StorageName) => void;
+    iterate(clientId: string, agentName: AgentName): AsyncIterableIterator<IModelMessage>;
     /**
-     * Callback function for search events.
-     * @param search - The search query.
-     * @param index - The sorted array of storage data.
+     * Push a new message to the history.
+     * @param value - The model message to push.
      * @param clientId - The client ID.
-     * @param storageName - The name of the storage.
+     * @param agentName - The agent name.
+     * @returns A promise that resolves when the message is pushed.
      */
-    onSearch: (search: string, index: SortedArray<T>, clientId: string, storageName: StorageName) => void;
+    push: (value: IModelMessage, clientId: string, agentName: AgentName) => Promise<void>;
+    /**
+     * Dispose of the history for a given client and agent.
+     * @param clientId - The client ID.
+     * @param agentName - The agent name or null.
+     * @returns A promise that resolves when the history is disposed.
+     */
+    dispose: (clientId: string, agentName: AgentName | null) => Promise<void>;
 }
 /**
- * Interface representing the parameters for storage.
- * @template T - Type of the storage data.
+ * Interface for History Control
  */
-interface IStorageParams<T extends IStorageData = IStorageData> extends IStorageSchema<T>, Partial<IEmbeddingCallbacks> {
+interface IHistoryControl {
     /**
-     * The client ID.
+     * Use a custom history adapter.
+     * @param Ctor - The constructor for the history instance.
      */
-    clientId: string;
+    useHistoryAdapter(Ctor: THistoryInstanceCtor): void;
     /**
-     * Function to calculate similarity.
+     * Use history lifecycle callbacks.
+     * @param Callbacks - The callbacks dictionary.
      */
-    calculateSimilarity: IEmbeddingSchema["calculateSimilarity"];
+    useHistoryCallbacks: (Callbacks: Partial<IHistoryInstanceCallbacks>) => void;
+}
+/**
+ * Interface for History Instance
+ */
+interface IHistoryInstance {
     /**
-     * Function to create an embedding.
+     * Iterate over the history messages for a given agent.
+     * @param agentName - The agent name.
+     * @returns An async iterable iterator of model messages.
      */
-    createEmbedding: IEmbeddingSchema["createEmbedding"];
+    iterate(agentName: AgentName): AsyncIterableIterator<IModelMessage>;
     /**
-     * The name of the storage.
+     * Wait for the history to initialize.
+     * @param agentName - The agent name.
+     * @param init - Whether the history is initializing.
+     * @returns A promise that resolves when the history is initialized.
      */
-    storageName: StorageName;
+    waitForInit(agentName: AgentName, init: boolean): Promise<void>;
     /**
-     * Logger instance.
+     * Push a new message to the history for a given agent.
+     * @param value - The model message to push.
+     * @param agentName - The agent name.
+     * @returns A promise that resolves when the message is pushed.
      */
-    logger: ILogger;
+    push(value: IModelMessage, agentName: AgentName): Promise<void>;
+    /**
+     * Dispose of the history for a given agent.
+     * @param agentName - The agent name or null.
+     * @returns A promise that resolves when the history is disposed.
+     */
+    dispose(agentName: AgentName | null): Promise<void>;
 }
 /**
- * Interface representing the storage.
- * @template T - Type of the storage data.
+ * Type for History Instance Constructor
  */
-interface IStorage<T extends IStorageData = IStorageData> {
+type THistoryInstanceCtor = new (clientId: string, ...args: unknown[]) => IHistoryInstance;
+/**
+ * Class representing a History Instance
+ */
+declare class HistoryInstance implements IHistoryInstance {
+    readonly clientId: string;
+    readonly callbacks: Partial<IHistoryInstanceCallbacks>;
+    private _array;
     /**
-     * Function to take items from the storage.
-     * @param search - The search query.
-     * @param total - The total number of items to take.
-     * @param score - Optional score parameter.
-     * @returns A promise that resolves to an array of storage data.
+     * Wait for the history to initialize.
+     * @param agentName - The agent name.
      */
-    take(search: string, total: number, score?: number): Promise<T[]>;
+    waitForInit: ((agentName: AgentName) => Promise<void>) & functools_kit.ISingleshotClearable;
     /**
-     * Function to upsert an item in the storage.
-     * @param item - The item to upsert.
-     * @returns A promise that resolves when the operation is complete.
+     * Create a HistoryInstance.
+     * @param clientId - The client ID.
+     * @param callbacks - The callbacks for the history instance.
      */
-    upsert(item: T): Promise<void>;
+    constructor(clientId: string, callbacks: Partial<IHistoryInstanceCallbacks>);
     /**
-     * Function to remove an item from the storage.
-     * @param itemId - The ID of the item to remove.
-     * @returns A promise that resolves when the operation is complete.
+     * Iterate over the history messages for a given agent.
+     * @param agentName - The agent name.
+     * @returns An async iterable iterator of model messages.
      */
-    remove(itemId: IStorageData["id"]): Promise<void>;
+    iterate(agentName: AgentName): AsyncIterableIterator<IModelMessage>;
     /**
-     * Function to get an item from the storage.
-     * @param itemId - The ID of the item to get.
-     * @returns A promise that resolves to the item or null if not found.
+     * Push a new message to the history for a given agent.
+     * @param value - The model message to push.
+     * @param agentName - The agent name.
+     * @returns A promise that resolves when the message is pushed.
      */
-    get(itemId: IStorageData["id"]): Promise<T | null>;
+    push: (value: IModelMessage, agentName: AgentName) => Promise<void>;
     /**
-     * Function to list items from the storage.
-     * @param filter - Optional filter function.
-     * @returns A promise that resolves to an array of storage data.
+     * Dispose of the history for a given agent.
+     * @param agentName - The agent name or null.
+     * @returns A promise that resolves when the history is disposed.
+     */
+    dispose: (agentName: AgentName | null) => Promise<void>;
+}
+/**
+ * Class representing History Utilities
+ */
+declare class HistoryUtils implements IHistoryAdapter, IHistoryControl {
+    private HistoryFactory;
+    private HistoryCallbacks;
+    private getHistory;
+    /**
+     * Use a custom history adapter.
+     * @param Ctor - The constructor for the history instance.
+     */
+    useHistoryAdapter: (Ctor: THistoryInstanceCtor) => void;
+    /**
+     * Use history lifecycle callbacks.
+     * @param Callbacks - The callbacks dictionary.
+     */
+    useHistoryCallbacks: (Callbacks: Partial<IHistoryInstanceCallbacks>) => void;
+    /**
+     * Iterate over the history messages.
+     * @param clientId - The client ID.
+     * @param agentName - The agent name.
+     * @returns An async iterable iterator of model messages.
+     */
+    iterate(clientId: string, agentName: AgentName): AsyncIterableIterator<IModelMessage>;
+    /**
+     * Push a new message to the history.
+     * @param value - The model message to push.
+     * @param clientId - The client ID.
+     * @param agentName - The agent name.
+     * @returns A promise that resolves when the message is pushed.
      */
-    list(filter?: (item: T) => boolean): Promise<T[]>;
+    push: (value: IModelMessage, clientId: string, agentName: AgentName) => Promise<void>;
     /**
-     * Function to clear the storage.
-     * @returns A promise that resolves when the operation is complete.
+     * Dispose of the history for a given client and agent.
+     * @param clientId - The client ID.
+     * @param agentName - The agent name or null.
+     * @returns A promise that resolves when the history is disposed.
      */
-    clear(): Promise<void>;
+    dispose: (clientId: string, agentName: AgentName | null) => Promise<void>;
 }
 /**
- * Type representing the name of the storage.
+ * Exported History Adapter instance
  */
-type StorageName = string;
-
-type IStateData = any;
+declare const HistoryAdapter: HistoryUtils;
 /**
- * Middleware function for state management.
- * @template T - The type of the state data.
- * @param {T} state - The current state.
- * @param {string} clientId - The client ID.
- * @param {StateName} stateName - The name of the state.
- * @returns {Promise<T>} - The updated state.
+ * Exported History Control instance
  */
-interface IStateMiddleware<T extends IStateData = IStateData> {
-    (state: T, clientId: string, stateName: StateName): Promise<T>;
-}
+declare const History: IHistoryControl;
+
 /**
- * Callbacks for state lifecycle events.
- * @template T - The type of the state data.
+ * Interface representing the history of model messages.
  */
-interface IStateCallbacks<T extends IStateData = IStateData> {
+interface IHistory {
     /**
-     * Called when the state is initialized.
-     * @param {string} clientId - The client ID.
-     * @param {StateName} stateName - The name of the state.
+     * Pushes a message to the history.
+     * @param {IModelMessage} message - The message to push.
+     * @returns {Promise<void>}
      */
-    onInit: (clientId: string, stateName: StateName) => void;
+    push(message: IModelMessage): Promise<void>;
     /**
-     * Called when the state is disposed.
-     * @param {string} clientId - The client ID.
-     * @param {StateName} stateName - The name of the state.
+     * Converts the history to an array of messages for a specific agent.
+     * @param {string} prompt - The prompt to filter messages for the agent.
+     * @returns {Promise<IModelMessage[]>}
      */
-    onDispose: (clientId: string, stateName: StateName) => void;
+    toArrayForAgent(prompt: string, system?: string[]): Promise<IModelMessage[]>;
     /**
-     * Called when the state is loaded.
-     * @param {T} state - The current state.
-     * @param {string} clientId - The client ID.
-     * @param {StateName} stateName - The name of the state.
+     * Converts the history to an array of raw messages.
+     * @returns {Promise<IModelMessage[]>}
      */
-    onLoad: (state: T, clientId: string, stateName: StateName) => void;
+    toArrayForRaw(): Promise<IModelMessage[]>;
+}
+/**
+ * Interface representing the parameters required to create a history instance.
+ */
+interface IHistoryParams extends IHistorySchema {
     /**
-     * Called when the state is read.
-     * @param {T} state - The current state.
-     * @param {string} clientId - The client ID.
-     * @param {StateName} stateName - The name of the state.
+     * The name of the agent.
+     * @type {AgentName}
      */
-    onRead: (state: T, clientId: string, stateName: StateName) => void;
+    agentName: AgentName;
     /**
-     * Called when the state is written.
-     * @param {T} state - The current state.
-     * @param {string} clientId - The client ID.
-     * @param {StateName} stateName - The name of the state.
+     * The client ID.
+     * @type {string}
      */
-    onWrite: (state: T, clientId: string, stateName: StateName) => void;
+    clientId: string;
+    /**
+     * The logger instance.
+     * @type {ILogger}
+     */
+    logger: ILogger;
+    /** The bus instance. */
+    bus: IBus;
 }
 /**
- * Schema for state management.
- * @template T - The type of the state data.
+ * Interface representing the schema of the history.
  */
-interface IStateSchema<T extends IStateData = IStateData> {
+interface IHistorySchema {
     /**
-     * The name of the state.
+     * The adapter for array of model messages.
+     * @type {IHistoryAdapter}
      */
-    stateName: StateName;
+    items: IHistoryAdapter;
+}
+
+/**
+ * Interface representing a completion.
+ */
+interface ICompletion extends ICompletionSchema {
+}
+/**
+ * Arguments required to get a completion.
+ */
+interface ICompletionArgs {
     /**
-     * Gets the state.
-     * @param {string} clientId - The client ID.
-     * @param {StateName} stateName - The name of the state.
-     * @returns {T | Promise<T>} - The current state.
+     * Client ID.
      */
-    getState: (clientId: string, stateName: StateName) => T | Promise<T>;
+    clientId: string;
     /**
-     * Sets the state.
-     * @param {T} state - The new state.
-     * @param {string} clientId - The client ID.
-     * @param {StateName} stateName - The name of the state.
-     * @returns {Promise<void> | void} - A promise that resolves when the state is set.
+     * Name of the agent.
      */
-    setState?: (state: T, clientId: string, stateName: StateName) => Promise<void> | void;
+    agentName: AgentName;
     /**
-     * Middleware functions for state management.
+     * The source of the last message: tool or user
      */
-    middlewares?: IStateMiddleware<T>[];
+    mode: ExecutionMode;
     /**
-     * Callbacks for state lifecycle events.
+     * Array of model messages.
      */
-    callbacks?: Partial<IStateCallbacks<T>>;
+    messages: IModelMessage[];
+    /**
+     * Optional array of tools.
+     */
+    tools?: ITool[];
 }
 /**
- * Parameters for state management.
- * @template T - The type of the state data.
+ * Completion lifecycle callbacks
  */
-interface IStateParams<T extends IStateData = IStateData> extends IStateSchema<T> {
-    /**
-     * The client ID.
-     */
-    clientId: string;
+interface ICompletionCallbacks {
     /**
-     * The logger instance.
+     * Callback fired after complete.
+     * @param args - Arguments passed to complete
+     * @param output - Output of the model
      */
-    logger: ILogger;
+    onComplete?: (args: ICompletionArgs, output: IModelMessage) => void;
 }
 /**
- * State management interface.
- * @template T - The type of the state data.
+ * Schema for a completion.
  */
-interface IState<T extends IStateData = IStateData> {
+interface ICompletionSchema {
     /**
-     * Gets the state.
-     * @returns {Promise<T>} - The current state.
+     * Name of the completion.
      */
-    getState: () => Promise<T>;
+    completionName: CompletionName;
     /**
-     * Sets the state.
-     * @param {(prevState: T) => Promise<T>} dispatchFn - The function to dispatch the new state.
-     * @returns {Promise<T>} - The updated state.
+     * Method to get a completion.
+     * @param args - Arguments required to get a completion.
+     * @returns A promise that resolves to a model message.
      */
-    setState: (dispatchFn: (prevState: T) => Promise<T>) => Promise<T>;
+    getCompletion(args: ICompletionArgs): Promise<IModelMessage>;
+    /**
+     * Completion lifecycle callbacks
+     */
+    callbacks?: Partial<ICompletionCallbacks>;
 }
 /**
- * The name of the state.
+ * Type representing the name of a completion.
  */
-type StateName = string;
+type CompletionName = string;
 
 /**
  * Interface representing lifecycle callbacks of a tool
@@ -1128,6 +1197,8 @@ interface IAgentParams extends Omit<IAgentSchema, keyof {
     clientId: string;
     /** The logger instance. */
     logger: ILogger;
+    /** The bus instance. */
+    bus: IBus;
     /** The history instance. */
     history: IHistory;
     /** The completion instance. */
@@ -1429,6 +1500,7 @@ declare class ClientAgent implements IAgent {
  */
 declare class AgentConnectionService implements IAgent {
     private readonly loggerService;
+    private readonly busService;
     private readonly contextService;
     private readonly sessionValidationService;
     private readonly historyConnectionService;
@@ -1536,6 +1608,7 @@ declare class ClientHistory implements IHistory {
  */
 declare class HistoryConnectionService implements IHistory {
     private readonly loggerService;
+    private readonly busService;
     private readonly contextService;
     private readonly sessionValidationService;
     /**
@@ -1616,16 +1689,21 @@ declare class ClientSwarm implements ISwarm {
     readonly params: ISwarmParams;
     private _agentChangedSubject;
     private _activeAgent;
+    private _cancelOutputSubject;
     get _agentList(): [string, IAgent][];
     /**
      * Creates an instance of ClientSwarm.
      * @param {ISwarmParams} params - The parameters for the swarm.
      */
     constructor(params: ISwarmParams);
+    /**
+     * Cancel the await of output by emit of empty string
+     * @returns {Promise<string>} - The output from the active agent.
+     */
+    cancelOutput: () => Promise<void>;
     /**
      * Waits for output from the active agent.
      * @returns {Promise<string>} - The output from the active agent.
-     * @throws {Error} - If the timeout is reached.
      */
     waitForOutput: () => Promise<string>;
     /**
@@ -1658,6 +1736,7 @@ declare class ClientSwarm implements ISwarm {
  */
 declare class SwarmConnectionService implements ISwarm {
     private readonly loggerService;
+    private readonly busService;
     private readonly contextService;
     private readonly agentConnectionService;
     private readonly swarmSchemaService;
@@ -1668,6 +1747,11 @@ declare class SwarmConnectionService implements ISwarm {
      * @returns {ClientSwarm} The client swarm instance.
      */
     getSwarm: ((clientId: string, swarmName: string) => ClientSwarm) & functools_kit.IClearableMemoize<string> & functools_kit.IControlMemoize<string, ClientSwarm>;
+    /**
+     * Cancel the await of output by emit of empty string
+     * @returns {Promise<void>}
+     */
+    cancelOutput: () => Promise<void>;
     /**
      * Waits for the output from the swarm.
      * @returns {Promise<any>} The output from the swarm.
@@ -1810,6 +1894,7 @@ declare class ClientSession implements ISession {
  */
 declare class SessionConnectionService implements ISession {
     private readonly loggerService;
+    private readonly busService;
     private readonly contextService;
     private readonly swarmConnectionService;
     private readonly swarmSchemaService;
@@ -2094,6 +2179,13 @@ type TSwarmConnectionService = {
 declare class SwarmPublicService implements TSwarmConnectionService {
     private readonly loggerService;
     private readonly swarmConnectionService;
+    /**
+     * Cancel the await of output by emit of empty string
+     * @param {string} clientId - The client ID.
+     * @param {SwarmName} swarmName - The swarm name.
+     * @returns {Promise<void>}
+     */
+    cancelOutput: (clientId: string, swarmName: SwarmName) => Promise<void>;
     /**
      * Waits for output from the swarm.
      * @param {string} clientId - The client ID.
@@ -2482,6 +2574,11 @@ declare class ClientStorage<T extends IStorageData = IStorageData> implements IS
      * @returns {Promise<T[]>} - The list of items.
      */
     list: (filter?: (item: T) => boolean) => Promise<T[]>;
+    /**
+     * Disposes of the state.
+     * @returns {Promise<void>}
+     */
+    dispose: () => Promise<void>;
 }
 
 /**
@@ -2490,6 +2587,7 @@ declare class ClientStorage<T extends IStorageData = IStorageData> implements IS
  */
 declare class StorageConnectionService implements IStorage {
     private readonly loggerService;
+    private readonly busService;
     private readonly contextService;
     private readonly storageSchemaService;
     private readonly sessionValidationService;
@@ -2701,9 +2799,17 @@ declare class ClientState<State extends IStateData = IStateData> implements ISta
  */
 declare class StateConnectionService<T extends IStateData = IStateData> implements IState<T> {
     private readonly loggerService;
+    private readonly busService;
     private readonly contextService;
     private readonly stateSchemaService;
     private readonly sessionValidationService;
+    /**
+     * Memoized function to get a shared state reference.
+     * @param {string} clientId - The client ID.
+     * @param {StateName} stateName - The state name.
+     * @returns {ClientState} The client state.
+     */
+    getSharedStateRef: ((clientId: string, stateName: StateName) => ClientState<any>) & functools_kit.IClearableMemoize<string> & functools_kit.IControlMemoize<string, ClientState<any>>;
     /**
      * Memoized function to get a state reference.
      * @param {string} clientId - The client ID.
@@ -2733,6 +2839,7 @@ interface IStateConnectionService extends StateConnectionService {
 }
 type InternalKeys = keyof {
     getStateRef: never;
+    getSharedStateRef: never;
 };
 type TStateConnectionService = {
     [key in Exclude<keyof IStateConnectionService, InternalKeys>]: unknown;
@@ -2784,6 +2891,41 @@ declare class StateSchemaService {
     get: (key: StateName) => IStateSchema;
 }
 
+declare class BusService implements IBus {
+    private readonly loggerService;
+    private _eventSourceSet;
+    private getEventSubject;
+    /**
+     * Subscribes to events for a specific client and source.
+     * @param {string} clientId - The client ID.
+     * @param {EventSource} source - The event source.
+     * @param {(event: T) => void} fn - The callback function to handle the event.
+     * @returns {Subscription} The subscription object.
+     */
+    subscribe: <T extends IBaseEvent>(clientId: string, source: EventSource, fn: (event: T) => void) => () => void;
+    /**
+     * Subscribes to a single event for a specific client and source.
+     * @param {string} clientId - The client ID.
+     * @param {EventSource} source - The event source.
+     * @param {(event: T) => boolean} filterFn - The filter function to determine if the event should be handled.
+     * @param {(event: T) => void} fn - The callback function to handle the event.
+     * @returns {Subscription} The subscription object.
+     */
+    once: <T extends IBaseEvent>(clientId: string, source: EventSource, filterFn: (event: T) => boolean, fn: (event: T) => void) => () => void;
+    /**
+     * Emits an event for a specific client.
+     * @param {string} clientId - The client ID.
+     * @param {T} event - The event to emit.
+     * @returns {Promise<void>} A promise that resolves when the event has been emitted.
+     */
+    emit: <T extends IBaseEvent>(clientId: string, event: T) => Promise<void>;
+    /**
+     * Disposes of all event subscriptions for a specific client.
+     * @param {string} clientId - The client ID.
+     */
+    dispose: (clientId: string) => void;
+}
+
 declare const swarm: {
     agentValidationService: AgentValidationService;
     toolValidationService: ToolValidationService;
@@ -2811,6 +2953,7 @@ declare const swarm: {
     sessionConnectionService: SessionConnectionService;
     storageConnectionService: StorageConnectionService;
     stateConnectionService: StateConnectionService<any>;
+    busService: BusService;
     loggerService: LoggerService;
     contextService: {
         readonly context: IContext;
@@ -3145,6 +3288,16 @@ declare const emitForce: (content: string, clientId: string) => Promise<void>;
  */
 declare const executeForce: (content: string, clientId: string) => Promise<string>;
 
+/**
+ * Listens for an event on the swarm bus service and executes a callback function when the event is received.
+ *
+ * @template T - The type of the data payload.
+ * @param {string} clientId - The ID of the client to listen for events from.
+ * @param {(data: T) => void} fn - The callback function to execute when the event is received. The data payload is passed as an argument to this function.
+ * @returns {void} - Returns nothing.
+ */
+declare const listenEvent: <T extends unknown = any>(clientId: string, topicName: string, fn: (data: T) => void) => () => void;
+
 /**
  * Retrieves the last message sent by the user from the client's message history.
  *
@@ -3226,6 +3379,88 @@ declare const makeAutoDispose: (clientId: string, swarmName: SwarmName, { timeou
     destroy(): void;
 };
 
+/**
+ * Emits an event to the swarm bus service.
+ *
+ * @template T - The type of the payload.
+ * @param {string} clientId - The ID of the client emitting the event.
+ * @param {T} payload - The payload of the event.
+ * @returns {boolean} - Returns true if the event was successfully emitted.
+ */
+declare const event: <T extends unknown = any>(clientId: string, topicName: string, payload: T) => Promise<void>;
+
+/**
+ * Cancel the await of output by emit of empty string
+ *
+ * @param {string} clientId - The ID of the client.
+ * @param {string} agentName - The name of the agent.
+ * @returns {Promise<void>} - A promise that resolves when the output is canceled
+ */
+declare const cancelOutput: (clientId: string, agentName: string) => Promise<void>;
+
+/**
+ * Cancel the await of output by emit of empty string without checking active agent
+ *
+ * @param {string} clientId - The ID of the client.
+ * @param {string} agentName - The name of the agent.
+ * @returns {Promise<void>} - A promise that resolves when the output is canceled
+ */
+declare const cancelOutputForce: (clientId: string) => Promise<void>;
+
+/**
+ * Hook to subscribe to agent events for a specific client.
+ *
+ * @param {string} clientId - The ID of the client to subscribe to events for.
+ * @param {function} fn - The callback function to handle the event.
+ * @returns {function} - A function to unsubscribe from the event.
+ */
+declare const listenAgentEvent: (clientId: string, fn: (event: IBaseEvent) => void) => () => void;
+
+/**
+ * Hook to subscribe to history events for a specific client.
+ *
+ * @param {string} clientId - The ID of the client to subscribe to.
+ * @param {(event: IBaseEvent) => void} fn - The callback function to handle the event.
+ * @returns {Function} - The unsubscribe function.
+ */
+declare const listenHistoryEvent: (clientId: string, fn: (event: IBaseEvent) => void) => () => void;
+
+/**
+ * Hook to subscribe to session events for a specific client.
+ *
+ * @param {string} clientId - The ID of the client to subscribe to session events for.
+ * @param {function} fn - The callback function to handle the session events.
+ * @returns {function} - The unsubscribe function to stop listening to session events.
+ */
+declare const listenSessionEvent: (clientId: string, fn: (event: IBaseEvent) => void) => () => void;
+
+/**
+ * Hook to subscribe to state events for a specific client.
+ *
+ * @param {string} clientId - The ID of the client to subscribe to.
+ * @param {function} fn - The callback function to handle the event.
+ * @returns {function} - The unsubscribe function to stop listening to the events.
+ */
+declare const listenStateEvent: (clientId: string, fn: (event: IBaseEvent) => void) => () => void;
+
+/**
+ * Hook to subscribe to storage events for a specific client.
+ *
+ * @param {string} clientId - The ID of the client to subscribe to storage events for.
+ * @param {function} fn - The callback function to handle the storage event.
+ * @returns {function} - A function to unsubscribe from the storage events.
+ */
+declare const listenStorageEvent: (clientId: string, fn: (event: IBaseEvent) => void) => () => void;
+
+/**
+ * Hook to subscribe to swarm events for a specific client.
+ *
+ * @param {string} clientId - The ID of the client to subscribe to events for.
+ * @param {(event: IBaseEvent) => void} fn - The callback function to handle the event.
+ * @returns {Function} - A function to unsubscribe from the event.
+ */
+declare const listenSwarmEvent: (clientId: string, fn: (event: IBaseEvent) => void) => () => void;
+
 declare const GLOBAL_CONFIG: {
     CC_TOOL_CALL_EXCEPTION_PROMPT: string;
     CC_EMPTY_OUTPUT_PLACEHOLDERS: string[];
@@ -3387,4 +3622,4 @@ declare class StateUtils implements TState {
  */
 declare const State: StateUtils;
 
-export { ContextService, History, HistoryAdapter, HistoryInstance, type IAgentSchema, type IAgentTool, type ICompletionArgs, type ICompletionSchema, type IEmbeddingSchema, type IHistoryAdapter, type IHistoryInstance, type IHistoryInstanceCallbacks, type IIncomingMessage, type IMakeConnectionConfig, type IMakeDisposeParams, type IModelMessage, type IOutgoingMessage, type ISessionConfig, type IStateSchema, type IStorageSchema, type ISwarmSchema, type ITool, type IToolCall, type ReceiveMessageFn, type SendMessageFn$1 as SendMessageFn, State, Storage, addAgent, addCompletion, addEmbedding, addState, addStorage, addSwarm, addTool, changeAgent, commitFlush, commitFlushForce, commitSystemMessage, commitSystemMessageForce, commitToolOutput, commitToolOutputForce, commitUserMessage, commitUserMessageForce, complete, disposeConnection, emit, emitForce, execute, executeForce, getAgentHistory, getAgentName, getAssistantHistory, getLastAssistantMessage, getLastSystemMessage, getLastUserMessage, getRawHistory, getSessionMode, getUserHistory, makeAutoDispose, makeConnection, session, setConfig, swarm };
+export { ContextService, type EventSource, History, HistoryAdapter, HistoryInstance, type IAgentSchema, type IAgentTool, type IBaseEvent, type IBaseEventContext, type ICompletionArgs, type ICompletionSchema, type IEmbeddingSchema, type IHistoryAdapter, type IHistoryInstance, type IHistoryInstanceCallbacks, type IIncomingMessage, type IMakeConnectionConfig, type IMakeDisposeParams, type IModelMessage, type IOutgoingMessage, type ISessionConfig, type IStateSchema, type IStorageSchema, type ISwarmSchema, type ITool, type IToolCall, type ReceiveMessageFn, type SendMessageFn$1 as SendMessageFn, State, Storage, addAgent, addCompletion, addEmbedding, addState, addStorage, addSwarm, addTool, cancelOutput, cancelOutputForce, changeAgent, commitFlush, commitFlushForce, commitSystemMessage, commitSystemMessageForce, commitToolOutput, commitToolOutputForce, commitUserMessage, commitUserMessageForce, complete, disposeConnection, emit, emitForce, event, execute, executeForce, getAgentHistory, getAgentName, getAssistantHistory, getLastAssistantMessage, getLastSystemMessage, getLastUserMessage, getRawHistory, getSessionMode, getUserHistory, listenAgentEvent, listenEvent, listenHistoryEvent, listenSessionEvent, listenStateEvent, listenStorageEvent, listenSwarmEvent, makeAutoDispose, makeConnection, session, setConfig, swarm };