agent-swarm-kit 1.0.113 → 1.0.115

package/package.json

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

package/types.d.ts

@@ -522,6 +522,13 @@ interface ISwarmSessionCallbacks {
      * @param mode - The source of execution: tool or user.
      */
     onExecute?: (clientId: string, swarmName: SwarmName, content: string, mode: ExecutionMode) => void;
+    /**
+     * Callback triggered when a stateless completion run executed
+     * @param clientId - The ID of the client.
+     * @param swarmName - The name of the swarm.
+     * @param content - The content to execute.
+     */
+    onRun?: (clientId: string, swarmName: SwarmName, content: string) => void;
     /**
      * Callback triggered when a message is emitted.
      * @param clientId - The ID of the client.
@@ -680,6 +687,12 @@ interface ISession {
      * @returns {Promise<void>}
      */
     emit(message: string): Promise<void>;
+    /**
+     * Run the complete stateless without modifying chat history
+     * @param {string} content - The content to execute.
+     * @returns {Promise<string>}
+     */
+    run(content: string): Promise<string>;
     /**
      * Execute a command.
      * @param {string} content - The content to execute.
@@ -1338,6 +1351,14 @@ interface IAgentParams extends Omit<IAgentSchema, keyof {
  * Interface representing the lifecycle callbacks of an agent
  */
 interface IAgentSchemaCallbacks {
+    /**
+     * Callback triggered when the agent run stateless.
+     * @param clientId - The ID of the client.
+     * @param agentName - The name of the agent.
+     * @param input - The input to execute.
+     * @param mode - The source of execution: tool or user.
+     */
+    onRun?: (clientId: string, agentName: AgentName, input: string) => void;
     /**
      * Callback triggered when the agent executes.
      * @param clientId - The ID of the client.
@@ -1455,6 +1476,12 @@ interface IAgentSchema {
  * Interface representing an agent.
  */
 interface IAgent {
+    /**
+     * Run the complete stateless without write to the chat history
+     * @param input - The input to run.
+     * @returns A promise that resolves when the run is complete.
+     */
+    run: (input: string) => Promise<string>;
     /**
      * Executes the agent with the given input.
      * @param input - The input to execute.
@@ -1662,6 +1689,12 @@ declare class ClientAgent implements IAgent {
      * @returns {Promise<void>}
      */
     execute: IAgent["execute"];
+    /**
+     * Run the completion stateless and return the output
+     * @param {string} incoming - The incoming message content.
+     * @returns {Promise<void>}
+     */
+    run: IAgent["run"];
     /**
      * Should call on agent dispose
      * @returns {Promise<void>}
@@ -1696,6 +1729,12 @@ declare class AgentConnectionService implements IAgent {
      * @returns {Promise<any>} The execution result.
      */
     execute: (input: string, mode: ExecutionMode) => Promise<void>;
+    /**
+     * Run the completion stateless
+     * @param {string} input - The input command.
+     * @returns {Promise<any>} The execution result.
+     */
+    run: (input: string) => Promise<string>;
     /**
      * Waits for the output from the agent.
      * @returns {Promise<any>} The output result.
@@ -2064,6 +2103,12 @@ declare class ClientSession implements ISession {
      * @returns {Promise<string>} - The output of the execution.
      */
     execute: (message: string, mode: ExecutionMode) => Promise<string>;
+    /**
+     * Run the completion stateless
+     * @param {string} message - The message to run.
+     * @returns {Promise<string>} - The output of the execution.
+     */
+    run: (message: string) => Promise<string>;
     /**
      * Commits tool output.
      * @param {string} toolId - The `tool_call_id` for openai history
@@ -2141,6 +2186,12 @@ declare class SessionConnectionService implements ISession {
      * @returns {Promise<string>} A promise that resolves with the execution result.
      */
     execute: (content: string, mode: ExecutionMode) => Promise<string>;
+    /**
+     * Run the completion stateless
+     * @param {string} content - The content to execute.
+     * @returns {Promise<string>} A promise that resolves with the execution result.
+     */
+    run: (content: string) => Promise<string>;
     /**
      * Connects to the session using the provided connector.
      * @param {SendMessageFn} connector - The function to send messages.
@@ -2220,6 +2271,14 @@ declare class AgentPublicService implements TAgentConnectionService {
      * @returns {Promise<unknown>} The execution result.
      */
     execute: (input: string, mode: ExecutionMode, methodName: string, clientId: string, agentName: AgentName) => Promise<void>;
+    /**
+     * Run the completion stateless
+     * @param {string} input - The input command.
+     * @param {string} clientId - The client ID.
+     * @param {AgentName} agentName - The name of the agent.
+     * @returns {Promise<unknown>} The execution result.
+     */
+    run: (input: string, methodName: string, clientId: string, agentName: AgentName) => Promise<string>;
     /**
      * Waits for the agent's output.
      * @param {string} clientId - The client ID.
@@ -2367,6 +2426,14 @@ declare class SessionPublicService implements TSessionConnectionService {
      * @returns {Promise<void>}
      */
     execute: (content: string, mode: ExecutionMode, methodName: string, clientId: string, swarmName: SwarmName) => Promise<string>;
+    /**
+     * Run the completion stateless
+     * @param {string} content - The content to execute.
+     * @param {string} clientId - The client ID.
+     * @param {SwarmName} swarmName - The swarm name.
+     * @returns {Promise<void>}
+     */
+    run: (content: string, methodName: string, clientId: string, swarmName: SwarmName) => Promise<string>;
     /**
      * Connects to the session.
      * @param {SendMessageFn} connector - The function to send messages.
@@ -3502,6 +3569,36 @@ declare class SharedStoragePublicService implements TSharedStorageConnectionServ
     clear: (methodName: string, storageName: StorageName) => Promise<void>;
 }
 
+/**
+ * Service to manage memory schema for different sessions.
+ */
+declare class MemorySchemaService {
+    private readonly loggerService;
+    private memoryMap;
+    /**
+     * Writes a value to the memory map for a given client ID.
+     *
+     * @template T - The type of the value to be written.
+     * @param {string} clientId - The ID of the client.
+     * @param {T} value - The value to be written.
+     */
+    writeValue: <T extends object = object>(clientId: string, value: T) => T;
+    /**
+     * Reads a value from the memory map for a given client ID.
+     *
+     * @template T - The type of the value to be read.
+     * @param {string} clientId - The ID of the client.
+     * @returns {T} - The value associated with the client ID.
+     */
+    readValue: <T extends object = object>(clientId: string) => T;
+    /**
+     * Disposes the memory map entry for a given client ID.
+     *
+     * @param {string} clientId - The ID of the client.
+     */
+    dispose: (clientId: string) => void;
+}
+
 declare const swarm: {
     agentValidationService: AgentValidationService;
     toolValidationService: ToolValidationService;
@@ -3527,6 +3624,7 @@ declare const swarm: {
     embeddingSchemaService: EmbeddingSchemaService;
     storageSchemaService: StorageSchemaService;
     stateSchemaService: StateSchemaService;
+    memorySchemaService: MemorySchemaService;
     agentConnectionService: AgentConnectionService;
     historyConnectionService: HistoryConnectionService;
     swarmConnectionService: SwarmConnectionService;
@@ -3842,6 +3940,29 @@ declare const execute: (content: string, clientId: string, agentName: AgentName)
  */
 declare const emit: (content: string, clientId: string, agentName: AgentName) => Promise<void>;
 
+/**
+ * Complete the message stateless without append to the chat history
+ * Use to prevent model from history overflow while handling storage output
+ *
+ * @param {string} content - The content to be runned.
+ * @param {string} clientId - The ID of the client requesting run.
+ * @param {AgentName} agentName - The name of the agent running the command.
+  * @returns {Promise<string>} - A promise that resolves the run result
+ */
+declare const run: (content: string, clientId: string, agentName: AgentName) => Promise<string>;
+
+/**
+ * Complete the message stateless without append to the chat history
+ * Use to prevent model from history overflow while handling storage output
+ *
+ * Will run even if the agent is inactive
+ *
+ * @param {string} content - The content to be runned.
+ * @param {string} clientId - The ID of the client requesting run.
+ * @returns {Promise<string>} - A promise that resolves the run result
+ */
+declare const runForce: (content: string, clientId: string) => Promise<string>;
+
 type SendMessageFn = (outgoing: string) => Promise<void>;
 /**
  * A connection factory for a client to a swarm and returns a function to send messages.
@@ -3982,6 +4103,27 @@ declare const getAgentHistory: (clientId: string, agentName: AgentName) => Promi
  */
 declare const getSessionMode: (clientId: string) => Promise<SessionMode>;
 
+/**
+ * Represents the session context.
+ *
+ * @interface ISessionContext
+ * @property {string | null} clientId - The client id, or null if not available.
+ * @property {IMethodContext | null} methodContext - The method context, or null if not available.
+ * @property {IExecutionContext | null} executionContext - The execution context, or null if not available.
+ */
+interface ISessionContext {
+    clientId: string | null;
+    methodContext: IMethodContext | null;
+    executionContext: IExecutionContext | null;
+}
+/**
+ * Retrieves the session context for a given client ID.
+ *
+ * @param {string} clientId - The ID of the client.
+ * @returns {Promise<ISessionContext>} A promise that resolves to the session context.
+ */
+declare const getSessionContext: () => Promise<ISessionContext>;
+
 /**
  * Retrieves the last message sent by the user from the client's message history.
  *
@@ -4470,42 +4612,28 @@ declare class SharedStateUtils implements TSharedState {
      * Retrieves the state for a given client and state name.
      * @template T
      * @param {Object} payload - The payload containing client and state information.
-     * @param {AgentName} payload.agentName - The agent name.
      * @param {StateName} payload.stateName - The state name.
      * @returns {Promise<T>} The state data.
      * @throws Will throw an error if the state is not registered in the agent.
      */
-    getState: <T extends unknown = any>(payload: {
-        agentName: AgentName;
-        stateName: StateName;
-    }) => Promise<T>;
+    getState: <T extends unknown = any>(stateName: StateName) => Promise<T>;
     /**
      * Sets the state for a given client and state name.
      * @template T
      * @param {T | ((prevSharedState: T) => Promise<T>)} dispatchFn - The new state or a function that returns the new state.
-     * @param {Object} payload - The payload containing client and state information.
-     * @param {AgentName} payload.agentName - The agent name.
-     * @param {StateName} payload.stateName - The state name.
+     * @param {StateName} stateName - The state name.
      * @returns {Promise<void>}
      * @throws Will throw an error if the state is not registered in the agent.
      */
-    setState: <T extends unknown = any>(dispatchFn: T | ((prevSharedState: T) => Promise<T>), payload: {
-        agentName: AgentName;
-        stateName: StateName;
-    }) => Promise<void>;
+    setState: <T extends unknown = any>(dispatchFn: T | ((prevSharedState: T) => Promise<T>), stateName: StateName) => Promise<void>;
     /**
      * Set the state to initial value
      * @template T
-     * @param {Object} payload - The payload containing client and state information.
-     * @param {AgentName} payload.agentName - The agent name.
      * @param {StateName} payload.stateName - The state name.
      * @returns {Promise<void>}
      * @throws Will throw an error if the state is not registered in the agent.
      */
-    clearState: <T extends unknown = any>(payload: {
-        agentName: AgentName;
-        stateName: StateName;
-    }) => Promise<T>;
+    clearState: <T extends unknown = any>(stateName: StateName) => Promise<T>;
 }
 /**
  * Instance of SharedStateUtils for managing state.
@@ -4617,7 +4745,6 @@ declare class SharedStorageUtils implements TSharedStorage {
      * Takes items from the storage.
      * @param {string} search - The search query.
      * @param {number} total - The total number of items to take.
-     * @param {AgentName} agentName - The agent name.
      * @param {StorageName} storageName - The storage name.
      * @returns {Promise<T[]>} - A promise that resolves to an array of items.
      * @template T
@@ -4625,71 +4752,46 @@ declare class SharedStorageUtils implements TSharedStorage {
     take: <T extends IStorageData = IStorageData>(payload: {
         search: string;
         total: number;
-        agentName: AgentName;
         storageName: StorageName;
         score?: number;
     }) => Promise<T[]>;
     /**
      * Upserts an item in the storage.
      * @param {T} item - The item to upsert.
-     * @param {AgentName} agentName - The agent name.
      * @param {StorageName} storageName - The storage name.
      * @returns {Promise<void>} - A promise that resolves when the operation is complete.
      * @template T
      */
-    upsert: <T extends IStorageData = IStorageData>(payload: {
-        item: T;
-        agentName: AgentName;
-        storageName: StorageName;
-    }) => Promise<void>;
+    upsert: <T extends IStorageData = IStorageData>(item: T, storageName: StorageName) => Promise<void>;
     /**
      * Removes an item from the storage.
      * @param {IStorageData["id"]} itemId - The ID of the item to remove.
-     * @param {AgentName} agentName - The agent name.
      * @param {StorageName} storageName - The storage name.
      * @returns {Promise<void>} - A promise that resolves when the operation is complete.
      */
-    remove: (payload: {
-        itemId: IStorageData["id"];
-        agentName: AgentName;
-        storageName: StorageName;
-    }) => Promise<void>;
+    remove: (itemId: IStorageData["id"], storageName: StorageName) => Promise<void>;
     /**
      * Gets an item from the storage.
      * @param {IStorageData["id"]} itemId - The ID of the item to get.
-     * @param {AgentName} agentName - The agent name.
      * @param {StorageName} storageName - The storage name.
      * @returns {Promise<T | null>} - A promise that resolves to the item or null if not found.
      * @template T
      */
-    get: <T extends IStorageData = IStorageData>(payload: {
-        itemId: IStorageData["id"];
-        agentName: AgentName;
-        storageName: StorageName;
-    }) => Promise<T | null>;
+    get: <T extends IStorageData = IStorageData>(itemId: IStorageData["id"], storageName: StorageName) => Promise<T | null>;
     /**
      * Lists items from the storage.
-     * @param {AgentName} agentName - The agent name.
      * @param {StorageName} storageName - The storage name.
      * @param {(item: T) => boolean} [filter] - Optional filter function.
      * @returns {Promise<T[]>} - A promise that resolves to an array of items.
      * @template T
      */
-    list: <T extends IStorageData = IStorageData>(payload: {
-        agentName: AgentName;
-        storageName: StorageName;
-        filter?: (item: T) => boolean;
-    }) => Promise<T[]>;
+    list: <T extends IStorageData = IStorageData>(storageName: StorageName, filter?: (item: T) => boolean) => Promise<T[]>;
     /**
      * Clears the storage.
-     * @param {AgentName} agentName - The agent name.
      * @param {StorageName} storageName - The storage name.
      * @returns {Promise<void>} - A promise that resolves when the operation is complete.
      */
-    clear: (payload: {
-        agentName: AgentName;
-        storageName: StorageName;
-    }) => Promise<void>;
+    clear: (storageName: StorageName) => Promise<void>;
 }
 declare const SharedStorage: SharedStorageUtils;
 
@@ -4697,6 +4799,23 @@ declare const SharedStorage: SharedStorageUtils;
  * Utility class for schema-related operations.
  */
 declare class SchemaUtils {
+    /**
+     * Writes a value to the session memory for a given client.
+     *
+     * @template T - The type of the value to write.
+     * @param {string} clientId - The ID of the client.
+     * @param {T} value - The value to write to the session memory.
+     * @returns {T} The actual value from the session memory.
+     */
+    writeSessionMemory: <T extends object = object>(clientId: string, value: T) => T;
+    /**
+     * Reads a value from the session memory for a given client.
+     *
+     * @template T - The type of the value to read.
+     * @param {string} clientId - The ID of the client.
+     * @returns {T} The value read from the session memory.
+     */
+    readSessionMemory: <T extends object = object>(clientId: string) => T;
     /**
      * Serializes an object or an array of objects into a formatted string.
      *
@@ -4711,4 +4830,4 @@ declare class SchemaUtils {
  */
 declare const Schema: SchemaUtils;
 
-export { type EventSource, ExecutionContextService, History, HistoryAdapter, HistoryInstance, type IAgentSchema, type IAgentTool, type IBaseEvent, type IBusEvent, type IBusEventContext, type ICompletionArgs, type ICompletionSchema, type ICustomEvent, type IEmbeddingSchema, type IHistoryAdapter, type IHistoryInstance, type IHistoryInstanceCallbacks, type IIncomingMessage, type ILoggerAdapter, type ILoggerInstance, type ILoggerInstanceCallbacks, type IMakeConnectionConfig, type IMakeDisposeParams, type IModelMessage, type IOutgoingMessage, type ISessionConfig, type IStateSchema, type IStorageSchema, type ISwarmSchema, type ITool, type IToolCall, Logger, LoggerAdapter, LoggerInstance, MethodContextService, type ReceiveMessageFn, Schema, type SendMessageFn$1 as SendMessageFn, SharedState, SharedStorage, State, Storage, addAgent, addCompletion, addEmbedding, addState, addStorage, addSwarm, addTool, cancelOutput, cancelOutputForce, changeToAgent, changeToDefaultAgent, changeToPrevAgent, commitAssistantMessage, commitAssistantMessageForce, commitFlush, commitFlushForce, commitStopTools, commitStopToolsForce, commitSystemMessage, commitSystemMessageForce, commitToolOutput, commitToolOutputForce, commitUserMessage, commitUserMessageForce, complete, disposeConnection, dumpAgent, dumpDocs, dumpSwarm, emit, emitForce, event, execute, executeForce, getAgentHistory, getAgentName, getAssistantHistory, getLastAssistantMessage, getLastSystemMessage, getLastUserMessage, getRawHistory, getSessionMode, getUserHistory, listenAgentEvent, listenAgentEventOnce, listenEvent, listenEventOnce, listenHistoryEvent, listenHistoryEventOnce, listenSessionEvent, listenSessionEventOnce, listenStateEvent, listenStateEventOnce, listenStorageEvent, listenStorageEventOnce, listenSwarmEvent, listenSwarmEventOnce, makeAutoDispose, makeConnection, session, setConfig, swarm };
+export { type EventSource, ExecutionContextService, History, HistoryAdapter, HistoryInstance, type IAgentSchema, type IAgentTool, type IBaseEvent, type IBusEvent, type IBusEventContext, type ICompletionArgs, type ICompletionSchema, type ICustomEvent, type IEmbeddingSchema, type IHistoryAdapter, type IHistoryInstance, type IHistoryInstanceCallbacks, type IIncomingMessage, type ILoggerAdapter, type ILoggerInstance, type ILoggerInstanceCallbacks, type IMakeConnectionConfig, type IMakeDisposeParams, type IModelMessage, type IOutgoingMessage, type ISessionConfig, type IStateSchema, type IStorageSchema, type ISwarmSchema, type ITool, type IToolCall, Logger, LoggerAdapter, LoggerInstance, MethodContextService, type ReceiveMessageFn, Schema, type SendMessageFn$1 as SendMessageFn, SharedState, SharedStorage, State, Storage, addAgent, addCompletion, addEmbedding, addState, addStorage, addSwarm, addTool, cancelOutput, cancelOutputForce, changeToAgent, changeToDefaultAgent, changeToPrevAgent, commitAssistantMessage, commitAssistantMessageForce, commitFlush, commitFlushForce, commitStopTools, commitStopToolsForce, commitSystemMessage, commitSystemMessageForce, commitToolOutput, commitToolOutputForce, commitUserMessage, commitUserMessageForce, complete, disposeConnection, dumpAgent, dumpDocs, dumpSwarm, emit, emitForce, event, execute, executeForce, getAgentHistory, getAgentName, getAssistantHistory, getLastAssistantMessage, getLastSystemMessage, getLastUserMessage, getRawHistory, getSessionContext, getSessionMode, getUserHistory, listenAgentEvent, listenAgentEventOnce, listenEvent, listenEventOnce, listenHistoryEvent, listenHistoryEventOnce, listenSessionEvent, listenSessionEventOnce, listenStateEvent, listenStateEventOnce, listenStorageEvent, listenStorageEventOnce, listenSwarmEvent, listenSwarmEventOnce, makeAutoDispose, makeConnection, run, runForce, session, setConfig, swarm };