agent-swarm-kit 1.1.163 → 1.1.165

package/build/index.cjs

@@ -18565,9 +18565,35 @@ const addAdvisorInternal = beginContext((advisorSchema) => {
     return advisorSchema.advisorName;
 });
 /**
- * Adds an advisor schema to the system
+ * Adds an advisor schema to the system.
+ * Registers the advisor with validation and schema services, making it available for chat operations.
+ *
  * @function addAdvisor
- * @param {IAdvisorSchema} advisorSchema - The schema definition for advisor.
+ * @template T - The type of message content the advisor accepts (defaults to string). Can be a custom object, Blob, or string.
+ * @param {IAdvisorSchema<T>} advisorSchema - The schema definition for advisor, including name, chat handler, and optional callbacks.
+ * @returns {string} The advisorName that was registered.
+ *
+ * @example
+ * // Using default string message type
+ * addAdvisor({
+ *   advisorName: "TextAdvisor",
+ *   getChat: async (args) => `Response to: ${args.message}`
+ * });
+ *
+ * @example
+ * // Using custom message type
+ * interface CustomMessage { text: string; metadata: Record<string, any> }
+ * addAdvisor<CustomMessage>({
+ *   advisorName: "StructuredAdvisor",
+ *   getChat: async (args) => `Processing: ${args.message.text}`
+ * });
+ *
+ * @example
+ * // Using Blob message type
+ * addAdvisor<Blob>({
+ *   advisorName: "BlobAdvisor",
+ *   getChat: async (args) => `Received blob of size: ${args.message.size}`
+ * });
 */
 function addAdvisor(advisorSchema) {
     return addAdvisorInternal(advisorSchema);
@@ -19367,7 +19393,7 @@ function overrideMCP(mcpSchema) {
 const METHOD_NAME$X = "function.test.overrideAdvisor";
 /**
  * Function implementation
-*/
+ */
 const overrideAdvisorInternal = beginContext((publicAdvisorSchema) => {
     GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
         swarm$1.loggerService.log(METHOD_NAME$X, {
@@ -19381,20 +19407,29 @@ const overrideAdvisorInternal = beginContext((publicAdvisorSchema) => {
  * This function updates the configuration of an advisor identified by its `advisorName`, applying the provided schema properties.
  * It operates outside any existing method or execution contexts to ensure isolation, leveraging `beginContext` for a clean execution scope.
  * Logs the override operation if logging is enabled in the global configuration.
+ * Only the provided properties will be updated - omitted properties remain unchanged.
  *
- *
- * @param {TAdvisorSchema} advisorSchema - The schema definition for advisor.
+ * @function overrideAdvisor
+ * @template T - The type of message content the advisor accepts (defaults to string). Can be a custom object, Blob, or string.
+ * @param {TAdvisorSchema<T>} advisorSchema - Partial schema definition for advisor. Must include `advisorName`, other properties are optional.
+ * @returns {IAdvisorSchema<T>} The updated complete advisor schema.
  * @throws {Error} If the advisor schema service encounters an error during the override operation (e.g., invalid advisorName or schema).
  *
  * @example
- * // Override an advisor's schema with new properties
+ * // Override advisor's description only
  * overrideAdvisor({
  *   advisorName: "KnowledgeBase",
- *   description: "Updated knowledge repository",
- *   storage: "AdvisorStorage",
+ *   docDescription: "Updated knowledge repository",
  * });
- * // Logs the operation (if enabled) and updates the advisor schema in the swarm.
-*/
+ *
+ * @example
+ * // Override advisor with custom message type
+ * interface CustomMessage { query: string; context: string[] }
+ * overrideAdvisor<CustomMessage>({
+ *   advisorName: "StructuredAdvisor",
+ *   getChat: async (args) => `Query: ${args.message.query}`
+ * });
+ */
 function overrideAdvisor(advisorSchema) {
     return overrideAdvisorInternal(advisorSchema);
 }
@@ -20125,11 +20160,33 @@ const askInternal = beginContext(async (message, advisorName, images = []) => {
     return await getChat(args);
 });
 /**
- * Initiates an ask process within a chat context
+ * Initiates an ask process within a chat context.
+ * Sends a message to the specified advisor and returns the chat response.
+ * Supports custom message types including objects, Blob, or string.
+ *
  * @function ask
- * @param {string} message - The message content to process or send.
- * @param {AdvisorName} advisorName - The name of the advisor.
- * @param {Image[]} [images] - Optional array of images (as Uint8Array or string).
+ * @template T - The type of message content (defaults to string). Can be a custom object, Blob, or string.
+ * @param {T} message - The message content to process or send. Type should match the advisor's expected message type.
+ * @param {AdvisorName} advisorName - The name of the advisor to handle the message.
+ * @param {Image[]} [images] - Optional array of images (as Uint8Array or string) to accompany the message.
+ * @returns {Promise<string>} The response from the advisor's chat handler.
+ *
+ * @example
+ * // Using default string message type
+ * const response = await ask("Hello", "TextAdvisor");
+ *
+ * @example
+ * // Using custom message type
+ * interface CustomMessage { text: string; priority: number }
+ * const response = await ask<CustomMessage>(
+ *   { text: "Important", priority: 1 },
+ *   "StructuredAdvisor"
+ * );
+ *
+ * @example
+ * // Using Blob message type with images
+ * const blob = new Blob(["data"], { type: "text/plain" });
+ * const response = await ask<Blob>(blob, "BlobAdvisor", [imageData]);
 */
 async function ask(message, advisorName, images) {
     return await askInternal(message, advisorName, images);

package/build/index.mjs

@@ -18545,9 +18545,35 @@ const addAdvisorInternal = beginContext((advisorSchema) => {
     return advisorSchema.advisorName;
 });
 /**
- * Adds an advisor schema to the system
+ * Adds an advisor schema to the system.
+ * Registers the advisor with validation and schema services, making it available for chat operations.
+ *
  * @function addAdvisor
- * @param {IAdvisorSchema} advisorSchema - The schema definition for advisor.
+ * @template T - The type of message content the advisor accepts (defaults to string). Can be a custom object, Blob, or string.
+ * @param {IAdvisorSchema<T>} advisorSchema - The schema definition for advisor, including name, chat handler, and optional callbacks.
+ * @returns {string} The advisorName that was registered.
+ *
+ * @example
+ * // Using default string message type
+ * addAdvisor({
+ *   advisorName: "TextAdvisor",
+ *   getChat: async (args) => `Response to: ${args.message}`
+ * });
+ *
+ * @example
+ * // Using custom message type
+ * interface CustomMessage { text: string; metadata: Record<string, any> }
+ * addAdvisor<CustomMessage>({
+ *   advisorName: "StructuredAdvisor",
+ *   getChat: async (args) => `Processing: ${args.message.text}`
+ * });
+ *
+ * @example
+ * // Using Blob message type
+ * addAdvisor<Blob>({
+ *   advisorName: "BlobAdvisor",
+ *   getChat: async (args) => `Received blob of size: ${args.message.size}`
+ * });
 */
 function addAdvisor(advisorSchema) {
     return addAdvisorInternal(advisorSchema);
@@ -19347,7 +19373,7 @@ function overrideMCP(mcpSchema) {
 const METHOD_NAME$X = "function.test.overrideAdvisor";
 /**
  * Function implementation
-*/
+ */
 const overrideAdvisorInternal = beginContext((publicAdvisorSchema) => {
     GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
         swarm$1.loggerService.log(METHOD_NAME$X, {
@@ -19361,20 +19387,29 @@ const overrideAdvisorInternal = beginContext((publicAdvisorSchema) => {
  * This function updates the configuration of an advisor identified by its `advisorName`, applying the provided schema properties.
  * It operates outside any existing method or execution contexts to ensure isolation, leveraging `beginContext` for a clean execution scope.
  * Logs the override operation if logging is enabled in the global configuration.
+ * Only the provided properties will be updated - omitted properties remain unchanged.
  *
- *
- * @param {TAdvisorSchema} advisorSchema - The schema definition for advisor.
+ * @function overrideAdvisor
+ * @template T - The type of message content the advisor accepts (defaults to string). Can be a custom object, Blob, or string.
+ * @param {TAdvisorSchema<T>} advisorSchema - Partial schema definition for advisor. Must include `advisorName`, other properties are optional.
+ * @returns {IAdvisorSchema<T>} The updated complete advisor schema.
  * @throws {Error} If the advisor schema service encounters an error during the override operation (e.g., invalid advisorName or schema).
  *
  * @example
- * // Override an advisor's schema with new properties
+ * // Override advisor's description only
  * overrideAdvisor({
  *   advisorName: "KnowledgeBase",
- *   description: "Updated knowledge repository",
- *   storage: "AdvisorStorage",
+ *   docDescription: "Updated knowledge repository",
  * });
- * // Logs the operation (if enabled) and updates the advisor schema in the swarm.
-*/
+ *
+ * @example
+ * // Override advisor with custom message type
+ * interface CustomMessage { query: string; context: string[] }
+ * overrideAdvisor<CustomMessage>({
+ *   advisorName: "StructuredAdvisor",
+ *   getChat: async (args) => `Query: ${args.message.query}`
+ * });
+ */
 function overrideAdvisor(advisorSchema) {
     return overrideAdvisorInternal(advisorSchema);
 }
@@ -20105,11 +20140,33 @@ const askInternal = beginContext(async (message, advisorName, images = []) => {
     return await getChat(args);
 });
 /**
- * Initiates an ask process within a chat context
+ * Initiates an ask process within a chat context.
+ * Sends a message to the specified advisor and returns the chat response.
+ * Supports custom message types including objects, Blob, or string.
+ *
  * @function ask
- * @param {string} message - The message content to process or send.
- * @param {AdvisorName} advisorName - The name of the advisor.
- * @param {Image[]} [images] - Optional array of images (as Uint8Array or string).
+ * @template T - The type of message content (defaults to string). Can be a custom object, Blob, or string.
+ * @param {T} message - The message content to process or send. Type should match the advisor's expected message type.
+ * @param {AdvisorName} advisorName - The name of the advisor to handle the message.
+ * @param {Image[]} [images] - Optional array of images (as Uint8Array or string) to accompany the message.
+ * @returns {Promise<string>} The response from the advisor's chat handler.
+ *
+ * @example
+ * // Using default string message type
+ * const response = await ask("Hello", "TextAdvisor");
+ *
+ * @example
+ * // Using custom message type
+ * interface CustomMessage { text: string; priority: number }
+ * const response = await ask<CustomMessage>(
+ *   { text: "Important", priority: 1 },
+ *   "StructuredAdvisor"
+ * );
+ *
+ * @example
+ * // Using Blob message type with images
+ * const blob = new Blob(["data"], { type: "text/plain" });
+ * const response = await ask<Blob>(blob, "BlobAdvisor", [imageData]);
 */
 async function ask(message, advisorName, images) {
     return await askInternal(message, advisorName, images);

package/package.json

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

package/types.d.ts

@@ -2752,7 +2752,7 @@ interface IOutlineSchema<Data extends IOutlineData = IOutlineData, Param extends
      * If a function is provided, it may return a string or a Promise resolving to a string.
      * This prompt is typically sent to the completion engine or model to guide the generation process.
      */
-    prompt: string | ((outlineName: OutlineName) => (string | Promise<string>));
+    prompt?: string | ((outlineName: OutlineName) => (string | Promise<string>));
     /**
      * The system prompt(s) provided to the language model for the outline operation.
      * Can be a static array of strings or a function that generates the system prompts dynamically based on the outline name.
@@ -4143,19 +4143,19 @@ type Image$1 = Uint8Array | string;
  * @interface IAdvisorCallbacks
  * Callback functions for advisor operations
 */
-interface IAdvisorCallbacks {
+interface IAdvisorCallbacks<T = string> {
     /**
      * Optional callback triggered when a chat operation occurs
     */
-    onChat?: (args: IChatArgs) => void;
+    onChat?: (args: IChatArgs<T>) => void;
 }
 /**
  * @interface IChatArgs
  * Arguments required for chat operations
 */
-interface IChatArgs {
+interface IChatArgs<T = string> {
     /** Message content for the chat*/
-    message: string;
+    message: T;
     /** Optional array of images associated with the chat. */
     images?: Image$1[];
 }
@@ -4163,17 +4163,17 @@ interface IChatArgs {
  * @interface IAdvisorSchema
  * Schema definition for advisor configuration
 */
-interface IAdvisorSchema {
+interface IAdvisorSchema<T = string> {
     /** Optional description of the advisor documentation*/
     docDescription?: string;
     /** Name identifier for the advisor*/
     advisorName: AdvisorName;
     /**
      * Function to get chat response
-    */
-    getChat(args: IChatArgs): Promise<string>;
+     */
+    getChat(args: IChatArgs<T>): Promise<string>;
     /** Optional callbacks for advisor operations*/
-    callbacks?: IAdvisorCallbacks;
+    callbacks?: IAdvisorCallbacks<T>;
 }
 /**
  * Type alias for advisor name identifier.
@@ -8239,7 +8239,7 @@ declare class AdvisorSchemaService {
      * @public
      * Logs the override operation and updates the registry with the new schema
      */
-    override: (key: AdvisorName, value: Partial<IAdvisorSchema>) => IAdvisorSchema;
+    override: (key: AdvisorName, value: Partial<IAdvisorSchema>) => IAdvisorSchema<string>;
     /**
      * Retrieves an advisor schema by key
      * @public
@@ -10296,11 +10296,37 @@ interface IFetchInfoToolParams<T = Record<string, any>> extends IFetchInfoParams
 declare function addFetchInfo<T = Record<string, any>>(params: IFetchInfoToolParams<T>): string;
 
 /**
- * Adds an advisor schema to the system
+ * Adds an advisor schema to the system.
+ * Registers the advisor with validation and schema services, making it available for chat operations.
+ *
  * @function addAdvisor
- * @param {IAdvisorSchema} advisorSchema - The schema definition for advisor.
+ * @template T - The type of message content the advisor accepts (defaults to string). Can be a custom object, Blob, or string.
+ * @param {IAdvisorSchema<T>} advisorSchema - The schema definition for advisor, including name, chat handler, and optional callbacks.
+ * @returns {string} The advisorName that was registered.
+ *
+ * @example
+ * // Using default string message type
+ * addAdvisor({
+ *   advisorName: "TextAdvisor",
+ *   getChat: async (args) => `Response to: ${args.message}`
+ * });
+ *
+ * @example
+ * // Using custom message type
+ * interface CustomMessage { text: string; metadata: Record<string, any> }
+ * addAdvisor<CustomMessage>({
+ *   advisorName: "StructuredAdvisor",
+ *   getChat: async (args) => `Processing: ${args.message.text}`
+ * });
+ *
+ * @example
+ * // Using Blob message type
+ * addAdvisor<Blob>({
+ *   advisorName: "BlobAdvisor",
+ *   getChat: async (args) => `Received blob of size: ${args.message.size}`
+ * });
 */
-declare function addAdvisor(advisorSchema: IAdvisorSchema): string;
+declare function addAdvisor<T = string>(advisorSchema: IAdvisorSchema<T>): string;
 
 /**
  * Adds a new agent to the agent registry for use within the swarm system.
@@ -10737,30 +10763,39 @@ declare function overrideMCP(mcpSchema: TMCPSchema): IMCPSchema;
 /**
  * Type representing a partial advisor schema configuration.
  * Used for advisor service configuration with optional properties.
-*/
-type TAdvisorSchema = {
-    advisorName: IAdvisorSchema["advisorName"];
-} & Partial<IAdvisorSchema>;
+ */
+type TAdvisorSchema<T = string> = {
+    advisorName: IAdvisorSchema<T>["advisorName"];
+} & Partial<IAdvisorSchema<T>>;
 /**
  * Overrides an existing advisor schema in the swarm system with a new or partial schema.
  * This function updates the configuration of an advisor identified by its `advisorName`, applying the provided schema properties.
  * It operates outside any existing method or execution contexts to ensure isolation, leveraging `beginContext` for a clean execution scope.
  * Logs the override operation if logging is enabled in the global configuration.
+ * Only the provided properties will be updated - omitted properties remain unchanged.
  *
- *
- * @param {TAdvisorSchema} advisorSchema - The schema definition for advisor.
+ * @function overrideAdvisor
+ * @template T - The type of message content the advisor accepts (defaults to string). Can be a custom object, Blob, or string.
+ * @param {TAdvisorSchema<T>} advisorSchema - Partial schema definition for advisor. Must include `advisorName`, other properties are optional.
+ * @returns {IAdvisorSchema<T>} The updated complete advisor schema.
  * @throws {Error} If the advisor schema service encounters an error during the override operation (e.g., invalid advisorName or schema).
  *
  * @example
- * // Override an advisor's schema with new properties
+ * // Override advisor's description only
  * overrideAdvisor({
  *   advisorName: "KnowledgeBase",
- *   description: "Updated knowledge repository",
- *   storage: "AdvisorStorage",
+ *   docDescription: "Updated knowledge repository",
  * });
- * // Logs the operation (if enabled) and updates the advisor schema in the swarm.
-*/
-declare function overrideAdvisor(advisorSchema: TAdvisorSchema): IAdvisorSchema;
+ *
+ * @example
+ * // Override advisor with custom message type
+ * interface CustomMessage { query: string; context: string[] }
+ * overrideAdvisor<CustomMessage>({
+ *   advisorName: "StructuredAdvisor",
+ *   getChat: async (args) => `Query: ${args.message.query}`
+ * });
+ */
+declare function overrideAdvisor<T = string>(advisorSchema: TAdvisorSchema<T>): TAdvisorSchema<T>;
 
 /**
  * @module overrideCompute
@@ -11184,13 +11219,35 @@ declare function executeForce(content: string, clientId: string): Promise<string
 /** Image type as either an array of Uint8Array or an array of strings */
 type Image = Uint8Array | string;
 /**
- * Initiates an ask process within a chat context
+ * Initiates an ask process within a chat context.
+ * Sends a message to the specified advisor and returns the chat response.
+ * Supports custom message types including objects, Blob, or string.
+ *
  * @function ask
- * @param {string} message - The message content to process or send.
- * @param {AdvisorName} advisorName - The name of the advisor.
- * @param {Image[]} [images] - Optional array of images (as Uint8Array or string).
+ * @template T - The type of message content (defaults to string). Can be a custom object, Blob, or string.
+ * @param {T} message - The message content to process or send. Type should match the advisor's expected message type.
+ * @param {AdvisorName} advisorName - The name of the advisor to handle the message.
+ * @param {Image[]} [images] - Optional array of images (as Uint8Array or string) to accompany the message.
+ * @returns {Promise<string>} The response from the advisor's chat handler.
+ *
+ * @example
+ * // Using default string message type
+ * const response = await ask("Hello", "TextAdvisor");
+ *
+ * @example
+ * // Using custom message type
+ * interface CustomMessage { text: string; priority: number }
+ * const response = await ask<CustomMessage>(
+ *   { text: "Important", priority: 1 },
+ *   "StructuredAdvisor"
+ * );
+ *
+ * @example
+ * // Using Blob message type with images
+ * const blob = new Blob(["data"], { type: "text/plain" });
+ * const response = await ask<Blob>(blob, "BlobAdvisor", [imageData]);
 */
-declare function ask(message: string, advisorName: AdvisorName, images?: Image[]): Promise<string>;
+declare function ask<T = string>(message: T, advisorName: AdvisorName, images?: Image[]): Promise<string>;
 
 /**
  * Processes an outline request to generate structured JSON data based on a specified outline schema.
@@ -11903,7 +11960,7 @@ declare function getTool(toolName: ToolName): IAgentTool<Record<string, ToolValu
  * @function getAdvisor
  * @param {AdvisorName} advisorName - The name of the advisor.
 */
-declare function getAdvisor(advisorName: AdvisorName): IAdvisorSchema;
+declare function getAdvisor(advisorName: AdvisorName): IAdvisorSchema<string>;
 
 /**
  * Retrieves the raw, unmodified history for a given client session.